Settings Layout React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Settings Layout is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import SettingsLayout from @/components/ui/settings-layout.

import { Bell, User } from "lucide-react"
import { useState } from "react"
import { Input } from "@/components/ui/input"
import { SettingsLayout, SettingsRow, SettingsSection } from "@/components/ui/settings-layout"
import { Switch } from "@/components/ui/switch"

export function AccountSettings() {
  const [saved, setSaved] = useState({ name: "Emma Carter", digest: true })
  const [draft, setDraft] = useState(saved)
  const dirty = draft.name !== saved.name || draft.digest !== saved.digest

  return (
    <SettingsLayout
      title="Settings"
      dirty={dirty}
      onSave={async () => {
        await fetch("/api/settings", { method: "PUT", body: JSON.stringify(draft) })
        setSaved(draft)
      }}
      onDiscard={() => setDraft(saved)}
      labels={{ unsaved: "You have unsaved changes", save: "Save changes" }}
      sections={[
        {
          id: "profile",
          label: "Profile",
          icon: <User />,
          content: (
            <SettingsSection title="Public profile">
              <SettingsRow label="Name" controlWidth="md">
                <Input value={draft.name} onValueChange={(name) => setDraft({ ...draft, name })} autoComplete="name" />
              </SettingsRow>
            </SettingsSection>
          ),
        },
        {
          id: "notifications",
          label: "Notifications",
          icon: <Bell />,
          content: (
            <SettingsSection title="Email">
              <SettingsRow label="Daily digest" description="Sales and overdue invoices, at 8 AM.">
                <Switch checked={draft.digest} onCheckedChange={(digest) => setDraft({ ...draft, digest })} />
              </SettingsRow>
            </SettingsSection>
          ),
        },
      ]}
    />
  )
}

Props

• sections*
  SettingsNavItem[]

  The sections: { id, label, icon?, description? (the phone list subtitle), group? (eyebrow label), badge? (a number is a count), href? (a route, wins over content), disabled?, danger?, tone? (the phone icon tile), content? }.

• defaultValuedefault "profile"
  string

  The section open at first, uncontrolled. Pair value / onValueChange to drive it from the URL. The code default is the first enabled section; an unknown id falls back to it too.

• value
  string

  The active section id, controlled.

• onValueChange
  (id: string) => void

  Every switch: a nav click (after the leave confirm), a phone row, the tabs or select, and the scroll spy.

• titledefault ""
  ReactNode

  The page heading (an h1, see headingAs). On phones it becomes the large title of the grouped list.

• headingAsdefault "h1"
  "h1" | "h2" | "h3" | "div"

  The element of the title and of the section title on phones. Keep h1 for a settings page; use h2, h3 or div when the layout sits inside a page that already has its h1.

• descriptiondefault ""
  ReactNode

  A line under the title.

• children
  ReactNode | ((activeId: string) => ReactNode)

  The content when sections[].content is not used: a function gets the active id (in scroll mode, each id in turn). Sections with an href always render children.

• modedefault "pages"
  "pages" | "scroll"

  pages: only the active section shows and swaps with a fade. scroll: every section stacked on one page, the nav follows the scroll (an IntersectionObserver spy on the page's scroll container) and a click scrolls there.

• navdefault "sidebar"
  "sidebar" | "tabs" | "none"

  Desktop navigation: a sticky left column, underline tabs above the content, or none. One section never shows a nav.

• navWidthdefault 240
  number

  The sidebar column in px.

• mobileNavdefault "list"
  "list" | "tabs" | "select"

  Below 768px of its own width: an iOS grouped list that pushes the section (split-view stack with swipe back), scrolling pill tabs, or a select (a bottom sheet). Scroll mode uses tabs for list.

• dirtydefault false
  boolean

  Something changed: shows the save bar, binds saveShortcut and arms the leave guards. The demo also turns it on as soon as you edit a field.

• savingdefault false
  boolean

  The save button's loading state, for a save you track yourself. It also loads while an onSave promise runs; turning false with dirty off flashes the saved message.

• onSave
  (() => void | Promise<unknown>)

  Runs from the button or the shortcut. A promise keeps the button loading; resolved flashes labels.saved for 1.2s, rejected keeps the bar, shakes it and shows the error's message (else labels.saveError).

• onDiscard
  () => void

  The Discard button, and a confirmed leave. Put the saved values back here.

• saveShortcutdefault "mod+s"
  string

  Saves while dirty (it replaces the browser's Save Page only then). Shown as a key hint on the button, hidden on touch. "" disables.

• confirmLeavedefault true
  boolean

  Pages mode: switching sections while dirty asks "Discard changes?" (Discard / Keep editing) and calls onDiscard when confirmed. Links (href items) are the router's to guard.

• warnBeforeUnloaddefault true
  boolean

  The browser's leave-page warning while dirty.

• saveBarPositiondefault "sticky"
  "sticky" | "fixed"

  sticky: floats at the bottom of the content column while you scroll; fixed: pinned to the viewport. Phones always pin it above --bottom-bar-offset and the safe area, lifted over the keyboard.

• sizedefault "md"
  "sm" | "md"

  Nav rows 32 / 36px (44px on touch) and the row padding (48 / 56px rows).

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The nav indicator (a soft tint of the tone) and the save button. Neutral is a gray pill and an inverted button.

• linkComponent
  (props: LinkComponentProps) => ReactNode

  Renders nav items that have an href (settings as routes). Defaults to the LinkProvider's, else a plain <a>.

• labels
  Partial<SettingsLayoutLabels>

  Every string: nav "Settings", unsaved "You have unsaved changes", save "Save", saving "Saving…", discard "Discard", saved "Changes saved", saveError "Could not save. Try again.", leaveTitle "Discard changes?", leaveDescription "Your changes in this section will be lost.", leaveConfirm "Discard", leaveCancel "Keep editing", back "Settings", select "Section". Exported as DEFAULT_SETTINGS_LAYOUT_LABELS.

• classNames
  Partial<Record<"frame" | "header" | "title" | "description" | "nav" | "group" | "item" | "indicator" | "content" | "mobileNav" | "mobileList" | "mobileItem" | "mobileDetail" | "saveBar", string>>

  Extra classes for the parts. The phone stack's height is the --settings-mobile-height variable (default 100dvh minus --topbar-offset).

Parts

FAQ

Used in

More React layout components