Components
Switch
On/off control that applies a setting right away
Overview
Switch turns a setting on or off immediately, without a save button. It renders a button with the switch role, so screen readers announce it as a switch and read whether it is on or off.
Give it a name. When there is visible text next to it, point to that text with aria-labelledby. Otherwise use aria-label.
States
Both states keep at least 3:1 contrast against the background: the off track has a visible border and thumb, and the on track uses the brand color.
Props
| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
checked | boolean | - | Yes | true when on |
onCheckedChange | (checked: boolean) => void | - | No | Receives the value after the press (the opposite of the current one) |
disabled | boolean | false | No | Disabled |
aria-label | string | - | No | Accessible name. Use aria-labelledby when there is visible text next to it |
aria-labelledby | string | - | No | Id of the text that names it |
className | string | - | No | Extra CSS class |
ref | Ref<HTMLButtonElement> | - | No | Ref to the button element |
Specification
base
| 상태 | 요소 | 속성 | 값 |
|---|---|---|---|
| enabled | root | borderRadius | $size.radius.full |
| enabled | root | borderWidth | $size.stroke.border |
| enabled | root | borderColor | $color.border.default.secondary |
| enabled | root | backgroundColor | $color.background.default.default |
| enabled | root | width | 44px토큰 아님 — no sizing token scale |
| enabled | root | height | 24px토큰 아님 — no sizing token scale |
| enabled | thumb | backgroundColor | $color.icon.default.secondary |
| hover | root | backgroundColor | $color.background.default.defaultHover |
| checked | root | borderColor | $color.background.brand.default |
| checked | root | backgroundColor | $color.background.brand.default |
| checked | thumb | backgroundColor | $color.icon.brand.onBrand |
| disabled | root | borderColor | $color.border.disabled.default |
| disabled | root | backgroundColor | $color.background.disabled.default |
| disabled | thumb | backgroundColor | $color.icon.disabled.default |
| focusVisible | root | outlineWidth | $size.stroke.focus |
| focusVisible | root | outlineStyle | solid토큰 아님 — no line style token |
| focusVisible | root | outlineColor | $color.border.focus.default |
| focusVisible | root | outlineOffset | 2px토큰 아님 — no ring offset token |
Usage Guidelines
Do
- Use Switch for settings that take effect immediately
- Name it with the visible label next to it through
aria-labelledby
Don't
- Don't put the state in the name, such as Enable or Disable. The switch already announces on or off
- Don't use Switch for choices that need a submit button. Use a checkbox in a form