# Settings

A React block (a whole screen) in [Beamline](https://beamline.io/)'s [Blocks](https://beamline.io/components/blocks) category, in the free sample. Live demo: https://beamline.io/components/settings

Profile and workspace settings with one draft and real save handler. Personal mode omits workspace data; optional profile fields share validation, persistence, error recovery and focus return. Existing members, billing, notifications and API sections remain available.

## Use it for

- The settings area of a SaaS product: personal, workspace, team, billing and developer settings behind one section list.
- One section inside your own page (navigation none + section): it sits flush on your page's background and edge, under your heading.

## Not for

- A single preference (a [switch](https://beamline.io/components/switch) where the setting takes effect).
- Onboarding (a [stepper](https://beamline.io/components/stepper) flow).

## Anatomy

- section list (a column; a scrolling row under 760px)
- section header (title, description, last-saved caption, action)
- fields
- members table (role select, actions menu)
- plan cards, period toggle and plan-change bar
- usage meters
- API key rows
- danger zone
- save bar (count, Discard, Save)
- toasts
- explicit rail, tabs or no section navigation; optional heading with an aside (e.g. where saves are kept); in tabs mode heading, tab row, form and save bar share one 720px column
- dirty section markers and field error links
- sticky save bar as wide as the form

## States

- clean
- dirty (save bar counts changes)
- invalid field (save disabled, field says why)
- saving
- save failed (bar keeps the message, Save becomes Try again)
- invite dialog: sending, failed
- role change failed (reverted)
- remove member / withdraw invitation (confirm)
- plan or period chosen, waiting for Switch plan
- key created (secret shown once)
- revoke key (confirm)
- deletion scheduling, scheduled, failed
- sections hidden when their data is not passed
- saved confirmation for 1.6 seconds; last-saved time
- discard returns focus to current section heading
- field-tagged save rejection marks and focuses the named field
- edits during a pending save remain as unsaved changes
- personal configuration without Workspace
- optional profile fields share the same save flow

## Keyboard

- Tab through the section list, then the section
- dialogs and confirmations trap focus; Esc closes; confirmations start on Cancel
- hold-to-confirm: hold Space or Enter
- Save success and Discard return focus to the current section heading
- A field-tagged save error focuses the visible field; Go to field switches section and focuses it

## Motion

The save bar rises on --motion-in; toasts follow the toast stack.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValues / values / onValuesChange` (required) | `SettingsValues` | — | Saved profile, workspace and notification values, controlled or not. |
| `onSave` (required) | `(values, changed: string[]) => Promise<void>` | — | Persist the draft; a rejection keeps the bar with its message. |
| `section / defaultSection / onSectionChange` | `SettingsSection` | — |  |
| `members / defaultMembers / onMembersChange` | `SettingsMember[]` | — | Adds the Members section. |
| `roles` | `SettingsRole[]` | — |  |
| `onInvite / onRoleChange / onRemoveMember` | `(emails, role) => Promise<SettingsMember[]> / (id, role) => Promise<void> / (id) => Promise<void>` | — |  |
| `plans / plan / defaultPlan / period / defaultPeriod / onPlanChange` | `SettingsPlan[] / string / "monthly" \| "yearly" / (plan, period) => Promise<void>` | — | Adds Billing; a change waits for Switch plan. |
| `seats / usage` | `number / SettingsUsage[]` | — |  |
| `apiKeys / defaultApiKeys / onApiKeysChange` | `SettingsApiKey[]` | — | Adds API keys. |
| `onCreateKey / onRevokeKey` | `(name) => Promise<{ key, secret }> / (id) => Promise<void>` | — |  |
| `onDeleteWorkspace` | `() => Promise<void>` | — | Adds the Danger zone. |
| `onPhotoChange` | `() => void` | — |  |
| `timeZones / domain / notificationOptions` | `string[] / string / SettingsNotification[]` | — |  |
| `className` | `string` | — |  |
| `navigation` | `"rail" \| "tabs" \| "none"` | — | Rail folds to tabs below 760px; use tabs when embedded in a host shell, none for host-routed sections. |
| `heading` | `ReactNode \| null` | — | Defaults to Settings; null leaves the page title to the host. |
| `profileFields` | `SettingsProfileField[]` | — | Extra profile Inputs keyed by SettingsValues.profile; optional empty strings are valid and changed keys use profile.<id>. |
| `SettingsValues.workspace / slug` | `string \| undefined` | — | Omit both for a personal profile; Workspace and its validation are then absent. |
| `onSave rejection` | `Error & { field?: string }` | — | Known field keys render inline and receive focus; unknown fields remain general errors. Never changes the saved baseline on failure. |
| `defaultDraft` | `Partial<SettingsValues>` | — | Optional restored draft applied once; shares the same validation, changed keys and save flow. |
| `classNames` | `SettingsClassNames` | — |  |
| `style / ref` | `CSSProperties / Ref<HTMLDivElement>` | — |  |

## Built from

- item
- avatar
- input
- combobox
- dialog
- [alert-dialog](https://beamline.io/components/alert-dialog)
- [tag-input](https://beamline.io/components/tag-input)
- select
- table
- [dropdown-menu](https://beamline.io/components/dropdown-menu)
- badge
- [billing-toggle](https://beamline.io/components/billing-toggle)
- [radio-cards](https://beamline.io/components/radio-cards)
- [usage-meter](https://beamline.io/components/usage-meter)
- switch
- [copy-button](https://beamline.io/components/copy-button)
- [hold-to-confirm](https://beamline.io/components/hold-to-confirm)
- alert
- button
- toast

## Dependencies

`lucide-react`, `motion`

## Import

```tsx
import { Settings } from "@/blocks/settings/settings";
```

## Get it

Settings is part of Beamline: 190 React components and screens your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 one payment (regular $200), no subscription, a year of updates, one licence for your whole team. Settings is in the free sample, which costs nothing. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Blocks

- [AI agent workspace](https://beamline.io/components/agent-workspace): Threads, a conversation with streamed reasoning, cited answers and a plan that waits for approval then runs step by step, and an artifacts panel with…
- [Analytics dashboard](https://beamline.io/components/analytics-dashboard): A SaaS overview in the app shell, fed by your metrics hook: range and segment filters drive KPIs, new and expansion revenue, channels, plan mix, uptime…
- [Auth page](https://beamline.io/components/auth): The whole sign-in / sign-up route: product mark, a quiet dotted field with a light that follows the mouse, an optional notice, the SignIn and SignupForm…
- [Changelog feed](https://beamline.io/components/changelog-feed): An in-app What's new page: release notes grouped by month with tags, versions, pictures and details, a tag filter with counts, entries since your last…
- [CRM pipeline](https://beamline.io/components/crm): A pipeline screen: KPIs and stage mix derived from a virtualised deals grid with inline edit, bulk moves and delete with undo; a row opens the deal in a…
- [Empty states](https://beamline.io/components/empty-states): The five empty moments every product has, written and wired: first use with a first step, no results with the filters to clear, an error with retry and a…
- [Page header](https://beamline.io/components/page-header): The top of a record or project page: breadcrumb, title with status, description and meta, a primary action with secondary actions that fold into a More…
- [Plan comparison](https://beamline.io/components/plan-comparison): Plans side by side against every feature: prices that roll between monthly and yearly, the current and recommended plan marked, a header that stays in…
- [Sign in](https://beamline.io/components/sign-in): The sign-in card: email and password, a one-time code or a magic link, passkeys and single sign-on, with validation, progress, errors and a signed-in…
- [Sign up form](https://beamline.io/components/signup-form): The account creation card: single sign-on, name, work email and a password with strength and Caps Lock hints, terms consent, inline validation, your…
- [Step form](https://beamline.io/components/step-form): The finished frame for any multi-step form you compose — onboarding, intake brief, questionnaire, booking, application: a wide card with progress, the…
- [Trading terminal](https://beamline.io/components/trading-terminal): A perpetuals terminal on your feed and your account: ticker tape, market header with funding, candles, book / trades / depth, order ticket, account…
- [Voice agent](https://beamline.io/components/voice-agent): A voice agent in three layouts on one session: a support panel that mixes typing and talking, a call screen with the agent's orb and one call button, and…