Switch
switchToggles a binary setting with a compact track-and-thumb control.
Usage
Basic usage
Off by default, click the toggle switch.
tsx
<Switch aria-label="Switch" />Enabled by default
For uncontrolled writing, use defaultChecked to set the initial open state.
tsx
<Switch defaultChecked aria-label="Switch" />Disabled
disabled Lock switch, both off/on states can be disabled.
tsx
<>
<Switch disabled aria-label="Disable-Off" />
<Switch disabled defaultChecked aria-label="Disable-On" />
</>With caption
Use label to associate copywriting, and you can switch by clicking on the text.
tsx
<label className="inline-flex items-center gap-2">
<Switch defaultChecked aria-label="Receive notification" />
<span className="text-sm text-foreground">Receive notification</span>
</label>When to use
Use Switch for a Boolean setting that takes effect immediately, such as enabling notifications, without waiting for form submission. Use Radio for two mutually exclusive choices with equal semantic weight, or Checkbox for a Boolean field submitted with a form, such as accepting terms.
Import
ts
import { Switch } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| checked | boolean | — | Checked state in controlled mode. |
| defaultChecked | boolean | false | Initial checked state in uncontrolled mode. |
| disabled | boolean | false | Whether to disable the switch. |
| id | string | — | HTML identifier used to associate the switch with a label. |
| className | string | — | Additional class name for the switch root. |
| aria-label | string | — | Accessible label when no visible label is present. |
| size | "sm" | "md" | "lg" | "md" | Visual size: 36×20, 40×24, or 48×28 px. The default md size preserves the original dimensions. |
| touchTarget | boolean | false | Expands the invisible hit area to at least 44 px without changing layout or appearance; enable it for touch interfaces when spacing permits. |
Events
| Event | Type | Description |
|---|---|---|
| onCheckedChange | (checked: boolean) => void | Called with the new checked state. |
Example
tsx
<Switch defaultChecked aria-label="Turn on notifications" />Controlled usage:
tsx
const [on, setOn] = useState(false);
<Switch checked={on} onCheckedChange={setOn} aria-label="Turn on notifications" />Usage guidelines
- Pair controlled
checkedwithonCheckedChange. UsedefaultCheckedonly for uncontrolled initial state; do not mix the two patterns. - Provide
aria-labelwhen there is no visible label so assistive technology can identify the control. - Enable `touchTarget` on mobile. The default
mdtrack is only 24 px high, below the recommended 44 px touch target; the invisible expansion improves finger accuracy without changing layout. - The expanded hit area extends about 10 px above and below. In a dense desktop form it may overlap nearby controls, so the option is off by default and should be enabled by context.
Related
Input · Textarea · Select · Checkbox · CheckboxGroup · Radio
Playground
<Switch />