# Cell Switch

A compact switch for inline use in a Data Table cell.

- Category: Forms
- Page: https://wunderui.com/components/cell-switch
- Tier: Free

## Install

```bash
npx wunderui-cli add cell-switch
```

## Import

```tsx
import { CellSwitch } from "@/components/wunderui/table-cells"
```

## Minimal usage

Then use it inside a table cell:

```tsx
import { useState } from "react"
import { CellSwitch } from "@/components/ui/cell-switch"
import { TableCell } from "@/components/ui/table"

export function EmailAlertsCell({ member }: { member: string }) {
  const [on, setOn] = useState(true)

  return (
    <TableCell>
      <CellSwitch aria-label={`Email alerts for ${member}`} checked={on} onCheckedChange={setOn} />
    </TableCell>
  )
}
```

Expected result: You see a small brand-coloured switch in the cell, turned on. Click it or press Space to turn it off, and the track turns grey as the knob moves left.

## Usage

```tsx
import { useState } from "react"
import { CellSwitch } from "@/components/ui/cell-switch"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

const MEMBERS = [
  { name: "Nora Lindgren", alerts: true },
  { name: "Daniel Okafor", alerts: false },
  { name: "Priya Raman", alerts: true },
]

export function Example() {
  const [members, setMembers] = useState(MEMBERS)
  const setAlerts = (name: string, alerts: boolean) =>
    setMembers((rows) => rows.map((row) => (row.name === name ? { ...row, alerts } : row)))
  
  return (
    <div className="w-full overflow-hidden rounded-xl border border-border bg-card">
      <Table aria-label="Email alerts">
        <TableHeader>
          <TableRow>
            <TableHead>Member</TableHead>
            <TableHead className="w-40">Email alerts</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {members.map((member) => (
            <TableRow key={member.name}>
              <TableCell role="rowheader" className="font-medium">{member.name}</TableCell>
              <TableCell>
                <CellSwitch
                  aria-label={`Email alerts for ${member.name}`}
                  checked={member.alerts}
                  onCheckedChange={(alerts) => setAlerts(member.name, alerts)}
                />
              </TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </div>
  )
}
```

## When to use

### Use Cell Switch for

- An on/off column in a table, such as enabled, notify or public
- A matrix of switches, where each row and column pair is one setting
- Settings that apply at once, with no Save button

### Use something else

