> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# Switch

Data Entry`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Toggles a setting on or off with immediate effect.

## When to use

Use Switch for settings that take effect immediately.

**Recommended**

- Use labels that describe the enabled state.
- Use Checkbox when the value is submitted with a form.

**Avoid**

- Do not use the component outside its intended interaction model.

## Examples


### Basic usage
```tsx preview
import { Stack, Switch } from '@rockshin/tao-ui';
import { useState } from 'react';

function SwitchExample() {
  const [enabled, setEnabled] = useState(true);

  return (
    <Stack direction="horizontal" gap="lg" align="center">
      <Switch checked={enabled} onChange={setEnabled} />
      <Switch checked loading />
      <Switch disabled />
    </Stack>
  );
}

export default SwitchExample;
```

### Labels and sizes
```tsx preview
import { Stack, Switch } from '@rockshin/tao-ui';

function SwitchLabels() {
  return (
    <Stack direction="horizontal" gap="lg" align="center">
      <Switch size="small" defaultChecked />
      <Switch checkedChildren="ON" unCheckedChildren="OFF" defaultChecked />
      <Switch
        aria-label="Receive notifications"
        checkedChildren={
          <svg
            width="14"
            height="14"
            viewBox="0 0 16 16"
            fill="none"
            stroke="currentColor"
            strokeWidth="2"
            strokeLinecap="round"
            strokeLinejoin="round"
            aria-hidden="true"
            focusable="false"
          >
            <path d="m3 8 3 3 7-7" />
          </svg>
        }
        unCheckedChildren={
          <svg
            width="14"
            height="14"
            viewBox="0 0 16 16"
            fill="none"
            stroke="currentColor"
            strokeWidth="2"
            strokeLinecap="round"
            aria-hidden="true"
            focusable="false"
          >
            <path d="m4 4 8 8m0-8-8 8" />
          </svg>
        }
      />
    </Stack>
  );
}

export default SwitchLabels;
```

### Loading and disabled states
```tsx preview
import { Stack, Switch } from '@rockshin/tao-ui';

function SwitchStates() {
  return (
    <Stack direction="horizontal" gap="lg" align="center">
      <Switch loading checked />
      <Switch disabled />
      <Switch checked disabled />
    </Stack>
  );
}

export default SwitchStates;
```

### Controlled switch
onChange returns a boolean that can directly update setting state.
```tsx preview
import { useState } from 'react';
import { Switch, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [enabled, setEnabled] = useState(true);
  return (
    <Stack direction="vertical">
      <Switch
        aria-label="Notifications"
        checked={enabled}
        onChange={setEnabled}
      />
      <output>
        {enabled ? 'Notifications enabled' : 'Notifications disabled'}
      </output>
    </Stack>
  );
}
```

### Loading prevents repeated toggles
Use a separate button to toggle loading and inspect the waiting state.
```tsx preview
import { useState } from 'react';
import { Switch, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [loading, setLoading] = useState(false);
  return (
    <Stack direction="vertical">
      <Switch aria-label="Sync" loading={loading} defaultChecked />
      <Button onClick={() => setLoading(!loading)}>
        {loading ? 'Finish loading' : 'Start loading'}
      </Button>
    </Stack>
  );
}
```

### State labels and sizes
Keep state labels concise and readable at both sizes.
```tsx preview
import { Switch, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      <Switch
        aria-label="Access"
        checkedChildren="On"
        unCheckedChildren="Off"
        defaultChecked
      />
      <Switch
        size="small"
        aria-label="Compact access"
        checkedChildren="On"
        unCheckedChildren="Off"
        defaultChecked
      />
      <Switch
        aria-label="Locked access"
        checkedChildren="On"
        unCheckedChildren="Off"
        defaultChecked
        disabled
      />
    </Stack>
  );
}
```

### Shared size and disabled state
Multiple switches inherit configuration; a local disabled prop can override it.
```tsx preview
import { Switch, TaoProvider, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <TaoProvider size="small" disabled>
      <Stack>
        <Switch aria-label="Inherited disabled" defaultChecked />
        <Switch aria-label="Enabled override" disabled={false} />
      </Stack>
    </TaoProvider>
  );
}
```

## API


### [#](#switch)Switch



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |

