Switch
A control that turns an option on or off.
Switch follows the Switch WAI-ARIA design pattern.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Switch } from '@leve-ui/switch';
import styles from './default.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Switch.Root class="switch-default-root">
<Switch.Label class="switch-default-label">Airplane mode</Switch.Label>
<Switch.Control class="switch-default-control">
<Switch.Thumb class="switch-default-thumb" />
</Switch.Control>
</Switch.Root>
);
});.switch-default-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
justify-content: space-between;
gap: 12px;
min-width: 200px;
font-family: inherit;
}
.switch-default-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.switch-default-control {
display: inline-flex;
align-items: center;
flex-shrink: 0;
width: 36px;
height: 20px;
padding: 2px;
border: none;
border-radius: 9999px;
background: light-dark(#cbd5e1, #ffffff3d);
cursor: pointer;
}
.switch-default-control[data-state="checked"] {
background: #009dfd;
}
.switch-default-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.switch-default-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
.switch-default-thumb {
display: block;
width: 16px;
height: 16px;
border-radius: 9999px;
background: #ffffff;
box-shadow: 0 1px 2px rgb(15 23 42 / 0.2);
transition: transform 150ms ease;
}
.switch-default-thumb[data-state="checked"] {
transform: translateX(16px);
}Installation#
Install the individual package, or use @leve-ui/core to get every component at once:
pnpm add @leve-ui/switchnpm install @leve-ui/switchyarn add @leve-ui/switchbun add @leve-ui/switchpnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/coreAnatomy#
import { Switch } from '@leve-ui/switch'; // or '@leve-ui/core'
<Switch.Root>
<Switch.Label />
<Switch.Control>
<Switch.Thumb />
</Switch.Control>
<Switch.HiddenInput />
</Switch.Root>
| Part | Element | Description |
|---|---|---|
Switch.Root | <div> | Wraps the parts and holds the on/off state. Not interactive. |
Switch.Label | <label> | The label. Clicking it toggles the switch. |
Switch.Control | <button> | The switch itself, with role="switch". |
Switch.Thumb | <span> | The thumb inside the control. Decorative. |
Switch.HiddenInput | <input type="checkbox"> | Optional. Sends the state with a native <form>. |
Examples#
Checked#
defaultChecked turns the switch on initially.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Switch } from '@leve-ui/switch';
import styles from './checked.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Switch.Root defaultChecked class="switch-checked-root">
<Switch.Label class="switch-checked-label">Wi-Fi</Switch.Label>
<Switch.Control class="switch-checked-control">
<Switch.Thumb class="switch-checked-thumb" />
</Switch.Control>
</Switch.Root>
);
});.switch-checked-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
justify-content: space-between;
gap: 12px;
min-width: 200px;
font-family: inherit;
}
.switch-checked-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.switch-checked-control {
display: inline-flex;
align-items: center;
flex-shrink: 0;
width: 36px;
height: 20px;
padding: 2px;
border: none;
border-radius: 9999px;
background: light-dark(#cbd5e1, #ffffff3d);
cursor: pointer;
}
.switch-checked-control[data-state="checked"] {
background: #009dfd;
}
.switch-checked-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.switch-checked-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
.switch-checked-thumb {
display: block;
width: 16px;
height: 16px;
border-radius: 9999px;
background: #ffffff;
box-shadow: 0 1px 2px rgb(15 23 42 / 0.2);
transition: transform 150ms ease;
}
.switch-checked-thumb[data-state="checked"] {
transform: translateX(16px);
}Disabled#
disabled on the Root disables the switch.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Switch } from '@leve-ui/switch';
import styles from './disabled.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Switch.Root disabled class="switch-disabled-root">
<Switch.Label class="switch-disabled-label">Bluetooth</Switch.Label>
<Switch.Control class="switch-disabled-control">
<Switch.Thumb class="switch-disabled-thumb" />
</Switch.Control>
</Switch.Root>
);
});.switch-disabled-root {
font-family: inherit;
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
justify-content: space-between;
gap: 12px;
min-width: 200px;
}
.switch-disabled-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.switch-disabled-control {
display: inline-flex;
align-items: center;
flex-shrink: 0;
width: 36px;
height: 20px;
padding: 2px;
border: none;
border-radius: 9999px;
background: light-dark(#cbd5e1, #ffffff3d);
cursor: pointer;
}
.switch-disabled-control[data-state="checked"] {
background: #009dfd;
}
.switch-disabled-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.switch-disabled-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
.switch-disabled-thumb {
display: block;
width: 16px;
height: 16px;
border-radius: 9999px;
background: #ffffff;
box-shadow: 0 1px 2px rgb(15 23 42 / 0.2);
transition: transform 150ms ease;
}
.switch-disabled-thumb[data-state="checked"] {
transform: translateX(16px);
}
.switch-disabled-label[data-disabled] {
opacity: 0.5;
cursor: not-allowed;
}Form#
Add Switch.HiddenInput with name to submit the state with a native <form>. The value is sent only while the switch is on.
import { $, component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Switch } from '@leve-ui/switch';
import styles from './form.css?inline';
export default component$(() => {
useStyles$(styles);
const submittedData = useSignal('');
const handleSubmit$ = $((_event: unknown, form: HTMLFormElement) => {
const formData = new FormData(form);
submittedData.value = JSON.stringify(Object.fromEntries(formData));
});
return (
<form class="switch-form-form" preventdefault:submit onSubmit$={handleSubmit$}>
<Switch.Root class="switch-form-root">
<Switch.Label class="switch-form-label">Notifications</Switch.Label>
<Switch.Control class="switch-form-control">
<Switch.Thumb class="switch-form-thumb" />
</Switch.Control>
<Switch.HiddenInput name="notifications" />
</Switch.Root>
<button type="submit" class="switch-form-submit">
Save
</button>
<output class="switch-form-output">{submittedData.value}</output>
</form>
);
});.switch-form-form {
display: flex;
flex-direction: column;
align-items: flex-start;
gap: 12px;
font-family: inherit;
}
.switch-form-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
justify-content: space-between;
gap: 12px;
min-width: 200px;
}
.switch-form-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.switch-form-control {
display: inline-flex;
align-items: center;
flex-shrink: 0;
width: 36px;
height: 20px;
padding: 2px;
border: none;
border-radius: 9999px;
background: light-dark(#cbd5e1, #ffffff3d);
cursor: pointer;
}
.switch-form-control[data-state="checked"] {
background: #009dfd;
}
.switch-form-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.switch-form-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
.switch-form-thumb {
display: block;
width: 16px;
height: 16px;
border-radius: 9999px;
background: #ffffff;
box-shadow: 0 1px 2px rgb(15 23 42 / 0.2);
transition: transform 150ms ease;
}
.switch-form-thumb[data-state="checked"] {
transform: translateX(16px);
}
.switch-form-submit {
height: 32px;
padding: 0 12px;
border: none;
border-radius: 6px;
background: #009dfd;
color: #ffffff;
font: inherit;
font-size: 13px;
font-weight: 500;
cursor: pointer;
}
.switch-form-submit:hover {
background: #006ce9;
}
.switch-form-submit:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.switch-form-output {
margin: 0;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}With Field#
Inside a Field.Root, use Field.Label instead of Switch.Label. The Field provides the IDs, the description and the disabled / required / invalid states.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Field } from '@leve-ui/field';
import { Switch } from '@leve-ui/switch';
import styles from './with-field.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Field.Root hasDescription class="switch-with-field-field">
<div class="switch-with-field-row">
<Field.Label class="switch-with-field-label">Dark mode</Field.Label>
<Switch.Root class="switch-with-field-root">
<Switch.Control class="switch-with-field-control">
<Switch.Thumb class="switch-with-field-thumb" />
</Switch.Control>
</Switch.Root>
</div>
<Field.Description class="switch-with-field-description">
Use a dark color scheme.
</Field.Description>
</Field.Root>
);
});.switch-with-field-field {
display: flex;
flex-direction: column;
gap: 6px;
width: 280px;
font-family: inherit;
}
.switch-with-field-row {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
}
.switch-with-field-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.switch-with-field-description {
margin: 0;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}
.switch-with-field-root {
display: inline-flex;
}
.switch-with-field-control {
display: inline-flex;
align-items: center;
flex-shrink: 0;
width: 36px;
height: 20px;
padding: 2px;
border: none;
border-radius: 9999px;
background: light-dark(#cbd5e1, #ffffff3d);
cursor: pointer;
}
.switch-with-field-control[data-state="checked"] {
background: #009dfd;
}
.switch-with-field-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.switch-with-field-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
.switch-with-field-thumb {
display: block;
width: 16px;
height: 16px;
border-radius: 9999px;
background: #ffffff;
box-shadow: 0 1px 2px rgb(15 23 42 / 0.2);
transition: transform 150ms ease;
}
.switch-with-field-thumb[data-state="checked"] {
transform: translateX(16px);
}API Reference#
Root#
| Prop | Default | Type |
|---|---|---|
| ids | – | { control?: string; label?: string } Overrides the element IDs of the parts. Only used outside a Field. |
| defaultChecked | false | boolean Whether the switch is on initially (uncontrolled). |
| bind:checked | – | Signal<boolean> A signal with the on/off state (controlled). |
| onCheckedChange$ | – | QRL<(checked: boolean) => void> Called when the user turns the switch on or off. |
| disabled | false | boolean Disables the switch. Inside a Field, the Field's |
| required | false | boolean Marks the switch as required. Inside a Field, the Field's |
Also accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-switch | Always present |
data-state | "checked" | "unchecked" |
data-disabled | Present when disabled |
The state is uncontrolled with defaultChecked, or controlled with bind:checked. onCheckedChange$ is called when the user turns the switch on or off.
Inside a Field, the IDs come from the Field and ids is ignored (ADR 0024).
Label#
No props of its own. Accepts all <label> attributes.
| Data attribute | Value |
|---|---|
data-leve-switch-label | Always present |
data-state | "checked" | "unchecked" |
data-disabled | Present when disabled |
Control#
No props of its own. Accepts all <button> attributes.
| Data attribute | Value |
|---|---|
data-leve-switch-control | Always present |
data-state | "checked" | "unchecked" |
data-disabled | Present when disabled |
data-invalid | Present when the Field is invalid |
Thumb#
No props of its own. Accepts all <span> attributes.
| Data attribute | Value |
|---|---|
data-leve-switch-thumb | Always present |
data-state | "checked" | "unchecked" |
data-disabled | Present when disabled |
Move the thumb with CSS, for example [data-leve-switch-thumb][data-state="checked"].
HiddenInput#
No props of its own. Accepts all <input> attributes.
| Data attribute | Value |
|---|---|
data-leve-switch-hidden-input | Always present |
data-state | "checked" | "unchecked" |
data-disabled | Present when disabled |
The hidden input follows the checked, required and disabled states, so native form submission and required validation work (ADR 0026). It is positioned absolutely with an inline style, so give Switch.Root position: relative.
Accessibility#
Complies with the Switch WAI-ARIA design pattern.
- Name the switch with
Switch.Label,Field.Label, oraria-label/aria-labelledbyonSwitch.Control. Switch.Controlis a<button type="button">withrole="switch"andaria-checked("true"or"false"), andaria-requiredwhen required. Inside a Field it also rendersaria-describedbyandaria-invalid. When disabled, it uses the nativedisabledattribute, so it is not focusable.- Do not change the label text with the state. The state is conveyed by
aria-checked. Switch.ThumbandSwitch.HiddenInputare hidden from assistive technologies witharia-hidden="true". The hidden input is not in the tab sequence.
Keyboard Interactions#
| Key | Description |
|---|---|
Space | Turns the switch on or off. |
Enter | Turns the switch on or off. |