Settings dialog with grouped side navigation and pages of setting rows: switches, fields and pick-one menus, with an optional Save / Cancel footer.
Workspace settings
Grouped navigation on the left, rows of fields, switches and pick-one menus on the right, and Cancel / Save pinned to the bottom. On phones the navigation becomes an icon rail.
Installation
Copies the component into src/design-system/ as your own source, with only the files it needs.
npx avesk-ui@latest add settings-modalBrings the 5 files it builds on (dialog.tsx, button.tsx, glyph.tsx, icon.tsx, scroll-area.tsx). The first time, it also adds the tokens and the cn() helper, imports the tokens in globals.css and installs clsx and tailwind-merge. Files already in your project are kept unless you add --force.
Import
Lives in src/design-system/components/settings-modal.tsx.
import { SettingsModal, SettingsSection, SettingsRow } from "@/design-system/components/settings-modal";Usage
<SettingsModal
open={open}
onOpenChange={setOpen}
defaultPage="billing"
groups={[{ label: "Workspace", pages: [{ id: "billing", label: "Billing", icon: "giro-cards", content: <BillingPage /> }] }]}
footer={<><Button onClick={cancel}>Cancel</Button><Button variant="primary" onClick={save}>Save changes</Button></>}
/>Examples
Open on a page
defaultPage opens the modal where a contextual action points; it resets on every open.
Without a footer
Leave out footer when every control applies at once (switches, segmented choices).
When to use
Use it when
- Workspace, billing, notification and client-portal settings opened from the account menu or sidebar
- Several pages of settings that belong together but don't need their own URLs
- Opening straight onto one page from a contextual action (defaultPage)
Rules
- It renders no trigger: keep open in the screen that owns the menu item or button
- Build pages from SettingsSection + SettingsRow; controls are the usual Switch, Input, DropdownMenu (checked items), SegmentedControl and Button
- Add footer (Cancel, then Save) when there are typed fields; leave it out when every control applies at once
- Give every row's control htmlFor/id, and point aria-describedby at `${id}-description` when the row has a description
- Name a pick-one DropdownMenu with its row label and value, e.g. aria-label="Default currency: USD"
Properties
SettingsModal
| Prop | Type | Default |
|---|---|---|
open * | boolean | – |
onOpenChange * | (open: boolean) => void | – |
groups * | SettingsNavGroup[] | – |
defaultPage | string | first page |
page | string | – |
onPageChange | (page: string) => void | – |
title | string | "Settings" |
footer | ReactNode | – |
className | string | – |
SettingsSection
| Prop | Type | Default |
|---|---|---|
title | string | – |
description | ReactNode | – |
action | ReactNode | – |
children * | ReactNode | – |
className | string | – |
SettingsRow
| Prop | Type | Default |
|---|---|---|
label * | ReactNode | – |
description | ReactNode | – |
htmlFor | string | – |
children | ReactNode | – |
className | string | – |
SettingsPage
| Prop | Type | Default |
|---|---|---|
id * | string | – |
label * | string | – |
icon * | IconName | – |
content * | ReactNode | – |
* required
Accessibility
- Built on Dialog (native <dialog>): focus is trapped, Escape and the backdrop close it, focus returns to the trigger
- The dialog is named by title (visually hidden); the current page name is the visible heading
- Navigation is a labelled <nav>; the current page has aria-current="page" and gets focus on open
- On phones the navigation is an icon rail; each icon keeps its text label for screen readers
- Clicking a row's label focuses or toggles its control