SettingsModal
Overlays

SettingsModal

Settings dialog with a persistent nav rail on the left and a titled, scrolling pane on the right. Used for account, workspace, and project settings.

Preview

SettingsModal

How it works

The nav is data-driven from a SettingsSection[]: grouped headings, icons, badges, and per-section header actions all live in that array. The active section's body is children, which the caller swaps on activeSection (controllable via activeSection / onSectionChange, or uncontrolled via defaultSection). Every pane gets the same header, scroll region, and footer bar.

Compose the body from SettingsGroup and SettingsRow so rows line up consistently across apps. The overlay mechanics (portal, backdrop, Escape, scroll lock, focus trap) come from the shared Dialog primitive, as in Modal and Drawer.

SettingsModalProps props
PropTypeDefaultDescription
openboolean—Controls visibility.
onClose() => void—Escape / backdrop / close-button handler.
sectionsSettingsSection[]—The nav model. Order is preserved; group collapses runs into headings.
activeSectionstring—Controlled active id. Pair with onSectionChange.
defaultSectionstring—Uncontrolled initial id. Defaults to the first enabled section.
onSectionChange(id: string) => void—Called when the active section changes.
titleReactNode"Settings"Heading above the settings navigation.
subReactNode—Dim line under the sidebar heading (the org / account name).
brandReactNode—Logo mark beside the sidebar heading.
searchboolean—Adds a filter box over the nav.
searchPlaceholderstring"Search settings…"Placeholder for the nav filter.
navFooterReactNode—Pinned to the bottom of the sidebar (a 'sign out' row, a plan chip).
footerReactNode—Footer content below the active pane. Omit for auto-saving panes.
widthnumber780Panel width in px.
closeLabelstring"Close settings"Accessible label for the pane's close button.
childrenReactNode—The active section's body. Swap it on activeSection.

SettingsSection

SettingsSection props
PropTypeDefaultDescription
idstring—Stable section ID used by activeSection and onSectionChange.
labelReactNode—Nav label; also the pane header title unless title overrides it.
iconReactNode—Leading nav icon.
groupstring—Uppercase divider heading; consecutive sections with the same group share one heading.
titleReactNode—Pane header title, when it should differ from the nav label.
descriptionReactNode—Dim line under the pane title.
badgeReactNode—Content after the navigation label.
headerActionsReactNode—Right-aligned actions in this section's pane header.
disabledboolean—Greys out and disables the nav item.
keywordsstring—Extra words the nav search should match beyond the label text.

Usage

ImportTSX
import {
  SettingsModal,
  SettingsGroup,
  SettingsRow,
  Switch,
  Select,
  Input,
  Field,
  Button,
} from "@solarius/onset";
import type { SettingsSection } from "@solarius/onset";
import { IconUserCircle, IconBell, IconLock } from "@tabler/icons-react";
import { useState } from "react";

const sections: SettingsSection[] = [
  {
    id: "profile",
    label: "Profile",
    icon: <IconUserCircle size={15} />,
    group: "Account",
    description: "Profile settings displayed throughout the application.",
  },
  {
    id: "notifications",
    label: "Notifications",
    icon: <IconBell size={15} />,
    group: "Account",
  },
  {
    id: "security",
    label: "Security",
    icon: <IconLock size={15} />,
    group: "Account",
  },
];

function Settings() {
  const [open, setOpen] = useState(false);
  const [section, setSection] = useState("profile");

  return (
    <>
      <Button onClick={() => setOpen(true)}>Settings</Button>
      <SettingsModal
        open={open}
        onClose={() => setOpen(false)}
        sections={sections}
        activeSection={section}
        onSectionChange={setSection}
        title="Settings"
        sub="Acme Commerce"
        search
        footer={
          <>
            <Button variant="ghost" onClick={() => setOpen(false)}>
              Cancel
            </Button>
            <Button variant="primary" onClick={() => setOpen(false)}>
              Save changes
            </Button>
          </>
        }
      >
        {section === "profile" && (
          <SettingsGroup
            title="Profile"
            description="Shown on comments and audit logs."
          >
            <SettingsRow label="Display name" htmlFor="name" stacked>
              <Input id="name" defaultValue="Malaika Okafor" />
            </SettingsRow>
            <SettingsRow label="Role">
              <Select
                defaultValue="ops"
                options={[{ value: "ops", label: "Finance operations" }]}
              />
            </SettingsRow>
          </SettingsGroup>
        )}

        {section === "notifications" && (
          <SettingsGroup title="Alerts">
            <SettingsRow
              label="Disputes opened"
              description="A cardholder opened a chargeback."
            >
              <Switch checked onChange={() => {}} />
            </SettingsRow>
          </SettingsGroup>
        )}
      </SettingsModal>
    </>
  );
}

Content helpers

Two helpers keep every pane's rows aligned. SettingsGroup is a titled, framed block; SettingsRow is one setting: label and description on the left, control on the right (or stacked underneath for wide inputs).

SettingsGroup

SettingsGroupProps extends HTMLAttributes<HTMLElement> props
PropTypeDefaultDescription
titleReactNode—Group heading, above the framed rows.
descriptionReactNode—Dim line under the heading.
actionReactNode—Right-aligned slot next to the heading (a group-level action).
plainboolean—Removes the outer border and row borders.
childrenReactNode—SettingsRows, or arbitrary content when plain.

SettingsRow

SettingsRowProps props
PropTypeDefaultDescription
labelReactNode—The setting's name.
descriptionReactNode—Dim explanatory line under the label.
htmlForstring—Renders the label as a <label> bound to this control id.
stackedboolean—Stacks the control under the label (for wide inputs and textareas).
childrenReactNode—The control(s), right-aligned unless stacked.