Switch

Switch represents an immediate boolean setting, where changing the value applies right away.

Import

import { Switch } from '@vellira-ui/react';

Storybook

Primitives/Switch - Default Open in Storybook

API

API details are generated from packages/react/API.md.

Prop	Type	Required	Description
accessibilityLabel	string	No	Accessible name announced by assistive technology.
checked	boolean	No	Controlled checked state.
defaultChecked	boolean	No	Initial checked state for uncontrolled usage.
disabled	boolean	No	Disables interaction.
required	boolean	No	Marks the control as required.
invalid	boolean	No	Marks the control as invalid.
onCheckedChange	(checked: boolean) => void	No	Called when the checked state changes.

When To Use

• Enable or disable notifications.
• Turn synchronization on or off.
• Enable a product feature.
• Toggle a persistent preference.
• Use Checkbox instead when the value is part of a form submission or represents an independent selection.

Accessibility

• Switch renders a native button with role='switch' and exposes its state with aria-checked.
• Provide a meaningful accessibilityLabel when surrounding content does not already make the purpose obvious.
• Do not rely on the default Switch label for production interfaces with multiple switches.
• Required, invalid, and disabled state are reflected through platform accessibility semantics.

See Also

• Checkbox - Checkbox for independent form selections.
• FormField - FormField for labels, descriptions, and validation layout.

Basic Usage

<Switch accessibilityLabel='Enable notifications' defaultChecked />

Controlled Usage

Use checked with onCheckedChange when application state owns the value.

import { Switch } from '@vellira-ui/react';
import { useState } from 'react';

export function NotificationsSetting() {
  const [enabled, setEnabled] = useState(false);

  return (
    <Switch
      accessibilityLabel='Enable notifications'
      checked={enabled}
      onCheckedChange={setEnabled}
    />
  );
}

Uncontrolled Usage

Use defaultChecked when the component can own its own state.

<Switch accessibilityLabel='Enable automatic updates' defaultChecked />

States

<Switch accessibilityLabel='Available setting' />

<Switch accessibilityLabel='Enabled setting' checked />

<Switch accessibilityLabel='Unavailable setting' disabled />

<Switch accessibilityLabel='Required setting' required />

<Switch accessibilityLabel='Invalid setting' invalid />

Web Accessibility Details

required maps to aria-required, invalid maps to aria-invalid, and disabled uses the native disabled button state.

<Switch
  accessibilityLabel='Use dark theme'
  checked={darkMode}
  onCheckedChange={setDarkMode}
/>

Platform Pair

• React Native Switch for the native implementation.