# Switch

## Overview

A binary toggle control that represents an on/off state — similar to a physical light switch. More prominent and visually expressive than a `<Checkbox>`. Used for feature toggles, notification settings, accessibility preferences, and any prominent boolean setting.

---

## When to Use

- Enabling/disabling individual features or settings
- Notification preferences
- Theme toggles
- Item visibility controls

## When NOT to Use

- Lists of independent multi-select options — use `<Checkbox>` instead.
- Single-choice from multiple options — use `<RadioGroup>` instead.
- Immediate irreversible destructive toggles — use a `<Button>` with `<AlertDialog>`.

---

## Props

| Prop              | Type                         | Default | Required | Description                                          |
| ----------------- | ---------------------------- | ------- | -------- | ---------------------------------------------------- |
| `id`              | `string`                     | —       | No       | Associates with `<Label htmlFor="...">`              |
| `size`            | `'sm' \| 'md' \| 'lg'`       | `'md'`  | No       | Size variant controlling track and thumb dimensions. |
| `checked`         | `boolean`                    | —       | No       | Controlled checked state                             |
| `defaultChecked`  | `boolean`                    | `false` | No       | Uncontrolled initial state                           |
| `onCheckedChange` | `(checked: boolean) => void` | —       | No       | Change handler                                       |
| `disabled`        | `boolean"                    | `false` | No       | Disables interaction                                 |
| `className`       | `string`                     | —       | No       | Additional CSS classes                               |

---

## Examples

### Standalone with Label

```tsx
import { Switch, Label } from 'xertica-ui/ui';
import { useState } from 'react';

const [enabled, setEnabled] = useState(false);

<div className="flex items-center space-x-2">
  <Switch id="notifications" checked={enabled} onCheckedChange={setEnabled} />
  <Label htmlFor="notifications">Email notifications</Label>
</div>;
```

### Settings List

```tsx
<div className="space-y-4">
  {[
    { id: 'email', label: 'Email Notifications' },
    { id: 'push', label: 'Push Notifications' },
    { id: 'sms', label: 'SMS Alerts' },
  ].map(({ id, label }) => (
    <div key={id} className="flex items-center justify-between">
      <Label htmlFor={id}>{label}</Label>
      <Switch id={id} />
    </div>
  ))}
</div>
```

### Inside react-hook-form

```tsx
<FormField
  control={form.control}
  name="newsletter"
  render={({ field }) => (
    <FormItem className="flex items-center justify-between p-4 border rounded-lg">
      <div>
        <FormLabel>Newsletter</FormLabel>
        <FormDescription>Receive weekly product updates</FormDescription>
      </div>
      <FormControl>
        <Switch checked={field.value} onCheckedChange={field.onChange} />
      </FormControl>
    </FormItem>
  )}
/>
```

---

## AI Rules

- Use `checked={field.value}` + `onCheckedChange={field.onChange}` in forms — **not** `{...field}`.
- **Sizing** — `Switch` supports `sm`, `md`, and `lg`. Ensure the size matches the associated `Label` size.
- Always pair with a `<Label>` for accessibility.
- For a list of settings, use `justify-between` on the row container to push the switch to the right.

---

## Related Components

- [`Checkbox`](./checkbox.md) — For multi-select lists
- [`RadioGroup`](./radio-group.md) — For single-choice selections
- [`Form`](./form.md)