# Switch

Toggles a setting that applies immediately.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Switch.tsx)

## Overview

A switch is a pill toggle for a setting that applies immediately.

Use `Checkbox` for choices that are submitted later.

## Examples

### Basic

```tsx
import { Switch } from '@tempoxyz/ds'

export function Demo() {
  return <Switch aria-label="Notifications" />
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Switch/Basic.tsx)

### Size

Set `size` to `small`, `medium`, or `large`. It defaults to `medium`, or `small` inside a `setting` field.

```tsx
import { style, Switch } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['small', 'medium', 'large'] as const).map((size) => (
        <Switch aria-label={size} key={size} size={size} />
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '6' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Switch/Size.tsx)

### Checked

Set `defaultChecked`, or control the state with `checked` and `onCheckedChange`.

```tsx
import { style, Switch } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['small', 'medium', 'large'] as const).map((size) => (
        <Switch aria-label={`${size} on`} defaultChecked key={size} size={size} />
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '6' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Switch/Checked.tsx)

### Disabled

Set `disabled` to block toggling.

```tsx
import { style, Switch } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['small', 'medium', 'large'] as const).map((size) => (
        <Switch aria-label={`${size} disabled`} disabled key={size} size={size} />
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '6' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Switch/Disabled.tsx)

### Field

Place the switch in a `Field.Root` with `variant="setting"` to sit beside its label and description.

```tsx
import { Field, style, Switch } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.settings()}>
      <Field.Root variant="setting">
        <Field.Label>Auto-convert</Field.Label>
        <Field.Description>Swap incoming funds to USDC.</Field.Description>
        <Switch defaultChecked />
      </Field.Root>
      <Field.Root variant="setting">
        <Field.Label>Notifications</Field.Label>
        <Field.Description>Email me when a payment settles.</Field.Description>
        <Switch />
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const settings = style({ maxWidth: '480px !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Switch/Field.tsx)

## Guidelines

TODO: Write guidelines for Switch.