Switch

An immediate on/off. The difference from a Checkbox is not visual, it is temporal.

import { Switch } from 'neba';

<Switch label="Email alerts" defaultChecked />;

Props

Prop	Type	Default	Description
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Height and type scale
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. Arbitrary colour values are not accepted
label	ReactNode	—	The label, wired to the control by Base UI's Field
description	ReactNode	—	Helper text
error	ReactNode	—	Error message. Its presence turns the control invalid and re-points the colour family at danger
invalid	boolean	!!error	Forces the invalid state without a message, for when a form library owns validity
checked	boolean	—	Whether it is on. Use with onCheckedChange for a controlled switch
defaultChecked	boolean	false	The initial state, for an uncontrolled switch
onCheckedChange	(checked: boolean, details) => void	—	Called when the switch is turned on or off
labelPlacement	'start' | 'end'	'end'	Which side the label sits on. `start` is for a settings list, where the switches line up on the right
name	string	—	Identifies the field when a form is submitted
readOnly	boolean	false	Shown but not changeable. Keeps its colour and edge, drains the saturation
disabled	boolean	false	Unavailable. Drops the colour family for neutral grey

Switch or checkbox?

A checkbox is a value that gets submitted with a form. A switch takes effect the moment it moves. If there is a Save button underneath it, it should have been a checkbox.

Examples

States

import { Switch } from 'neba';

export default function SwitchStates() {
  return (
    <div className="flex flex-col gap-3">
      <Switch label="Off" />
      <Switch label="On" defaultChecked />
      <Switch label="Read-only" readOnly defaultChecked />
      <Switch label="Disabled" disabled />
      <Switch label="Disabled and on" disabled defaultChecked />
    </div>
  );
}

Label placement

end reads as a caption for the control. start is for a settings list, where the labels form a column and every switch lines up on the right.

import { Switch } from 'neba';

export default function SwitchPlacement() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <Switch
        labelPlacement="start"
        label="Two-factor authentication"
        description="Required for admins."
        defaultChecked
      />
      <Switch labelPlacement="start" label="Session timeout" description="After 30 minutes." />
    </div>
  );
}

Sizes

import { Switch } from 'neba';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function SwitchSizes() {
  return (
    <div className="flex flex-col gap-3">
      {SIZES.map((size) => (
        <Switch key={size} size={size} label={size} defaultChecked />
      ))}
    </div>
  );
}

The two rules it bends

It is a pill. Everywhere else the radius stops short of 50%, because the flat run along the top and bottom edge is what reads as a sheet with its corners cut off. A switch is not a sheet — it is a track something runs along, and a track with corners is a track the thumb would have to climb out of.

Something moves. This is the only component in the library where anything travels, and it travels on left, not on a transform. The no-transform rule exists because scaling a control resamples its label; the thumb carries no text, and its movement is the control. Under prefers-reduced-motion the travel drops to 0ms with everything else.

Accessibility

• Renders a real role="switch" with a hidden <input> beside it.
• The label is wired to the control by Base UI's Field: clicking the text flips it.
• Without a label, give it an aria-label.