Switch
Also known as: Toggle, On/Off switch
Resources
Properties
| Property | Values | Default |
|---|---|---|
Size Variant | 2Xs | Xs | Sm | Sm |
Selected Boolean | true | false | false |
State Variant | Default | Hover | Focus | Disabled | Default |
Has start icon Boolean | true | false | false |
Start icon InstanceSwap | Any icon | heart |
Has end icon Boolean | true | false | false |
End icon InstanceSwap | Any icon | heart |
Has label Boolean | true | false | true |
Label Text | string | Label |
Label position Variant | Start | End | End |
When to use
If users need to make a binary action (on/off, switching color mode or enabling notifications).
When the setting doesn't require confirmation and takes effect immediately.
When multiple switches affect each other in a complex way, leading to confusion.
If user needs to take a non-binary action, such as choosing between "Daily" vs "Weekly" notifications, use radio button instead.
Behaviour
Selection
Switch has two selection states:
- Use
unselectedstate as default, when the setting is optional and user should enable it themselves or if most users are unlikely to need it on by default. - Use
selectedstate as default, when the setting is expected or recommended for must users, it’s a common practice (such as enable notifications), or if the switch represents a system default setting.
States
Switch (and all other forms and selection controls) express states. States indicate current condition of the component to someone interacting with it. Using states ensure clear user feedback, highlighting possible actions or barriers. We have included most common states:
| State | Context |
|---|---|
Default | Status of the component before the interaction. Also referred to as ‘resting’. |
Hover | When the user moves their cursor over the component, but is not taking the action. Slight visual change can indicate interactivity of the component. |
Focus | When user selects the component via keyboard navigation, but has not yet taken action on it. |
Disabled | A non-interactive state where the component appears faded or grayed out. It indicates that the action is unavailable at the moment. |
Size
Dimensions of the switch are tied to the global scale tokens. This ensures that the components, especially forms, with similar size settings remain consistent across the interface. scale tokens also provides more granular control over dimensional settings.
--scale-height-<size>
--scale-width-<size>
--scale-icon-size-<size>