feat(ui): Mosaic Settings component#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

Merged
austincalvelage merged 6 commits into from
Aug 12, 2026
Merged

feat(ui): Mosaic Settings component #9377

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 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
c3954e5
refactor(ui): move Settings from block to component
alexcarpenter 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 numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---
Comment on lines +1 to +2

@coderabbitaicoderabbitaiBotAug 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 numberDiff line numberDiff line change
Expand Up@@ -42,6 +42,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
icon: dynamic(() => import('../stories/icon.mdx')),
menu: dynamic(() => import('../stories/menu.component.mdx')),
popover: dynamic(() => import('../stories/popover.component.mdx')),
settings: dynamic(() => import('../stories/settings.mdx')),
tabs: dynamic(() => import('../stories/tabs.component.mdx')),
text: dynamic(() => import('../stories/text.mdx')),
field: dynamic(() => import('../stories/field.component.mdx')),
Expand Down
15 changes: 15 additions & 0 deletions packages/swingset/src/lib/registry.ts
View file
Open in desktop
Original file line numberDiff line numberDiff 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 DownExpand Up@@ -281,6 +295,7 @@ export const registry: StoryModule[] = [
iconModule,
menuComponentModule,
popoverComponentModule,
settingsModule,
tabsComponentModule,
textModule,
fieldModule,
Expand Down
74 changes: 74 additions & 0 deletions packages/swingset/src/stories/settings.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
import * as SettingsStories from './settings.stories';

# Settings

A settings component 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/components/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

@coderabbitaicoderabbitaiBotAug 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
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
feat(ui): Mosaic Settings component#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

 Merged

austincalvelage
merged 6 commits into

from

Aug 12, 2026
 Merged


feat(ui): Mosaic Settings component
#9377
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 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
c3954e5

refactor(ui): move Settings from block to component


alexcarpenter 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 numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---

Comment on lines

+1
 to 
+2

@coderabbitaicoderabbitaiBotAug 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 numberDiff line numberDiff line change
Expand Up@@ -42,6 +42,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
 icon: dynamic(() => import('../stories/icon.mdx')),
 menu: dynamic(() => import('../stories/menu.component.mdx')),
 popover: dynamic(() => import('../stories/popover.component.mdx')),
 settings: dynamic(() => import('../stories/settings.mdx')),
 tabs: dynamic(() => import('../stories/tabs.component.mdx')),
 text: dynamic(() => import('../stories/text.mdx')),
 field: dynamic(() => import('../stories/field.component.mdx')),
Expand Down

15 changes: 15 additions & 0 deletions
packages/swingset/src/lib/registry.ts

View file


Open in desktop

Original file line numberDiff line numberDiff 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 DownExpand Up@@ -281,6 +295,7 @@ export const registry: StoryModule[] = [
 iconModule,
 menuComponentModule,
 popoverComponentModule,
 settingsModule,
 tabsComponentModule,
 textModule,
 fieldModule,
Expand Down

74 changes: 74 additions & 0 deletions
packages/swingset/src/stories/settings.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
import * as SettingsStories from './settings.stories';

# Settings

A settings component 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/components/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

@coderabbitaicoderabbitaiBotAug 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

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(ui): Mosaic Settings component#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

 Merged

austincalvelage
merged 6 commits into

from

Aug 12, 2026
 Merged


feat(ui): Mosaic Settings component
#9377
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 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
c3954e5

refactor(ui): move Settings from block to component


alexcarpenter 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 numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---

Comment on lines

+1
 to 
+2

@coderabbitaicoderabbitaiBotAug 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 numberDiff line numberDiff line change
Expand Up@@ -42,6 +42,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
 icon: dynamic(() => import('../stories/icon.mdx')),
 menu: dynamic(() => import('../stories/menu.component.mdx')),
 popover: dynamic(() => import('../stories/popover.component.mdx')),
 settings: dynamic(() => import('../stories/settings.mdx')),
 tabs: dynamic(() => import('../stories/tabs.component.mdx')),
 text: dynamic(() => import('../stories/text.mdx')),
 field: dynamic(() => import('../stories/field.component.mdx')),
Expand Down

15 changes: 15 additions & 0 deletions
packages/swingset/src/lib/registry.ts

View file


Open in desktop

Original file line numberDiff line numberDiff 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 DownExpand Up@@ -281,6 +295,7 @@ export const registry: StoryModule[] = [
 iconModule,
 menuComponentModule,
 popoverComponentModule,
 settingsModule,
 tabsComponentModule,
 textModule,
 fieldModule,
Expand Down

74 changes: 74 additions & 0 deletions
packages/swingset/src/stories/settings.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
import * as SettingsStories from './settings.stories';

# Settings

A settings component 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/components/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

@coderabbitaicoderabbitaiBotAug 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

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(ui): Mosaic Settings component#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

 Merged

austincalvelage
merged 6 commits into

from

Aug 12, 2026
 Merged


feat(ui): Mosaic Settings component
#9377
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 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
c3954e5

refactor(ui): move Settings from block to component


alexcarpenter 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 numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---

Comment on lines

+1
 to 
+2

@coderabbitaicoderabbitaiBotAug 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 numberDiff line numberDiff line change
Expand Up@@ -42,6 +42,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
 icon: dynamic(() => import('../stories/icon.mdx')),
 menu: dynamic(() => import('../stories/menu.component.mdx')),
 popover: dynamic(() => import('../stories/popover.component.mdx')),
 settings: dynamic(() => import('../stories/settings.mdx')),
 tabs: dynamic(() => import('../stories/tabs.component.mdx')),
 text: dynamic(() => import('../stories/text.mdx')),
 field: dynamic(() => import('../stories/field.component.mdx')),
Expand Down

15 changes: 15 additions & 0 deletions
packages/swingset/src/lib/registry.ts

View file


Open in desktop

Original file line numberDiff line numberDiff 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 DownExpand Up@@ -281,6 +295,7 @@ export const registry: StoryModule[] = [
 iconModule,
 menuComponentModule,
 popoverComponentModule,
 settingsModule,
 tabsComponentModule,
 textModule,
 fieldModule,
Expand Down

74 changes: 74 additions & 0 deletions
packages/swingset/src/stories/settings.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
import * as SettingsStories from './settings.stories';

# Settings

A settings component 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/components/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

@coderabbitaicoderabbitaiBotAug 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

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
feat(ui): Mosaic Settings component#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

 Merged

austincalvelage
merged 6 commits into

from

Aug 12, 2026
 Merged


feat(ui): Mosaic Settings component
#9377
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 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
c3954e5

refactor(ui): move Settings from block to component


alexcarpenter 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 numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---

Comment on lines

+1
 to 
+2

@coderabbitaicoderabbitaiBotAug 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 numberDiff line numberDiff line change
Expand Up@@ -42,6 +42,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
 icon: dynamic(() => import('../stories/icon.mdx')),
 menu: dynamic(() => import('../stories/menu.component.mdx')),
 popover: dynamic(() => import('../stories/popover.component.mdx')),
 settings: dynamic(() => import('../stories/settings.mdx')),
 tabs: dynamic(() => import('../stories/tabs.component.mdx')),
 text: dynamic(() => import('../stories/text.mdx')),
 field: dynamic(() => import('../stories/field.component.mdx')),
Expand Down

15 changes: 15 additions & 0 deletions
packages/swingset/src/lib/registry.ts

View file


Open in desktop

Original file line numberDiff line numberDiff 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 DownExpand Up@@ -281,6 +295,7 @@ export const registry: StoryModule[] = [
 iconModule,
 menuComponentModule,
 popoverComponentModule,
 settingsModule,
 tabsComponentModule,
 textModule,
 fieldModule,
Expand Down

74 changes: 74 additions & 0 deletions
packages/swingset/src/stories/settings.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
import * as SettingsStories from './settings.stories';

# Settings

A settings component 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/components/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

@coderabbitaicoderabbitaiBotAug 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

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(ui): Mosaic Settings component#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

 Merged

austincalvelage
merged 6 commits into

from

Aug 12, 2026
 Merged


feat(ui): Mosaic Settings component
#9377
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 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
c3954e5

refactor(ui): move Settings from block to component


alexcarpenter 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 numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---

Comment on lines

+1
 to 
+2

@coderabbitaicoderabbitaiBotAug 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 numberDiff line numberDiff line change
Expand Up@@ -42,6 +42,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
 icon: dynamic(() => import('../stories/icon.mdx')),
 menu: dynamic(() => import('../stories/menu.component.mdx')),
 popover: dynamic(() => import('../stories/popover.component.mdx')),
 settings: dynamic(() => import('../stories/settings.mdx')),
 tabs: dynamic(() => import('../stories/tabs.component.mdx')),
 text: dynamic(() => import('../stories/text.mdx')),
 field: dynamic(() => import('../stories/field.component.mdx')),
Expand Down

15 changes: 15 additions & 0 deletions
packages/swingset/src/lib/registry.ts

View file


Open in desktop

Original file line numberDiff line numberDiff 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 DownExpand Up@@ -281,6 +295,7 @@ export const registry: StoryModule[] = [
 iconModule,
 menuComponentModule,
 popoverComponentModule,
 settingsModule,
 tabsComponentModule,
 textModule,
 fieldModule,
Expand Down

74 changes: 74 additions & 0 deletions
packages/swingset/src/stories/settings.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
import * as SettingsStories from './settings.stories';

# Settings

A settings component 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/components/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

@coderabbitaicoderabbitaiBotAug 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

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(ui): Mosaic Settings component#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

 Merged

austincalvelage
merged 6 commits into

from

Aug 12, 2026
 Merged


feat(ui): Mosaic Settings component
#9377
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 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
c3954e5

refactor(ui): move Settings from block to component


alexcarpenter 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 numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---

Comment on lines

+1
 to 
+2

@coderabbitaicoderabbitaiBotAug 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 numberDiff line numberDiff line change
Expand Up@@ -42,6 +42,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
 icon: dynamic(() => import('../stories/icon.mdx')),
 menu: dynamic(() => import('../stories/menu.component.mdx')),
 popover: dynamic(() => import('../stories/popover.component.mdx')),
 settings: dynamic(() => import('../stories/settings.mdx')),
 tabs: dynamic(() => import('../stories/tabs.component.mdx')),
 text: dynamic(() => import('../stories/text.mdx')),
 field: dynamic(() => import('../stories/field.component.mdx')),
Expand Down

15 changes: 15 additions & 0 deletions
packages/swingset/src/lib/registry.ts

View file


Open in desktop

Original file line numberDiff line numberDiff 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 DownExpand Up@@ -281,6 +295,7 @@ export const registry: StoryModule[] = [
 iconModule,
 menuComponentModule,
 popoverComponentModule,
 settingsModule,
 tabsComponentModule,
 textModule,
 fieldModule,
Expand Down

74 changes: 74 additions & 0 deletions
packages/swingset/src/stories/settings.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
import * as SettingsStories from './settings.stories';

# Settings

A settings component 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/components/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

@coderabbitaicoderabbitaiBotAug 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

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
feat(ui): Mosaic Settings component#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

 Merged

austincalvelage
merged 6 commits into

from

Aug 12, 2026
 Merged


feat(ui): Mosaic Settings component
#9377
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 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
c3954e5

refactor(ui): move Settings from block to component


alexcarpenter 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 numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---

Comment on lines

+1
 to 
+2

@coderabbitaicoderabbitaiBotAug 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 numberDiff line numberDiff line change
Expand Up@@ -42,6 +42,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
 icon: dynamic(() => import('../stories/icon.mdx')),
 menu: dynamic(() => import('../stories/menu.component.mdx')),
 popover: dynamic(() => import('../stories/popover.component.mdx')),
 settings: dynamic(() => import('../stories/settings.mdx')),
 tabs: dynamic(() => import('../stories/tabs.component.mdx')),
 text: dynamic(() => import('../stories/text.mdx')),
 field: dynamic(() => import('../stories/field.component.mdx')),
Expand Down

15 changes: 15 additions & 0 deletions
packages/swingset/src/lib/registry.ts

View file


Open in desktop

Original file line numberDiff line numberDiff 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 DownExpand Up@@ -281,6 +295,7 @@ export const registry: StoryModule[] = [
 iconModule,
 menuComponentModule,
 popoverComponentModule,
 settingsModule,
 tabsComponentModule,
 textModule,
 fieldModule,
Expand Down

74 changes: 74 additions & 0 deletions
packages/swingset/src/stories/settings.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
import * as SettingsStories from './settings.stories';

# Settings

A settings component 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/components/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

@coderabbitaicoderabbitaiBotAug 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