# Switch

```tsx
import { Switch } from '@tangible/ui';
```

Interactive docs and examples: [Switch in Storybook](https://storybook-tangible-ui.pages.dev/?path=/docs/forms-switch--docs).

## Switch props

| Prop | Type | Default | Description |
| - | - | - | - |
| `checked?` | `boolean` | | |
| `className?` | `string` | | |
| `defaultChecked?` | `boolean` | `false` | |
| `disabled?` | `boolean` | | |
| `label?` | `ReactNode` | | |
| `onCheckedChange?` | `(checked: boolean) => void` | | |
| `size?` | `"lg" \| "md" \| "sm"` | `'md'` | |

Also accepts the standard attributes of `ButtonHTMLAttributes` (`data-*`, `aria-*`, event handlers), passed to the element it renders.

## Examples

- [Bare](https://storybook-tangible-ui.pages.dev/?path=/story/forms-switch--bare): Bare switch with no visible label — requires `aria-label` for accessibility.

- [Labeled](https://storybook-tangible-ui.pages.dev/?path=/story/forms-switch--labeled): Labeled switch using the built-in `label` prop (no Field wrapper).

- [With Field](https://storybook-tangible-ui.pages.dev/?path=/story/forms-switch--with-field): Bare switch inside a Field — `Field.Control` injects `aria-labelledby`
  pointing at `Field.Label`, providing the accessible name. This works
  because `<button>` is not a labelable element, so `htmlFor` alone
  would not associate the label.

- [Bare With Field](https://storybook-tangible-ui.pages.dev/?path=/story/forms-switch--bare-with-field): Minimal Field integration — bare switch with label provided by Field.Label.

- [With Field Error](https://storybook-tangible-ui.pages.dev/?path=/story/forms-switch--with-field-error): Error state — `aria-invalid` is injected by `Field.Control` and the
  switch track displays a danger-coloured border for visual feedback.

- [Multiple Options](https://storybook-tangible-ui.pages.dev/?path=/story/forms-switch--multiple-options): Related switches should be grouped in a `<fieldset>` with a `<legend>`
  so screen reader users understand the switches belong together.

Other stories: Basic, Checked By Default, Disabled, Disabled Checked, Controlled, Sizes ([interactive page](https://storybook-tangible-ui.pages.dev/?path=/docs/forms-switch--docs)).

## Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.

- `--tui-switch-accent`
- `--tui-switch-bg`
- `--tui-switch-border`
- `--tui-switch-border-width`
- `--tui-switch-thumb-bg`
- `--tui-switch-thumb-size`
- `--tui-switch-track-height`
- `--tui-switch-track-width`
- `--tui-switch-size`
- `--tui-switch-label-color`
- `--tui-switch-font-size`
- `--tui-switch-gap`

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/forms-switch--docs