# Switch

> An on/off toggle for settings that take effect immediately.

Category: Forms · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/switch

Use Switch for binary settings that apply as soon as they change, like enabling automatic deployment or two-factor authentication. If the change only applies when a form is submitted, use Checkbox instead.

## Import

```tsx
import { Switch } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { Switch } from '@bindshq/stance-react';

export function Basic() {
  return <Switch label="Automatic deployment" defaultChecked />;
}
```

### With description

```tsx
import { Switch } from '@bindshq/stance-react';

export function WithDescription() {
  return (
    <Switch
      label="Require two-factor authentication"
      description="All administrators must confirm sign-in with a second factor."
    />
  );
}
```

### Settings list

Label at the start aligns switches in a column.

```tsx
import * as React from 'react';
import { Switch } from '@bindshq/stance-react';

export function SettingsList() {
  const [settings, setSettings] = React.useState({
    banner: true,
    tracking: false,
    reminders: true,
  });
  const rows: { key: keyof typeof settings; label: string; description: string }[] = [
    {
      key: 'banner',
      label: 'Campaign banner',
      description: 'Show the current campaign below every signature.',
    },
    { key: 'tracking', label: 'Link tracking', description: 'Count clicks on signature links.' },
    {
      key: 'reminders',
      label: 'Signing reminders',
      description: 'Remind signers every three days.',
    },
  ];
  return (
    <div style={{ display: 'grid', gap: 20, width: '100%', maxWidth: 520 }}>
      {rows.map((r) => (
        <Switch
          key={r.key}
          label={r.label}
          description={r.description}
          labelPosition="start"
          style={{ justifyContent: 'space-between', width: '100%' }}
          checked={settings[r.key]}
          onCheckedChange={(v) => setSettings((s) => ({ ...s, [r.key]: v }))}
        />
      ))}
    </div>
  );
}
```

### Sizes and states

```tsx
import { FormField, Switch } from '@bindshq/stance-react';

export function States() {
  return (
    <div style={{ display: 'grid', gap: 14 }}>
      <Switch size="sm" label="Small" defaultChecked />
      <Switch label="Disabled" disabled />
      <Switch label="Disabled on" disabled defaultChecked />
      <FormField label="Single sign-on" description="Managed by your identity provider" readOnly>
        <Switch defaultChecked />
      </FormField>
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Switch | `checked` | `boolean` | None | Controlled state. |
| Switch | `defaultChecked` | `boolean` | `false` | Initial state. |
| Switch | `onCheckedChange` | `(checked: boolean) => void` | None | Called with the new state. |
| Switch | `label` | `ReactNode` | None | Visible label. Without it use aria-label or FormField. |
| Switch | `description` | `ReactNode` | None | Help text, linked via aria-describedby. |
| Switch | `size` | `'sm' \| 'md'` | `'md'` | Track size. |
| Switch | `labelPosition` | `'start' \| 'end'` | `'end'` | Label before or after the track. |
| Switch | `name / value` | `string` | `value 'on'` | Submit with forms via a hidden input. |
| Switch | `readOnly` | `boolean` | `false` | Prevents changes but stays focusable. |
| Switch | `disabled` | `boolean` | `false` | Disables the switch. |

## Accessibility

- Renders a button with role="switch" and aria-checked, announced as "on" or "off".
- The label is linked with aria-labelledby and clicking it toggles the switch.
- State is shown by thumb position and fill, not colour alone, and remains clear in forced colours.

## Keyboard

| Keys | Action |
| --- | --- |
| `Space` | Toggles the switch. |
| `Enter` | Toggles the switch. |

## Guidelines

**Do**

- Describe the setting, not the action: “Automatic deployment”.
- Apply the change immediately and confirm it.

**Don’t**

- Use a switch inside a form that needs a Save button.

## Related

- https://stanceui.com/components/checkbox
- https://stanceui.com/components/toggle-button