Koala UI

Switch

A toggle for an instant, self-applying boolean, built on Radix Switch. Use it for settings that take effect immediately (notifications, airplane mode); reach for a Checkbox when the choice is submitted with a form.

Installation#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Add this component (its dependencies come along)npx koalaui-cli@latest add switch

Usage#

usage.tsxTSX
import { Switch } from "@/components/ui/switch"export function Example() {  return (    <label htmlFor="airplane" className="flex items-center gap-2.5">      <Switch id="airplane" defaultChecked />      Airplane mode    </label>  )}

States#

Off rests on the input fill; on slides the thumb across a primary (ink) track. The thumb carries a shadow so it reads on both states in every theme.

Off
On
Disabled
Disabled on

Controlled#

Drive the switch from state with checked and onCheckedChange, or leave it uncontrolled with defaultChecked.

Enabled

In a settings list#

The common shell: a label and description on the left, the switch trailing right. The whole row is the label, so the full width is the hit target.

API reference#

Switch

The control, Radix Switch.Root rendering a <button> with its thumb inside. Forwards all Radix Root props; every part accepts className, merged last. Inside a Field it takes the field's id, disabled and aria-describedby unless you pass your own.

PropTypeDefaultDescription
checkedboolean-Controlled on state.
defaultCheckedbooleanfalseInitial on state when uncontrolled.
onCheckedChange(checked: boolean) => void-Called when the switch toggles.
disabledbooleanfalseBlocks interaction and dims the control. Falls back to the surrounding Field.
requiredbooleanfalseMarks the hidden form input as required.
namestring-Name of the hidden input submitted with a form.
valuestring"on"Value submitted with a form when on.
staticbooleanfalseKept for compatibility; controls no longer scale on press.
Data attributeDescription
data-state"checked" or "unchecked", on the track and the thumb.
data-disabledPresent when disabled.

SwitchIndicator

The switch's drawing without the control: an aria-hidden <span> for a row that owns the toggle itself (a menu checkbox item, a MultiSelect option). Forwards all native <span> props.

PropTypeDefaultDescription
checked*boolean-Which state to paint.
Data attributeDescription
data-state"checked" or "unchecked".

switchVariants

The tv recipe behind both parts, with root and thumb slots, for styling a control of your own to match.

FAQ#

Use a Switch for an instant, self-applying boolean that takes effect immediately, like notifications or airplane mode. Reach for a Checkbox when the choice is only submitted later with a form.