Settings Row
FreeA setting's title and description on the left and its control on the right. With a checked state the control is a switch named by the title; with a control prop it is anything you pass.
npx wunderui-cli add settings-rowPlayground
Email notifications
Mentions, replies and invites
Two-factor authentication
Add a second step when you sign in
Email digest
A summary of what you missed
Single sign-on
Enabled for wunderui.com
Delete workspace
Permanently delete WunderUI and all of its data.
Installation
npx wunderui-cli add settings-rowWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { SettingsRow } from "@/components/blocks/auth"
import type { SettingsRowProps } from "@/components/blocks/auth"Then use it:
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.
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 for
- Selector Item for a choice between options that each have a description
- Cell Switch for a switch in a cell of a settings list in the mobile style
- Field for a labelled input with a hint and an error message
- Switch for a bare switch outside a list
State
The built-in switch is only on or off. For a switch that is saving or disabled, pass your own Switch as the control.
Email notifications
Mentions, replies and invites
Email notifications
Mentions, replies and invites
Email notifications
Mentions, replies and invites
Email notifications
Managed by your administrator
Long text
The title and description wrap onto more lines and the control keeps its size, centred next to them. There is no ellipsis, and without a description the title stands alone.
Text
Email notifications
Mentions, replies and invites
Email me when someone mentions me, replies to my comment or invites me to a workspace
WunderUI sends one email for each event, at most one every five minutes, to the address on your account. Turn this off to read everything in the inbox instead.
Email notifications
Email notifications
Mentions, replies and invites
List
A row has no padding, border or fill. Put rows in a column with a gap, or divide them with one hairline and vertical padding on each row, and wrap the list in a card of your own.
Email notifications
Mentions, replies and invites
Push notifications
On your phone and in the browser
Weekly summary
Every Monday at 8:00
Email notifications
Mentions, replies and invites
Push notifications
On your phone and in the browser
Weekly summary
Every Monday at 8:00
Notifications
Email notifications
Mentions, replies and invites
Push notifications
On your phone and in the browser
Weekly summary
Every Monday at 8:00
Keyboard interactions
The row itself is not interactive. Its control is: a switch, a button or a select, in the page's tab order.
- TaborShift+Tab
- Moves focus to the control of the next or previous row.
- Space
- On a switch: turns it on or off and calls .
- EnterorSpace
- On a button in the : presses it.
- EnterorSpaceorArrowDown
- On a select in the : opens its list. Arrow keys move, Enter picks, Esc closes.
Behavior and motion
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
The parts of a settings row, numbered in the figure. It is one component, and the dashed outline only shows its bounds, since the row has no border of its own.
Email notifications
Mentions, replies and invites
- 1data-slot="settings-row"
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.
- 2
The title in 14 px medium text, wrapped when long with no ellipsis. With a switch it is the name of the switch.
- 3Optional
The description in 12 px secondary text, 2 px under the title. Drawn only when passed.
- 4Optional
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
- Do
Pass the checked value and a change handler for a switch. The title names the switch for assistive technology.
- Do
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.
- Do
Pass your own Switch as the control when it must show that it is saving or disabled. The built-in switch supports neither.
- Do
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.
- Do
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
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
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
Settings Row is one component with the props below. It takes no other attributes, so an id, a data attribute or an aria-label cannot be passed to the row.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| title required | ReactNode | — | The name of the setting. It is also the accessible name of the built-in switch. Required. |
| description | ReactNode | — | A line under the title that explains the setting. Optional. |
| control | 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 or is set. |
| checked | boolean | — | Turns the row into a switch and sets whether it is on. Controlled: the row does not change it. |
| onCheckedChange | (checked) => void | — | Turns the row into a switch and is called with the new value when it is pressed. |
| className | string | — | Added to the row. Use it for the width and for the padding of a list, for example . |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("settings-row")npx wunderui-cli add settings-rowThe full library index for assistants is at /llms.txt.