# Switch field (goodtabs UI)

A settings row with a label, a description and a switch. Rows stack in a group.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/switch-field.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/switch-field`

## Usage

```tsx
import { SwitchField, SwitchFieldGroup } from "@/components/ui/switch-field"

<SwitchFieldGroup aria-label="Notifications">
  <SwitchField label="Email digest" description="One email a week." defaultChecked />
  <SwitchField label="Product updates" onCheckedChange={setUpdates} />
</SwitchFieldGroup>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | `string` |  | The setting's name, on SwitchField. |
| description | `string` |  | One line under the name on what the setting does. |
| checked | `boolean` |  | Controlled state. |
| defaultChecked | `boolean` | `false` | Starting state when uncontrolled. |
| onCheckedChange | `(checked: boolean) => void` |  | Fires with the new state on every toggle. |
| disabled | `boolean` | `false` | Fades the row and blocks toggling. |
| id | `string` |  | Id for the switch. Generated when left out. |

## When to use

- Settings and preferences pages with on and off options
- Notification, privacy and feature toggles that need a line of explanation
- Any list of independent booleans that should read as one card

## When not to use

- Choosing one of several options: use a radio group or segmented tabs
- Actions that run straight away, like Send or Delete: use a button
- A switch inside a dense toolbar with no room for a description: use the Switch primitive alone

## Notes for agents

- Server component by default; it forwards every shadcn Switch prop. Pass onCheckedChange from a client component
- The row is the Label, so the hit area is the whole row; the switch is named by the label text only, not the description
- A row on its own has no border or side padding; SwitchFieldGroup adds the border, the hairlines and px-4
- Give SwitchFieldGroup an aria-label so screen readers announce the group

Docs: https://ui.goodtabs.co/components/switch-field