# Settings Row

A setting's title and description with a switch, or any other control, on the right.

- Category: Forms
- Page: https://wunderui.com/components/settings-row
- Tier: Free

## Install

```bash
npx wunderui-cli add settings-row
```

## Import

```tsx
import { SettingsRow, SettingsRowProps } from "@/components/blocks/auth"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { SettingsRow } from "@wunderui/react"

export function Setting() {
  const [on, setOn] = useState(true)

  return <SettingsRow title="Email notifications" description="Mentions, replies and invites" checked={on} onCheckedChange={setOn} />
}
```

Expected result: You see the title and description on the left and a switch on the right. Pressing the switch turns it off and on.

## Usage

```tsx
import { useState } from "react"
import { SettingsRow } from "@wunderui/react"

export function Example() {
  const [on, setOn] = useState(true)

  // checked or onCheckedChange turns the row into a switch that the title names
  return <SettingsRow title="Email notifications" description="Mentions, replies and invites" checked={on} onCheckedChange={setOn} />
}
```

## When to use

### Use Settings Row for

- A list of preferences with a switch on each row
- A setting that opens something: a button, a select or a badge on the right
- A danger zone with a destructive button

### Use something else

- [Selector Item](https://wunderui.com/components/selector-item) for a choice between options that each have a description
- [Cell Switch](https://wunderui.com/components/cell-switch) for a switch in a cell of a settings list in the mobile style
- [Field](https://wunderui.com/components/field) for a labelled input with a hint and an error message
- [Switch](https://wunderui.com/components/switch) for a bare switch outside a list

## Keyboard

The row itself is not interactive. Its control is: a switch, a button or a select, in the page's tab order.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the control of the next or previous row. |
| `Space` | On a switch: turns it on or off and calls `onCheckedChange`. |
| `Enter` or `Space` | On a button in the `control`: presses it. |
| `Enter` or `Space` or `ArrowDown` | On a select in the `control`: opens its list. Arrow keys move, Enter picks, Esc closes. |

## Behavior

What a settings row does with state, content, the DOM and motion.

- **Switch or control:** Setting a checked value or change handler makes the row a switch and ignores any control, otherwise it shows your control. The row keeps no value, it shows what you pass and reports what was asked.
- **States:** The built-in switch is on or off, with the usual hover, pressed and focus states. Saving (spinner, presses ignored) and disabled (40 % dim) belong to a Switch you pass as the control.
- **Long text:** The title and description wrap and the row grows taller, with no ellipsis. The control keeps its size and stays centred next to the text.
- **Responsive:** The row has no breakpoints, so text and control stay side by side and the text wraps onto many lines in a very narrow row. Give a wide control its own row on a narrow screen.
- **Names for assistive technology:** The title is the accessible name of the built-in switch, the description is not. A switch, select or button you pass as the control needs its own name.
- **Motion and reduced motion:** The row itself has no motion. The switch handle slides with the track changing colour, and the saving spinner stops under reduced motion while the handle still moves.

## Anatomy

- `SettingsRow`: A flex row with the text on the left, the control on the right and 24 px between them, centred vertically. It has no padding, border or fill, because the list around it provides them.
- `Title`: The title in 14 px medium text, wrapped when long with no ellipsis. With a switch it is the name of the switch.
- `Description`: The description in 12 px secondary text, 2 px under the title. Drawn only when passed.
- `Control`: A switch when a checked value or change handler is set, otherwise the control you pass, such as a button, select or badge. It keeps its size and is never squeezed.

## Best practices

### When to use

- Use it for lists of preferences, one setting per row. For choices between described options use Selector Item.

### Do

- Pass the checked value and a change handler for a switch. The title names the switch for assistive technology.
- Pass your own control for a setting that opens something or shows a state: a Button, a Select, a Badge. Give a Switch passed this way its own aria-label, because the title cannot name it.
- Pass your own Switch as the control when it must show that it is saving or disabled. The built-in switch supports neither.
- Space rows with the list: a divider between rows with vertical padding on each gives one hairline between two rows, never two. Put the list in a card with a 16 px radius.
- Say what changed in a status line, such as Email notifications turned off, because a switch that flips alone gives a screen reader user no other news.

### Don't

- Don't pass both a switch and a control. When the checked value or change handler is set, the control is ignored.
- Don't put a destructive action behind a plain press. A destructive button should open a confirmation, and the result should be undoable when possible.
- Don't expect the description to be announced with the switch. It is not linked to the control, so keep what matters in the title.

## API reference

### SettingsRow

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  | The name of the setting. It is also the accessible name of the built-in switch. Required. |
| checked | boolean |  | Turns the row into a switch and sets whether it is on. Controlled: the row does not change it. |
| className | string |  | Added to the row. Use it for the width and for the padding of a list, for example `py-3 first:pt-0 last:pb-0`. |
| control | React.ReactNode |  | The control on the right when the row is not a switch: a Button, a Select, a Badge or your own Switch. Ignored when `checked` or `onCheckedChange` is set. |
| description | React.ReactNode |  | A line under the title that explains the setting. Optional. |
| onCheckedChange | (checked: boolean) => void |  | Turns the row into a switch and is called with the new value when it is pressed. |

## Examples

### State: off, on, saving and disabled

```tsx
import { useState } from "react"
import { SettingsRow } from "@wunderui/react"

export function Example() {
  const [on, setOn] = useState(false)

  return <SettingsRow title="Email notifications" description="Mentions, replies and invites" checked={on} onCheckedChange={setOn} />
}
```

### Text: short, long, no description and narrow

```tsx
import { useState } from "react"
import { SettingsRow } from "@wunderui/react"

export function Example() {
  const [on, setOn] = useState(true)

  return (
    <SettingsRow
      title="Email notifications"
      description="Mentions, replies and invites"
      checked={on}
      onCheckedChange={setOn}
    />
  )
}
```

### List: plain, divided and in a card

```tsx
import { useState } from "react"
import { SettingsRow } from "@wunderui/react"

const ROWS = [
  { title: "Email notifications", description: "Mentions, replies and invites", on: true },
  { title: "Push notifications", description: "On your phone and in the browser", on: false },
  { title: "Weekly summary", description: "Every Monday at 8:00", on: true },
]

export function Settings() {
  const [prefs, setPrefs] = useState<Record<string, boolean>>(Object.fromEntries(ROWS.map((row) => [row.title, row.on])))

  return (
    <div className="flex flex-col gap-4">
      {ROWS.map((row) => (
        <SettingsRow
          key={row.title}
          title={row.title}
          description={row.description}
          checked={prefs[row.title]}
          onCheckedChange={(value) => setPrefs((current) => ({ ...current, [row.title]: value }))}
        />
      ))}
    </div>
  )
}
```

## In context

### Notification settings: switches, a select and a button

Two switches, a select for the digest and a button. Each change says what was saved in the line under the list, and rows are divided by a single hairline.

```tsx
import { useState } from "react"
import {
  Button,
  NativeSelect,
  NativeSelectContent,
  NativeSelectItem,
  NativeSelectTrigger,
  NativeSelectValue,
  SettingsRow,
} from "@wunderui/react"

export function NotificationSettings() {
  const [email, setEmail] = useState(true)
  const [push, setPush] = useState(false)
  const [digest, setDigest] = useState("Daily")
  const [message, setMessage] = useState("")

  const saved = (label: string, on: boolean) => setMessage(label + (on ? " on" : " off") + ". Saved.")

  return (
    <section aria-label="Notifications" className="flex flex-col gap-4 rounded-xl border border-border bg-card p-4">
      <div className="flex flex-col gap-0.5">
        <h2 className="text-sm font-semibold text-foreground">Notifications</h2>
        <p className="text-xs text-text-secondary">Choose how WunderUI reaches you at info@wunderui.com.</p>
      </div>
      <div className="flex flex-col divide-y divide-border">
        <SettingsRow
          className="py-3 first:pt-0"
          title="Email notifications"
          description="Mentions, replies and invites"
          checked={email}
          onCheckedChange={(on) => { setEmail(on); saved("Email notifications", on) }}
        />
        <SettingsRow
          className="py-3"
          title="Push notifications"
          description="On your phone and in the browser"
          checked={push}
          onCheckedChange={(on) => { setPush(on); saved("Push notifications", on) }}
        />
        <SettingsRow
          className="py-3"
          title="Email digest"
          description="A summary of what you missed"
          control={
            <NativeSelect
              value={digest}
              onValueChange={(value) => { setDigest(String(value)); setMessage("Digest set to " + String(value).toLowerCase() + ". Saved.") }}
            >
              <NativeSelectTrigger aria-label="Email digest" className="w-32">
                <NativeSelectValue />
              </NativeSelectTrigger>
              <NativeSelectContent>
                <NativeSelectItem value="Daily">Daily</NativeSelectItem>
                <NativeSelectItem value="Weekly">Weekly</NativeSelectItem>
                <NativeSelectItem value="Never">Never</NativeSelectItem>
              </NativeSelectContent>
            </NativeSelect>
          }
        />
        <SettingsRow
          className="py-3 last:pb-0"
          title="Test email"
          description="Send one to see how it looks"
          control={<Button variant="plain" size="sm" onClick={() => setMessage("Test email sent to info@wunderui.com.")}>Send test</Button>}
        />
      </div>
      <p role="status" className="min-h-4 text-xs text-text-secondary">
        {message}
      </p>
    </section>
  )
}
```

### Security and danger zone: a destructive row that asks first

A badge and a button in the Security card, and a destructive button in the Danger zone. Delete workspace asks first, then schedules the deletion and shows Undo; nothing is really deleted.

```tsx
import { useState } from "react"
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogIcon,
  AlertDialogTitle,
  Badge,
  Button,
  SettingsRow,
} from "@wunderui/react"

export function SecuritySettings() {
  const [confirm, setConfirm] = useState(false)
  const [deleted, setDeleted] = useState(false)

  return (
    <div className="flex flex-col gap-4">
      <section aria-label="Security" className="flex flex-col gap-4 rounded-xl border border-border bg-card p-4">
        <h2 className="text-sm font-semibold text-foreground">Security</h2>
        <div className="flex flex-col divide-y divide-border">
          <SettingsRow
            className="py-3 first:pt-0"
            title="Two-factor authentication"
            description="An authenticator app is set up"
            control={<Badge color="green" badgeStyle="light" shape="pill">Enabled</Badge>}
          />
          <SettingsRow
            className="py-3 last:pb-0"
            title="Active sessions"
            description="You are signed in on 3 devices"
            control={<Button variant="plain" size="sm">Sign out everywhere</Button>}
          />
        </div>
      </section>
      <section aria-label="Danger zone" className="flex flex-col gap-4 rounded-xl border border-border bg-card p-4">
        <h2 className="text-sm font-semibold text-foreground">Danger zone</h2>
        <SettingsRow
          title="Delete workspace"
          description={deleted ? "Scheduled for deletion in 14 days." : "Permanently delete WunderUI and all of its data."}
          control={
            deleted ? (
              <Button variant="plain" size="sm" onClick={() => setDeleted(false)}>Undo</Button>
            ) : (
              <Button variant="destructive" size="sm" onClick={() => setConfirm(true)}>Delete workspace</Button>
            )
          }
        />
      </section>
      <AlertDialog open={confirm} onOpenChange={setConfirm}>
        <AlertDialogContent>
          <AlertDialogHeader>
            <AlertDialogIcon variant="destructive" />
            <AlertDialogTitle>Delete WunderUI?</AlertDialogTitle>
            <AlertDialogDescription>All projects, files and members are removed after 14 days. You can undo this until then.</AlertDialogDescription>
          </AlertDialogHeader>
          <AlertDialogFooter>
            <AlertDialogCancel>Keep workspace</AlertDialogCancel>
            <AlertDialogAction variant="destructive" onClick={() => setDeleted(true)}>
              Delete workspace
            </AlertDialogAction>
          </AlertDialogFooter>
        </AlertDialogContent>
      </AlertDialog>
    </div>
  )
}
```

## For AI agents

`get_component("settings-row")`

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