- [Switch](https://wunderui.com/components/switch) for a setting outside a table, with a visible label
- [Checkbox](https://wunderui.com/components/checkbox) for a row you select for a bulk action, or a value that is sent with a form
- [Selector Item](https://wunderui.com/components/selector-item) for a setting with a title and a description in a card

## Keyboard

Each switch is one tab stop in its cell. It is a Switch, so the browser and Base UI handle focus and activation.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous control in the table, row by row. The table cells around the switch take no focus. |
| `Space` or `Enter` | Toggles the focused switch and calls `onCheckedChange` with the new value. |

Arrow keys do not move between table cells. Every switch in a column is its own Tab stop, in row order.

## Behavior

What the cell switch does itself, and what it leaves to the table around it.

- **Controlled:** CellSwitch keeps no state. You supply the checked value, every toggle calls the change handler with the new boolean, and nothing changes until you set it.
- **Accessible name:** A cell has no visible label, so the switch is named by its aria-label. The default Toggle is the same in every row, so set one per row, such as Email alerts for Nora Lindgren.
- **Table context:** With the first cell marked as a row header, a screen reader in table mode reads row, column and state together. In forms mode only the control is read, so its label must carry row and column.
- **Size and hit area:** It is the default Switch, 32 by 18 px. The click area reaches 12 px to the sides and 8 px above and below, so a near miss still toggles it and two rows in a 36 px row never overlap.
- **Alignment:** The switch is an inline control. Centre or right alignment on the cell moves it, and the column header should use the same alignment.
- **Hover and pressed:** An off track gets a rim on hover and a darker grey while pressed. A brand track darkens on hover and darkens again while pressed.
- **Figma states:** The Figma Editable Cell set has View, Edit, Changed, Saving, Error and Disabled, but CellSwitch is always editable. For a pending save or a disabled row, put a Switch with those states in the cell.
- **Motion:** The track changes colour quickly, and the knob slides, swings slightly past the end and settles. A second click reverses it from wherever it is.
- **Reduced motion:** With reduced motion the knob jumps to the other end instead of sliding. The colour change stays.

## Anatomy

- `Table`: The table the cell sits in. The first column holds the row names, the header row names the columns, and the switch lives in a table cell.
- `Column header`: The header of the switch column. It says what the switch changes, such as Email alerts, and aligns the same way as the cell.
- `Row header`: The first cell of the row, marked as the row header. It says whose or which setting this is, so a screen reader reads it with the switch.
- `CellSwitch`: A Switch with a default aria-label of Toggle, made for a table cell with no visible label. You hold the checked state and write it back on change.
- `Track`: The 32 by 18 px pill. It is brand-coloured when on and grey when off, and it carries the switch role and checked state.
- `Knob`: The 16 px circle that slides from one end of the track to the other. It swings slightly past the end before it settles.

## Best practices

### Do

- Name every switch by its row and column, such as Email alerts for Nora Lindgren. The default Toggle is the same in every row and tells a screen-reader user nothing.
- Mark the first cell of each row as a row header and give the switch column a header that says what it changes. The cell is then read as row, column and state.
- Keep the checked state in your own state and save in the same handler that writes it back. The cell keeps no state.
- Align the switch like its column header: centred in a narrow column, left beside text. Use the same alignment class on the header and the cell.

### Don't

- Don't use CellSwitch outside a table. Without a visible label the switch has no context, so use Switch with a Label, or a Selector Item.
- Don't use a switch for an action that needs a confirmation, such as deleting data. A switch applies at once.
- Don't put two switches in one cell. One cell holds one value, so give each value its own column.
- Don't expect a saving, error or disabled look from CellSwitch. For rows that need them, use a Switch with those states inside the cell.

## API reference

### CellSwitch

| Prop | Type | Default | Description |
|---|---|---|---|
| checked* | boolean |  | Whether the switch is on. It is a controlled value: write the new one back in `onCheckedChange`. |
| onCheckedChange* | (checked: boolean) => void |  | Called with the new value, `true` or `false`, when the person toggles the switch with a click, Space or Enter. |
| aria-label | string |  | The name for screen readers. A cell has no visible label, so give each switch its row and column, such as `Email alerts for Nora Lindgren`. The default is `Toggle`. |

## Examples

### Alignment: left, centered or right in the column

```tsx
import { useState } from "react"
import { CellSwitch } from "@/components/ui/cell-switch"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

const MEMBERS = [
  { name: "Nora Lindgren", alerts: true },
  { name: "Daniel Okafor", alerts: false },
  { name: "Priya Raman", alerts: true },
]

export function Example() {
  const [members, setMembers] = useState(MEMBERS)
  const setAlerts = (name: string, alerts: boolean) =>
    setMembers((rows) => rows.map((row) => (row.name === name ? { ...row, alerts } : row)))
  
  return (
    <div className="w-full overflow-hidden rounded-xl border border-border bg-card">
      <Table aria-label="Email alerts">
        <TableHeader>
          <TableRow>
            <TableHead>Member</TableHead>
            <TableHead className="w-40">Email alerts</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {members.map((member) => (
            <TableRow key={member.name}>
              <TableCell role="rowheader" className="font-medium">{member.name}</TableCell>
              <TableCell>
                <CellSwitch
                  aria-label={`Email alerts for ${member.name}`}
                  checked={member.alerts}
                  onCheckedChange={(alerts) => setAlerts(member.name, alerts)}
                />
              </TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </div>
  )
}
```

## In context

### Automation rules: one switch per rule

An Active column turns each rule on or off in the table. The count above follows, an inactive rule dims its name and each switch is named after its rule.

```tsx
import { useState } from "react"
import { CellSwitch } from "@/components/ui/cell-switch"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

const RULES = [
  { name: "Assign new tickets to the on-call agent", trigger: "Ticket created", on: true },
  { name: "Close tickets after 7 days without a reply", trigger: "Daily at 02:00", on: true },
  { name: "Tag customers on the Business plan", trigger: "Ticket created", on: false },
  { name: "Notify #billing about refunds", trigger: "Refund requested", on: true },
]

export function Example() {
  const [rules, setRules] = useState(RULES)
  const setOn = (name: string, on: boolean) =>
    setRules((rows) => rows.map((row) => (row.name === name ? { ...row, on } : row)))
  const active = rules.filter((rule) => rule.on).length

  return (
    <div className="w-full overflow-hidden rounded-xl border border-border bg-card">
      <div className="flex items-center justify-between gap-4 border-b border-border px-4 py-3">
        <p className="text-sm font-semibold text-foreground">Automation rules</p>
        <span className="text-xs text-text-tertiary">{active} of {rules.length} active</span>
      </div>
      <Table aria-label="Automation rules">
        <TableHeader>
          <TableRow>
            <TableHead>Rule</TableHead>
            <TableHead>Runs on</TableHead>
            <TableHead className="w-24 text-center">Active</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {rules.map((rule) => (
            <TableRow key={rule.name}>
              <TableCell role="rowheader" className={rule.on ? "font-medium" : "font-medium text-text-tertiary"}>
                {rule.name}
              </TableCell>
              <TableCell>{rule.trigger}</TableCell>
              <TableCell className="text-center">
                <CellSwitch
                  aria-label={`Active: ${rule.name}`}
                  checked={rule.on}
                  onCheckedChange={(on) => setOn(rule.name, on)}
                />
              </TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </div>
  )
}
```

### Notification preferences: a switch for each channel

Three switch columns share one table. Column and row headers give each switch a name made of both, such as Push for Mentions.

```tsx
import { useState } from "react"
import { CellSwitch } from "@/components/ui/cell-switch"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

type Channel = "email" | "push" | "slack"

const CHANNELS: { key: Channel; label: string }[] = [
  { key: "email", label: "Email" },
  { key: "push", label: "Push" },
  { key: "slack", label: "Slack" },
]

const EVENTS = [
  { name: "Mentions", email: true, push: true, slack: false },
  { name: "Comments on my tasks", email: true, push: false, slack: false },
  { name: "Weekly digest", email: true, push: false, slack: true },
  { name: "Billing receipts", email: true, push: false, slack: false },
]

export function Example() {
  const [events, setEvents] = useState(EVENTS)
  const setChannel = (name: string, channel: Channel, on: boolean) =>
    setEvents((rows) => rows.map((row) => (row.name === name ? { ...row, [channel]: on } : row)))

  return (
    <div className="w-full overflow-hidden rounded-xl border border-border bg-card">
      <Table aria-label="Notification preferences">
        <TableHeader>
          <TableRow>
            <TableHead>Notify me about</TableHead>
            {CHANNELS.map(({ key, label }) => (
              <TableHead key={key} className="w-24 text-center">{label}</TableHead>
            ))}
          </TableRow>
        </TableHeader>
        <TableBody>
          {events.map((event) => (
            <TableRow key={event.name}>
              <TableCell role="rowheader" className="font-medium">{event.name}</TableCell>
              {CHANNELS.map(({ key, label }) => (
                <TableCell key={key} className="text-center">
                  <CellSwitch
                    aria-label={`${label} for ${event.name}`}
                    checked={event[key]}
                    onCheckedChange={(on) => setChannel(event.name, key, on)}
                  />
                </TableCell>
              ))}
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </div>
  )
}
```

## For AI agents

`get_component("cell-switch")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
