Skip to content

feat(ui): Settings block #9377

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
austincalvelage wants to merge 5 commits into
base: main
Choose a base branch
from
Open

feat(ui): Settings block #9377

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c30f053
feat(ui): add SettingsGroup block
austincalvelage Aug 10, 2026
7d5faf9
feat(ui): rework settings block composition
austincalvelage Aug 11, 2026
2c8760c
docs(swingset): document settings composition
austincalvelage Aug 11, 2026
5a6ccdb
feat(ui): rename Settings block and expose item gap
austincalvelage Aug 12, 2026
0cd0c3e
Merge branch 'main' into austin/user-profile-02-settings-group
austincalvelage Aug 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .changeset/settings-block.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
---
---
Comment on lines +1 to +2

@coderabbitai coderabbitai Bot Aug 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Add a release entry for @clerk/ui.

This PR adds the public Settings API. An empty changeset produces no @clerk/ui release or changelog entry. Add the appropriate version bump and a concise release note.

Proposed changeset 
 ---
+"`@clerk/ui`": minor
 ---
+
+Add the Settings Mosaic block.

As per coding guidelines, “Use Changesets for version management and changelogs.” Based on learnings, empty changesets apply only when changes do not include functionality changes.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
---
---
---
"`@clerk/ui`": minor
---
Add the Settings Mosaic block.
---
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.changeset/settings-block.md around lines 1 - 2, Update the changeset
frontmatter in settings-block.md to include an appropriate release bump for
`@clerk/ui`, and add a concise release note describing the new public Settings
API.

Sources: Coding guidelines, Learnings

1 change: 1 addition & 0 deletions packages/swingset/src/components/DocsViewer.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
},
blocks: {
destructive: dynamic(() => import('../stories/destructive.mdx')),
settings: dynamic(() => import('../stories/settings.mdx')),
},
components: {
avatar: dynamic(() => import('../stories/avatar.mdx')),
Expand Down
15 changes: 15 additions & 0 deletions packages/swingset/src/lib/registry.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,13 @@ import {
ThemedScrollbar as ScrollAreaThemedScrollbar,
} from '../stories/scroll-area.stories';
import { meta as selectMeta } from '../stories/select.stories';
import {
ConnectedAccounts as SettingsConnectedAccounts,
Default as SettingsDefault,
Destructive as SettingsDestructive,
meta as settingsMeta,
MultipleEmailAndPhoneNumbers as SettingsMultipleEmailAndPhoneNumbers,
} from '../stories/settings.stories';
import { Default as TabsComponentDefault, meta as tabsComponentMeta } from '../stories/tabs.component.stories';
import { meta as tabsMeta } from '../stories/tabs.stories';
import {
Expand All @@ -126,6 +133,13 @@ import { toSlug } from './slug';
import type { StoryModule } from './types';

const destructiveModule: StoryModule = { meta: destructiveMeta, Default: DestructiveDefault };
const settingsModule: StoryModule = {
meta: settingsMeta,
Default: SettingsDefault,
MultipleEmailAndPhoneNumbers: SettingsMultipleEmailAndPhoneNumbers,
ConnectedAccounts: SettingsConnectedAccounts,
Destructive: SettingsDestructive,
};
const organizationProfileLeaveSectionModule: StoryModule = {
meta: organizationProfileLeaveSectionMeta,
Default: OrganizationProfileLeaveSectionDefault,
Expand Down Expand Up @@ -269,6 +283,7 @@ export const registry: StoryModule[] = [
organizationProfileDeleteSectionModule,
// Blocks
destructiveModule,
settingsModule,
// Components
avatarModule,
badgeModule,
Expand Down
74 changes: 74 additions & 0 deletions packages/swingset/src/stories/settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
import * as SettingsStories from './settings.stories';

# Settings

A settings block that carries the canonical section, surface, row grouping, and item layout. Use it for product settings while composing each item's media, content, and actions as needed.

## Usage

```tsx
import { Settings } from '@clerk/ui/mosaic/block/settings';

<Settings.Root>
<Settings.Title>Account</Settings.Title>
<Settings.Group>
<Settings.Row>
<Settings.Item>
<Settings.Media>{icon}</Settings.Media>
<Settings.Content>
<Settings.Label>Name</Settings.Label>
<Settings.Description>Shown throughout the application.</Settings.Description>
</Settings.Content>
<Settings.Actions>{control}</Settings.Actions>
</Settings.Item>
</Settings.Row>
</Settings.Group>
</Settings.Root>
```

`Settings.Group` owns the outlined surface. Its direct `Settings.Row` children own separation and may stack one or more `Settings.Item` entries. Each item lays out optional media, flexible content, and trailing actions. `Settings.Media` accepts `md` and `lg` sizes.

Use `Settings.Items` for a nested value list beneath a row's header item. The row keeps an 8px header-to-list gap, nested items stack without gaps at a 44px minimum height, and their content receives 12px vertical padding.

Override `--cl-settings-items-gap` on `Settings.Root` or a specific `Settings.Row` to customize the space between the row header and its nested value list. It defaults to 8px.

## Examples

<Story
name='Default'
storyModule={SettingsStories}
composition={[
{ name: 'Avatar', href: '/components/avatar', layer: 'Components' },
{ name: 'Button', href: '/components/button', layer: 'Components' },
]}
/>

### Multiple email addresses and phone numbers

<Story
name='MultipleEmailAndPhoneNumbers'
storyModule={SettingsStories}
composition={[
{ name: 'Badge', href: '/components/badge', layer: 'Components' },
{ name: 'Button', href: '/components/button', layer: 'Components' },
{ name: 'Icon', href: '/components/icon', layer: 'Components' },
]}
/>

### Connected accounts

<Story
name='ConnectedAccounts'
storyModule={SettingsStories}
composition={[
{ name: 'Button', href: '/components/button', layer: 'Components' },
{ name: 'Icon', href: '/components/icon', layer: 'Components' },
]}
/>

### Destructive setting

<Story
name='Destructive'
storyModule={SettingsStories}
/>
Comment on lines +7 to +74

@coderabbitai coderabbitai Bot Aug 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use the compound component page structure.

Settings is a compound component. This page starts with Usage and Examples and omits Example, Parts, and Styling.

Use Example, Usage, Parts, and Styling as the top-level headings in that order. Put Default in Example. Document subcomponents in Parts. Document --cl-settings-items-gap in Styling.

As per coding guidelines, “Compound Components pages must use the exact section order: Example, Usage, Parts, then Styling.” Based on learnings, preserve the archetype required by meta.group.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/swingset/src/stories/settings.mdx` around lines 7 - 74, Reorganize
the Settings compound-component page to use the required top-level headings in
order: Example, Usage, Parts, and Styling. Move the Default story under Example,
document Settings subcomponents under Parts, and move the
--cl-settings-items-gap guidance under Styling while preserving the existing
usage and example stories and the archetype required by meta.group.

Sources: Coding guidelines, Learnings

Loading
Loading