Settings List
Arrange labeled settings and their controls in a shared card.
Project settings
Manage visibility and notifications for your project.
Installation
pnpm dlx shadcn@4.18.0 add @siteplane/settings-listComplete the one-time setup first. Registry JSON lists source files and dependencies.
For this page’s examples, also install:
pnpm dlx shadcn@4.18.0 add @siteplane/badge @siteplane/input @siteplane/select @siteplane/switchUsage
import {
SettingsList,
SettingsListItem,
} from "@/siteplane/components/settings-list";
import { Switch } from "@/siteplane/components/switch";
<SettingsList title="Preferences">
<SettingsListItem
title="Email updates"
control={(props) => <Switch {...props} />}
/>
</SettingsList>;Composition
SettingsList
└── SettingsListItem
└── control(props) → Switch, Input or another public controlControlled values
Keep the values in your application state and spread every prop passed to control, so the title and description stay associated with the control. An action button, such as Change or Manage, keeps its own text as its name, so pass it only aria-describedby. tag adds a badge beside the title, and layout="inline" keeps a short control next to its label in a narrow list.
Profile
How other members see you in this workspace.
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
Settings | ReactNode | required | Section heading, an h2 unless titleLevel sets another level. |
Settings | 1 | 2 | 3 | 4 | 5 | 6 | 2 | Heading level of the title, with the same look at every level. A list inside a section of a settings page takes the next level. |
Settings | ReactNode | unset | Section help text. |
Settings | ReactNode | required | Accessible control label. |
Settings | ReactNode | unset | Associated description. |
Settings | (props: SettingsListControlProps) => ReactNode | required | Renders the actual control with generated aria-labelledby and optional aria-describedby. An action button takes only aria-describedby, so it keeps its own text as its name. |
Settings | inline | responsive | responsive | Responsive stacks until the list is 36rem (576 px) wide; inline keeps label and control together. |
Settings | ReactNode | unset | Supplementary tag beside the title. |
SettingsListProps extends native section props without native title. SettingsListItemProps extends native div props without title/children. SettingsListControlProps contains aria-labelledby and optional aria-describedby. Both wrappers accept className but their types do not expose ref. The card, separators and associations are provided by the component; values, request state, validation and saving are application-owned.
Usage notes
Use responsive layout for wider text controls. The rows follow the width of the list, not of the screen: a responsive row puts its control beside its copy once the list is 36rem (576 px) wide, and the card padding, the header inset and the row gaps widen with it. A list beside a sidebar or in a column therefore stays stacked while it is narrow. The list is a size container named settings-list, so a control can follow the same switch: className="w-full @min-[36rem]/settings-list:w-80" fills a stacked row and takes 320 px beside the copy. Do not replace control props with hard-coded labels that break the generated association. The list itself is not a form and does not submit values.