Switch

01Preview

Change the controls to try every supported combination. The switch is controlled here, so the code follows each click.

const [checked, setChecked] = useState(true)

<Switch
  label="Daily study reminder"
  description="A short nudge at 7 pm to keep your streak going."
  checked={checked}
  onCheckedChange={setChecked}
/>

02Installation

pnpm add @nuton/ui @nuton/tokens

npm install @nuton/ui @nuton/tokens

yarn add @nuton/ui @nuton/tokens

import '@nuton/tokens/tokens.css'
import '@nuton/ui/styles.css'

03Usage

import { Switch } from '@nuton/ui'

<Switch
  label="Daily reminders"
  description="A notification when you haven't studied today."
  defaultChecked
  onCheckedChange={(on) => savePreference('reminders', on)}
/>

• Use a switch when the change applies immediately, with no Save button. Inside a form that is submitted, use a Checkbox.
• It's a native <input type="checkbox" role="switch">: screen readers say “switch, on” or “off”, and name, value and forms work as usual.
• Name the setting, not the action: “Daily reminders”, not “Turn on daily reminders”. Don't change the label when the state changes.
• Use flip in settings lists so switches line up at the trailing edge.
• Give it a label, wrap it in a Field, or pass aria-label.

04Variants and sizes

Switch has one size (Figma 32 × 20). The variants are layout options for the label.

Label layouts

<Switch aria-label="Dark mode" />
<Switch label="Sound effects" />
<Switch label="Offline lessons" description="Downloads your next three lessons on Wi-Fi." />
<Switch label="Focus mode" badge={<Badge size="sm" color="blue" appearance="light">New</Badge>} flip />

05States and interactions

State tokens

Set on .nu-switch.

06Composition examples

Settings list

Each change saves straight away and is confirmed in a status message. Switches sit at the trailing edge with flip.

<ul aria-label="Study settings">
  {settings.map((s) => (
    <li key={s.key}>
      <Switch
        flip
        label={s.label}
        description={s.description}
        checked={on[s.key]}
        onCheckedChange={(v) => save(s.key, v)}
      />
    </li>
  ))}
</ul>
<p role="status">{message}</p>

Inside a Field

A Field gives the switch its label, hint and error, and passes disabled and the error state down.

<Field
  label="Share progress with my teacher"
  hint="Your teacher sees completed lessons and quiz scores, not your notes."
>
  <Switch checked={on} onCheckedChange={setOn} />
</Field>

07API reference

Props

Accessibility

You must: name every switch, apply the change straight away, and confirm saved changes with a status message or visible result.

Figma mapping

08Guidelines and related components

Do and don't

Related components

• CheckboxFor choices that are saved with a form.
• FieldLabel, hint and error for a switch in a form layout.
• DropdownMenu items with a switch indicator.