Search docs

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>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/switch

Anatomy#

import { Switch } from '@leve-ui/switch'; // or '@leve-ui/core'

<Switch.Root>
  <Switch.Label />
  <Switch.Control>
    <Switch.Thumb />
  </Switch.Control>
  <Switch.HiddenInput />
</Switch.Root>
PartElementDescription
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.

Disabled#

disabled on the Root disables the switch.

Form#

Add Switch.HiddenInput with name to submit the state with a native <form>. The value is sent only while the switch is on.

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.

Use a dark color scheme.

API Reference#

Root#

PropDefaultType
ids–{ control?: string; label?: string }

Overrides the element IDs of the parts. Only used outside a Field.

defaultCheckedfalseboolean

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.

disabledfalseboolean

Disables the switch. Inside a Field, the Field's disabled also applies.

requiredfalseboolean

Marks the switch as required. Inside a Field, the Field's required also applies.

Also accepts all <div> attributes.

Data attributeValue
data-leve-switchAlways present
data-state"checked" | "unchecked"
data-disabledPresent 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 attributeValue
data-leve-switch-labelAlways present
data-state"checked" | "unchecked"
data-disabledPresent when disabled

Control#

No props of its own. Accepts all <button> attributes.

Data attributeValue
data-leve-switch-controlAlways present
data-state"checked" | "unchecked"
data-disabledPresent when disabled
data-invalidPresent when the Field is invalid

Thumb#

No props of its own. Accepts all <span> attributes.

Data attributeValue
data-leve-switch-thumbAlways present
data-state"checked" | "unchecked"
data-disabledPresent 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 attributeValue
data-leve-switch-hidden-inputAlways present
data-state"checked" | "unchecked"
data-disabledPresent 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, or aria-label / aria-labelledby on Switch.Control.
  • Switch.Control is a <button type="button"> with role="switch" and aria-checked ("true" or "false"), and aria-required when required. Inside a Field it also renders aria-describedby and aria-invalid. When disabled, it uses the native disabled attribute, so it is not focusable.
  • Do not change the label text with the state. The state is conveyed by aria-checked.
  • Switch.Thumb and Switch.HiddenInput are hidden from assistive technologies with aria-hidden="true". The hidden input is not in the tab sequence.

Keyboard Interactions#

KeyDescription
SpaceTurns the switch on or off.
EnterTurns the switch on or off.