Settings Row

InstallCopy Anchor Link

pnpm exec vegastack-design verify settings-row

pnpm dlx shadcn@4.21.0 add @vegastack/settings-row

UsageCopy Anchor Link

import {
  SettingsCard,
  SettingsRow,
  SettingsSection,
} from "@/components/ui/settings-row";
import { Switch } from "@/components/ui/switch";

<SettingsSection
  title="Notifications"
  description="Choose what you want to hear about."
>
  <SettingsCard>
    <SettingsRow label="Email" description="Product updates and tips.">
      <Switch defaultChecked aria-label="Email notifications" />
    </SettingsRow>
    <SettingsRow label="SMS" description="Critical alerts only.">
      <Switch aria-label="SMS alerts" />
    </SettingsRow>
  </SettingsCard>
</SettingsSection>;

AnatomyCopy Anchor Link

Settings Row is a compound component. Every exported part, with the data-slot it renders (generated from the canonical source):

ExamplesCopy Anchor Link

AnatomyCopy Anchor Link

The settings layout is three flat parts that nest from the outside in. Each is a plain, server-safe element with a forwarded ref and a data-slot for styling and targeting:

<SettingsSection title="…" description="…">
  <SettingsCard>
    <SettingsRow label="…" description="…">
      {/* control: Switch, Input, Button, badge, or read-only value */}
    </SettingsRow>
    <SettingsRow label="…">{/* control */}</SettingsRow>
  </SettingsCard>
</SettingsSection>

• SettingsSection — a titled group (data-slot="settings-section"). Renders an optional title and description above its children, with optional actions ("Sign out other devices", "New attribute") right-aligned on the title's row. Use one section per logical group (Account, Notifications, Danger zone).
• SettingsCard — upstream's Card (data-slot="settings-card"), flattened for a divided list: py-0 gap-0, so rows sit edge to edge and each row's own border-b is the only divider. The radius, the bg-card ground and the border border-border hairline come from Card, which is why a settings card and every other card on the page are the same object; the last row's border is collapsed so the list ends on the card edge rather than on a stray rule.
• SettingsRow — one setting (data-slot="settings-row"): a label and optional description on the left, the control children on the right, with a border-b divider. The row is its own named @container — it stacks or goes horizontal based on its own measured width, not the viewport, so a row placed in a narrow card (a settings panel in a split view, a dialog) stacks even on a wide screen, while the same row in a full-width page goes horizontal. Works standalone; no SettingsCard required.

All three are flat named exports — there is no dotted namespace.

Settings layoutsCopy Anchor Link

A bordered card grouping a mix of rows — a Switch, a Select, and another Switch:

A full section with a titled header above a card of switch rows:

Native labels with controlIdCopy Anchor Link

Pass controlId when the row wraps a native form control with a matching id. The visual label renders as a real <label htmlFor={controlId}>, so clicking the label focuses the input and screen readers announce the pairing. Use labelProps to merge extra attributes (e.g. analytics hooks) onto the generated label.

Control sizesCopy Anchor Link

controlSize gives every row's control one measure once the row sits side by side — sm 160px, md 256px, lg 320px — so stacked rows share one left edge and one right edge for their controls. The first child of the control slot fills it (a trailing status icon or button beside it keeps its own size). Left unset, a row holding a field control (input, input group, textarea, select, combobox, date or people picker) takes md, found in CSS from the control's data-slot, and anything else — a switch, a button, a read-only value — keeps its own width; auto opts a field out. Below the row's side-by-side width the control spans the row. Never put a width class on the control itself: pick a size.

Settings matrixCopy Anchor Link

SettingsMatrix is settings × channels on one bordered surface: the column names ("Push", "Email") once, in a header that sticks to the top of the scrolling page, a switch under each, and the row labels on the left — not "Push" and "Email" repeated beside every switch. It sits where a SettingsCard would. Each row passes its values (one per column) and an onChange(column, checked); disabled takes a whole row or one flag per column. Narrower than 28rem of its own width, the header goes and each row stacks its switches under its label, each with its column name beside it — part of the tap target.

Control varietyCopy Anchor Link

The control slot accepts any node — Input, Switch, a read-only value, a Badge, or a Button. A row with no children renders label-only (no control slot), which suits headings such as a danger-zone intro.

API ReferenceCopy Anchor Link

SettingsRowCopy Anchor Link

SettingsMatrixCopy Anchor Link

Each row of rows:

SettingsCardCopy Anchor Link

SettingsSectionCopy Anchor Link

AccessibilityCopy Anchor Link

• SettingsSection renders its title as a real heading — <h3> by default, or whatever titleAs names (h2…h6). A settings page nests sections at different depths, and the level is a document-structure fact the page owns: pick the one that continues the outline, so heading navigation stays meaningful. The visual size never changes. Keep one section per heading and order them logically.
• Pass controlId when the row contains a form control with a matching id; the row label becomes a real <label htmlFor={controlId}>. For composite controls that do not expose an input id, keep an explicit aria-label or aria-labelledby on the control itself.
• Every SettingsMatrix switch is named by its row and its column ("Mentions Email") through aria-labelledby; the column header is visual only, and on a narrow matrix the column name is visible beside the switch.
• Rows are separated by border-border rather than by elevation, so the divided list stays legible in high-contrast and forced-colors modes; the card's own hairline is Card's border border-border (BRD-1).

Do / Don'tCopy Anchor Link