refactor(ui): rename Mosaic Item.Title to Item.Label#9412

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
alexcarpenter merged 1 commit into from
Aug 12, 2026
Merged

refactor(ui): rename Mosaic Item.Title to Item.Label #9412

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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/mosaic-item-title-to-label.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---
37 changes: 21 additions & 16 deletions packages/swingset/src/stories/item.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import * as ItemStories from './item.stories';

# Item

Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Title`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.
Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Label`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.

Set `size` once on `Item.Root` and the row scales as a unit: it fixes the row's height and gap, and `Item.Media` picks the matching column width up from context rather than taking a size of its own.

Expand DownExpand Up@@ -76,7 +76,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
</Avatar.Root>
</Item.Media>
<Item.Content>
<Item.Title>Test Organization</Item.Title>
<Item.Label>Test Organization</Item.Label>
<Item.Description>Member</Item.Description>
</Item.Content>
<Item.Actions>
Expand All@@ -86,38 +86,43 @@ import { Item } from '@clerk/ui/mosaic/components/item';
</Item.Group>;
```

Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:
Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. A row whose text _is_ the row, rather than naming a subject, uses `Item.Label` with `variant='secondary'`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
<Item.Media>
<Icon name='log-out' size='sm' />
</Item.Media>
<Item.Content>
<Item.Label>Sign out of all accounts</Item.Label>
<Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
</Item.Content>
</Item.Root>;
```

## Parts

| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the title. Truncates to a single line. |
| `Item.Label` | `cl-item-label` | Sole label on an action row, in place of a title. Inherits the row's text color. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |
| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Label` | `cl-item-label` | The row's label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the label. Truncates to a single line. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |

Every part accepts a `render` prop for element polymorphism and forwards a ref.

## Styling

The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon and `Item.Label` hold their resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.
The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon holds its resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.

`Item.Label` chooses whether it joins that promotion. `variant='primary'` sets its own color and holds it, so a subject the row names reads at full strength either way. `variant='secondary'` sets none and inherits the row's, so it fades and brightens with the row:

| Prop | Attribute | Values | Default |
| --------- | -------------- | ------------------------ | --------- |
| `variant` | `data-variant` | `primary` \| `secondary` | `primary` |

The root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

Expand Down
20 changes: 10 additions & 10 deletions packages/swingset/src/stories/item.stories.tsx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -32,7 +32,7 @@ export function Default() {
</Avatar.Root>
</Item.Media>
<Item.Content>
<Item.Title>Test Organization</Item.Title>
<Item.Label>Test Organization</Item.Label>
<Item.Description>Member</Item.Description>
</Item.Content>
<Item.Actions>
Expand DownExpand Up@@ -68,7 +68,7 @@ export function Interactive() {
</Avatar.Root>
</Item.Media>
<Item.Content>
<Item.Title>Test Organization</Item.Title>
<Item.Label>Test Organization</Item.Label>
<Item.Description>Member</Item.Description>
</Item.Content>
</Item.Root>
Expand All@@ -92,7 +92,7 @@ export function Sizes() {
</Avatar.Root>
</Item.Media>
<Item.Content>
<Item.Title>Test Organization</Item.Title>
<Item.Label>Test Organization</Item.Label>
</Item.Content>
</Item.Root>
))}
Expand All@@ -114,7 +114,7 @@ export function Group() {
</Avatar.Root>
</Item.Media>
<Item.Content>
<Item.Title>Cameron Walker</Item.Title>
<Item.Label>Cameron Walker</Item.Label>
<Item.Description>cameron@clerk.com</Item.Description>
</Item.Content>
<Item.Actions>
Expand DownExpand Up@@ -158,7 +158,7 @@ export function Group() {
</Avatar.Root>
</Item.Media>
<Item.Content>
<Item.Title>Clerk</Item.Title>
<Item.Label>Clerk</Item.Label>
</Item.Content>
<Icon
name='check'
Expand DownExpand Up@@ -189,7 +189,7 @@ export function Group() {
</Avatar.Root>
</Item.Media>
<Item.Content>
<Item.Title>Clerk</Item.Title>
<Item.Label>Clerk</Item.Label>
</Item.Content>
</Item.Root>
</Item.Group>
Expand All@@ -215,7 +215,7 @@ export function Group() {
</Avatar.Root>
</Item.Media>
<Item.Content>
<Item.Title>DesignCloud</Item.Title>
<Item.Label>DesignCloud</Item.Label>
</Item.Content>
</Item.Root>
</Item.Group>
Expand All@@ -239,7 +239,7 @@ export function Group() {
/>
</Item.Media>
<Item.Content>
<Item.Label>Add account</Item.Label>
<Item.Label variant='secondary'>Add account</Item.Label>
</Item.Content>
</Item.Root>
<Item.Root
Expand All@@ -260,7 +260,7 @@ export function Group() {
/>
</Item.Media>
<Item.Content>
<Item.Label>Sign out of all accounts</Item.Label>
<Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
</Item.Content>
</Item.Root>
</Item.Group>
Expand DownExpand Up@@ -324,7 +324,7 @@ export function Scrolling() {
</Avatar.Root>
</Item.Media>
<Item.Content>
<Item.Title>{name}</Item.Title>
<Item.Label>{name}</Item.Label>
</Item.Content>
</Item.Root>
))}
Expand Down
4 changes: 2 additions & 2 deletions packages/swingset/src/stories/scroll-area.stories.tsx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -51,7 +51,7 @@ function OrganizationRow({ name }: { name: string }) {
</Avatar.Root>
</Item.Media>
<Item.Content>
<Item.Title>{name}</Item.Title>
<Item.Label>{name}</Item.Label>
</Item.Content>
</Item.Root>
);
Expand DownExpand Up@@ -166,7 +166,7 @@ export function Gutter() {
</Avatar.Root>
</Item.Media>
<Item.Content>
<Item.Title>{name}</Item.Title>
<Item.Label>{name}</Item.Label>
</Item.Content>
{/* The shift is only legible against something reaching the content's right edge. */}
<div className='bg-border h-4 w-8 rounded-full' />
Expand Down
23 changes: 13 additions & 10 deletions packages/ui/src/mosaic/components/item/item.styles.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -95,28 +95,31 @@ export const content = stylex.create({
},
});

export const title = stylex.create({
export const label = stylex.create({
base: {
fontWeight: fontWeightVars['--cl-font-medium'],
},

primary: {
color: colorVars['--cl-color-neutral'],
fontSize: typeScaleVars['--cl-text-sm-size'],
fontWeight: fontWeightVars['--cl-font-medium'],
lineHeight: typeScaleVars['--cl-text-sm-leading'],
},
});

export const description = stylex.create({
base: {
color: colorVars['--cl-color-neutral-faded'],
// Declares no color, so `reset`'s `inherit` stands and the row's own color reaches it. That is
// what carries it through the hover promotion on an interactive row, which a fixed color would
// freeze. It has to stay undeclared here rather than restated: StyleX resolves a property to the
// last style that declares it, so `base` cannot hold a color either.
secondary: {
fontSize: typeScaleVars['--cl-text-xs-size'],
fontWeight: fontWeightVars['--cl-font-normal'],
lineHeight: typeScaleVars['--cl-text-xs-leading'],
},
});

export const label = stylex.create({
export const description = stylex.create({
base: {
color: colorVars['--cl-color-neutral-faded'],
fontSize: typeScaleVars['--cl-text-xs-size'],
fontWeight: fontWeightVars['--cl-font-medium'],
fontWeight: fontWeightVars['--cl-font-normal'],
lineHeight: typeScaleVars['--cl-text-xs-leading'],
},
});
Expand Down
32 changes: 29 additions & 3 deletions packages/ui/src/mosaic/components/item/item.test.tsx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -44,6 +44,32 @@ describe('Mosaic Item', () => {
expect(screen.getByTestId('media')).toHaveAttribute('data-size', 'md');
});

it('reflects the label variant as a data attribute, defaulting to primary', () => {
const { rerender } = render(<Item.Label>Clerk</Item.Label>);
expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'primary');
rerender(<Item.Label variant='secondary'>Clerk</Item.Label>);
expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'secondary');
});

// StyleX keeps only the last atom that declares a property, so the reset's `color: inherit`
// survives on the variant that declares no color of its own. That is what puts the secondary
// label on the row's color and carries it through the row's hover promotion. `Item.Content`
// declares no color either, so it stands in for the untouched reset.
it('lets the row color the secondary label, and not the primary one', () => {
render(
<Item.Content data-testid='reset-only'>
<Item.Label>Primary</Item.Label>
<Item.Label variant='secondary'>Secondary</Item.Label>
</Item.Content>,
);

const atoms = (element: HTMLElement) => element.className.split(' ');
const resetAtoms = atoms(screen.getByTestId('reset-only'));
const inherited = (text: string) => resetAtoms.filter(atom => atoms(screen.getByText(text)).includes(atom));

expect(inherited('Secondary')).toHaveLength(inherited('Primary').length + 1);
});

it('wires consumer className/style through to the element', () => {
render(
<Item.Root
Expand DownExpand Up@@ -71,7 +97,7 @@ describe('Mosaic Item', () => {
)}
>
<Item.Content>
<Item.Title>Settings</Item.Title>
<Item.Label>Settings</Item.Label>
</Item.Content>
</Item.Root>,
);
Expand All@@ -95,15 +121,15 @@ describe('Mosaic Item', () => {
render(
<Item.Root>
<Item.Content>
<Item.Title>Test Organization</Item.Title>
<Item.Label>Test Organization</Item.Label>
<Item.Description>Member</Item.Description>
</Item.Content>
<Item.Actions>
<button type='button'>Manage</button>
</Item.Actions>
</Item.Root>,
);
expect(screen.getByText('Test Organization')).toHaveClass('cl-item-title');
expect(screen.getByText('Test Organization')).toHaveClass('cl-item-label');
expect(screen.getByText('Member')).toHaveClass('cl-item-description');
expect(screen.getByRole('button', { name: 'Manage' }).parentElement).toHaveClass('cl-item-actions');
});
Expand Down
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
refactor(ui): rename Mosaic Item.Title to Item.Label#9412

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

alexcarpenter
merged 1 commit into

from

Aug 12, 2026
 Merged


refactor(ui): rename Mosaic Item.Title to Item.Label
#9412
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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/mosaic-item-title-to-label.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---

37 changes: 21 additions & 16 deletions
packages/swingset/src/stories/item.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import * as ItemStories from './item.stories';

# Item

Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Title`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.
Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Label`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.

Set `size` once on `Item.Root` and the row scales as a unit: it fixes the row's height and gap, and `Item.Media` picks the matching column width up from context rather than taking a size of its own.

Expand DownExpand Up@@ -76,7 +76,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand All@@ -86,38 +86,43 @@ import { Item } from '@clerk/ui/mosaic/components/item';
</Item.Group>;
```

Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:
Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. A row whose text _is_ the row, rather than naming a subject, uses `Item.Label` with `variant='secondary'`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
 <Item.Media>
 <Icon name='log-out' size='sm' />
 </Item.Media>
 <Item.Content>
 <Item.Label>Sign out of all accounts</Item.Label>
 <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
 </Item.Content>
</Item.Root>;
```

## Parts

| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the title. Truncates to a single line. |
| `Item.Label` | `cl-item-label` | Sole label on an action row, in place of a title. Inherits the row's text color. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |
| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Label` | `cl-item-label` | The row's label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the label. Truncates to a single line. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |

Every part accepts a `render` prop for element polymorphism and forwards a ref.

## Styling

The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon and `Item.Label` hold their resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.
The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon holds its resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.

`Item.Label` chooses whether it joins that promotion. `variant='primary'` sets its own color and holds it, so a subject the row names reads at full strength either way. `variant='secondary'` sets none and inherits the row's, so it fades and brightens with the row:

| Prop | Attribute | Values | Default |
| --------- | -------------- | ------------------------ | --------- |
| `variant` | `data-variant` | `primary` \| `secondary` | `primary` |

The root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

Expand Down

20 changes: 10 additions & 10 deletions
packages/swingset/src/stories/item.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,7 +32,7 @@ export function Default() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand DownExpand Up@@ -68,7 +68,7 @@ export function Interactive() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 </Item.Root>
Expand All@@ -92,7 +92,7 @@ export function Sizes() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 </Item.Content>
 </Item.Root>
 ))}
Expand All@@ -114,7 +114,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Cameron Walker</Item.Title>
 <Item.Label>Cameron Walker</Item.Label>
 <Item.Description>cameron@clerk.com</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand DownExpand Up@@ -158,7 +158,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Label>Clerk</Item.Label>
 </Item.Content>
 <Icon
 name='check'
Expand DownExpand Up@@ -189,7 +189,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Label>Clerk</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand All@@ -215,7 +215,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>DesignCloud</Item.Title>
 <Item.Label>DesignCloud</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand All@@ -239,7 +239,7 @@ export function Group() {
 />
 </Item.Media>
 <Item.Content>
 <Item.Label>Add account</Item.Label>
 <Item.Label variant='secondary'>Add account</Item.Label>
 </Item.Content>
 </Item.Root>
 <Item.Root
Expand All@@ -260,7 +260,7 @@ export function Group() {
 />
 </Item.Media>
 <Item.Content>
 <Item.Label>Sign out of all accounts</Item.Label>
 <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand DownExpand Up@@ -324,7 +324,7 @@ export function Scrolling() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 </Item.Root>
 ))}
Expand Down

4 changes: 2 additions & 2 deletions
packages/swingset/src/stories/scroll-area.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -51,7 +51,7 @@ function OrganizationRow({ name }: { name: string }) {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 </Item.Root>
 );
Expand DownExpand Up@@ -166,7 +166,7 @@ export function Gutter() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 {/* The shift is only legible against something reaching the content's right edge. */}
 <div className='bg-border h-4 w-8 rounded-full' />
Expand Down

23 changes: 13 additions & 10 deletions
packages/ui/src/mosaic/components/item/item.styles.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -95,28 +95,31 @@ export const content = stylex.create({
 },
});

export const title = stylex.create({
export const label = stylex.create({
 base: {
 fontWeight: fontWeightVars['--cl-font-medium'],
 },

 primary: {
 color: colorVars['--cl-color-neutral'],
 fontSize: typeScaleVars['--cl-text-sm-size'],
 fontWeight: fontWeightVars['--cl-font-medium'],
 lineHeight: typeScaleVars['--cl-text-sm-leading'],
 },
});

export const description = stylex.create({
 base: {
 color: colorVars['--cl-color-neutral-faded'],
 // Declares no color, so `reset`'s `inherit` stands and the row's own color reaches it. That is
 // what carries it through the hover promotion on an interactive row, which a fixed color would
 // freeze. It has to stay undeclared here rather than restated: StyleX resolves a property to the
// last style that declares it, so `base` cannot hold a color either.
secondary: {
 fontSize: typeScaleVars['--cl-text-xs-size'],
 fontWeight: fontWeightVars['--cl-font-normal'],
 lineHeight: typeScaleVars['--cl-text-xs-leading'],
 },
});

export const label = stylex.create({
export const description = stylex.create({
 base: {
 color: colorVars['--cl-color-neutral-faded'],
 fontSize: typeScaleVars['--cl-text-xs-size'],
 fontWeight: fontWeightVars['--cl-font-medium'],
 fontWeight: fontWeightVars['--cl-font-normal'],
 lineHeight: typeScaleVars['--cl-text-xs-leading'],
 },
});
Expand Down

32 changes: 29 additions & 3 deletions
packages/ui/src/mosaic/components/item/item.test.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -44,6 +44,32 @@ describe('Mosaic Item', () => {
 expect(screen.getByTestId('media')).toHaveAttribute('data-size', 'md');
 });

 it('reflects the label variant as a data attribute, defaulting to primary', () => {
 const { rerender } = render(<Item.Label>Clerk</Item.Label>);
 expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'primary');
 rerender(<Item.Label variant='secondary'>Clerk</Item.Label>);
 expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'secondary');
 });

 // StyleX keeps only the last atom that declares a property, so the reset's `color: inherit`
 // survives on the variant that declares no color of its own. That is what puts the secondary
 // label on the row's color and carries it through the row's hover promotion. `Item.Content`
 // declares no color either, so it stands in for the untouched reset.
 it('lets the row color the secondary label, and not the primary one', () => {
 render(
 <Item.Content data-testid='reset-only'>
 <Item.Label>Primary</Item.Label>
 <Item.Label variant='secondary'>Secondary</Item.Label>
 </Item.Content>,
 );

 const atoms = (element: HTMLElement) => element.className.split(' ');
 const resetAtoms = atoms(screen.getByTestId('reset-only'));
 const inherited = (text: string) => resetAtoms.filter(atom => atoms(screen.getByText(text)).includes(atom));

 expect(inherited('Secondary')).toHaveLength(inherited('Primary').length + 1);
 });

 it('wires consumer className/style through to the element', () => {
 render(
 <Item.Root
Expand DownExpand Up@@ -71,7 +97,7 @@ describe('Mosaic Item', () => {
 )}
 >
 <Item.Content>
 <Item.Title>Settings</Item.Title>
 <Item.Label>Settings</Item.Label>
 </Item.Content>
 </Item.Root>,
 );
Expand All@@ -95,15 +121,15 @@ describe('Mosaic Item', () => {
 render(
 <Item.Root>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <button type='button'>Manage</button>
 </Item.Actions>
 </Item.Root>,
 );
 expect(screen.getByText('Test Organization')).toHaveClass('cl-item-title');
 expect(screen.getByText('Test Organization')).toHaveClass('cl-item-label');
 expect(screen.getByText('Member')).toHaveClass('cl-item-description');
 expect(screen.getByRole('button', { name: 'Manage' }).parentElement).toHaveClass('cl-item-actions');
 });
Expand Down
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
refactor(ui): rename Mosaic Item.Title to Item.Label#9412

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

alexcarpenter
merged 1 commit into

from

Aug 12, 2026
 Merged


refactor(ui): rename Mosaic Item.Title to Item.Label
#9412
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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/mosaic-item-title-to-label.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---

37 changes: 21 additions & 16 deletions
packages/swingset/src/stories/item.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import * as ItemStories from './item.stories';

# Item

Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Title`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.
Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Label`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.

Set `size` once on `Item.Root` and the row scales as a unit: it fixes the row's height and gap, and `Item.Media` picks the matching column width up from context rather than taking a size of its own.

Expand DownExpand Up@@ -76,7 +76,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand All@@ -86,38 +86,43 @@ import { Item } from '@clerk/ui/mosaic/components/item';
</Item.Group>;
```

Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:
Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. A row whose text _is_ the row, rather than naming a subject, uses `Item.Label` with `variant='secondary'`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
 <Item.Media>
 <Icon name='log-out' size='sm' />
 </Item.Media>
 <Item.Content>
 <Item.Label>Sign out of all accounts</Item.Label>
 <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
 </Item.Content>
</Item.Root>;
```

## Parts

| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the title. Truncates to a single line. |
| `Item.Label` | `cl-item-label` | Sole label on an action row, in place of a title. Inherits the row's text color. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |
| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Label` | `cl-item-label` | The row's label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the label. Truncates to a single line. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |

Every part accepts a `render` prop for element polymorphism and forwards a ref.

## Styling

The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon and `Item.Label` hold their resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.
The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon holds its resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.

`Item.Label` chooses whether it joins that promotion. `variant='primary'` sets its own color and holds it, so a subject the row names reads at full strength either way. `variant='secondary'` sets none and inherits the row's, so it fades and brightens with the row:

| Prop | Attribute | Values | Default |
| --------- | -------------- | ------------------------ | --------- |
| `variant` | `data-variant` | `primary` \| `secondary` | `primary` |

The root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

Expand Down

20 changes: 10 additions & 10 deletions
packages/swingset/src/stories/item.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,7 +32,7 @@ export function Default() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand DownExpand Up@@ -68,7 +68,7 @@ export function Interactive() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 </Item.Root>
Expand All@@ -92,7 +92,7 @@ export function Sizes() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 </Item.Content>
 </Item.Root>
 ))}
Expand All@@ -114,7 +114,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Cameron Walker</Item.Title>
 <Item.Label>Cameron Walker</Item.Label>
 <Item.Description>cameron@clerk.com</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand DownExpand Up@@ -158,7 +158,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Label>Clerk</Item.Label>
 </Item.Content>
 <Icon
 name='check'
Expand DownExpand Up@@ -189,7 +189,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Label>Clerk</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand All@@ -215,7 +215,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>DesignCloud</Item.Title>
 <Item.Label>DesignCloud</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand All@@ -239,7 +239,7 @@ export function Group() {
 />
 </Item.Media>
 <Item.Content>
 <Item.Label>Add account</Item.Label>
 <Item.Label variant='secondary'>Add account</Item.Label>
 </Item.Content>
 </Item.Root>
 <Item.Root
Expand All@@ -260,7 +260,7 @@ export function Group() {
 />
 </Item.Media>
 <Item.Content>
 <Item.Label>Sign out of all accounts</Item.Label>
 <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand DownExpand Up@@ -324,7 +324,7 @@ export function Scrolling() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 </Item.Root>
 ))}
Expand Down

4 changes: 2 additions & 2 deletions
packages/swingset/src/stories/scroll-area.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -51,7 +51,7 @@ function OrganizationRow({ name }: { name: string }) {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 </Item.Root>
 );
Expand DownExpand Up@@ -166,7 +166,7 @@ export function Gutter() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 {/* The shift is only legible against something reaching the content's right edge. */}
 <div className='bg-border h-4 w-8 rounded-full' />
Expand Down

23 changes: 13 additions & 10 deletions
packages/ui/src/mosaic/components/item/item.styles.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -95,28 +95,31 @@ export const content = stylex.create({
 },
});

export const title = stylex.create({
export const label = stylex.create({
 base: {
 fontWeight: fontWeightVars['--cl-font-medium'],
 },

 primary: {
 color: colorVars['--cl-color-neutral'],
 fontSize: typeScaleVars['--cl-text-sm-size'],
 fontWeight: fontWeightVars['--cl-font-medium'],
 lineHeight: typeScaleVars['--cl-text-sm-leading'],
 },
});

export const description = stylex.create({
 base: {
 color: colorVars['--cl-color-neutral-faded'],
 // Declares no color, so `reset`'s `inherit` stands and the row's own color reaches it. That is
 // what carries it through the hover promotion on an interactive row, which a fixed color would
 // freeze. It has to stay undeclared here rather than restated: StyleX resolves a property to the
// last style that declares it, so `base` cannot hold a color either.
secondary: {
 fontSize: typeScaleVars['--cl-text-xs-size'],
 fontWeight: fontWeightVars['--cl-font-normal'],
 lineHeight: typeScaleVars['--cl-text-xs-leading'],
 },
});

export const label = stylex.create({
export const description = stylex.create({
 base: {
 color: colorVars['--cl-color-neutral-faded'],
 fontSize: typeScaleVars['--cl-text-xs-size'],
 fontWeight: fontWeightVars['--cl-font-medium'],
 fontWeight: fontWeightVars['--cl-font-normal'],
 lineHeight: typeScaleVars['--cl-text-xs-leading'],
 },
});
Expand Down

32 changes: 29 additions & 3 deletions
packages/ui/src/mosaic/components/item/item.test.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -44,6 +44,32 @@ describe('Mosaic Item', () => {
 expect(screen.getByTestId('media')).toHaveAttribute('data-size', 'md');
 });

 it('reflects the label variant as a data attribute, defaulting to primary', () => {
 const { rerender } = render(<Item.Label>Clerk</Item.Label>);
 expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'primary');
 rerender(<Item.Label variant='secondary'>Clerk</Item.Label>);
 expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'secondary');
 });

 // StyleX keeps only the last atom that declares a property, so the reset's `color: inherit`
 // survives on the variant that declares no color of its own. That is what puts the secondary
 // label on the row's color and carries it through the row's hover promotion. `Item.Content`
 // declares no color either, so it stands in for the untouched reset.
 it('lets the row color the secondary label, and not the primary one', () => {
 render(
 <Item.Content data-testid='reset-only'>
 <Item.Label>Primary</Item.Label>
 <Item.Label variant='secondary'>Secondary</Item.Label>
 </Item.Content>,
 );

 const atoms = (element: HTMLElement) => element.className.split(' ');
 const resetAtoms = atoms(screen.getByTestId('reset-only'));
 const inherited = (text: string) => resetAtoms.filter(atom => atoms(screen.getByText(text)).includes(atom));

 expect(inherited('Secondary')).toHaveLength(inherited('Primary').length + 1);
 });

 it('wires consumer className/style through to the element', () => {
 render(
 <Item.Root
Expand DownExpand Up@@ -71,7 +97,7 @@ describe('Mosaic Item', () => {
 )}
 >
 <Item.Content>
 <Item.Title>Settings</Item.Title>
 <Item.Label>Settings</Item.Label>
 </Item.Content>
 </Item.Root>,
 );
Expand All@@ -95,15 +121,15 @@ describe('Mosaic Item', () => {
 render(
 <Item.Root>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <button type='button'>Manage</button>
 </Item.Actions>
 </Item.Root>,
 );
 expect(screen.getByText('Test Organization')).toHaveClass('cl-item-title');
 expect(screen.getByText('Test Organization')).toHaveClass('cl-item-label');
 expect(screen.getByText('Member')).toHaveClass('cl-item-description');
 expect(screen.getByRole('button', { name: 'Manage' }).parentElement).toHaveClass('cl-item-actions');
 });
Expand Down
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
refactor(ui): rename Mosaic Item.Title to Item.Label#9412

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

alexcarpenter
merged 1 commit into

from

Aug 12, 2026
 Merged


refactor(ui): rename Mosaic Item.Title to Item.Label
#9412
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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/mosaic-item-title-to-label.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---

37 changes: 21 additions & 16 deletions
packages/swingset/src/stories/item.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import * as ItemStories from './item.stories';

# Item

Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Title`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.
Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Label`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.

Set `size` once on `Item.Root` and the row scales as a unit: it fixes the row's height and gap, and `Item.Media` picks the matching column width up from context rather than taking a size of its own.

Expand DownExpand Up@@ -76,7 +76,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand All@@ -86,38 +86,43 @@ import { Item } from '@clerk/ui/mosaic/components/item';
</Item.Group>;
```

Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:
Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. A row whose text _is_ the row, rather than naming a subject, uses `Item.Label` with `variant='secondary'`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
 <Item.Media>
 <Icon name='log-out' size='sm' />
 </Item.Media>
 <Item.Content>
 <Item.Label>Sign out of all accounts</Item.Label>
 <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
 </Item.Content>
</Item.Root>;
```

## Parts

| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the title. Truncates to a single line. |
| `Item.Label` | `cl-item-label` | Sole label on an action row, in place of a title. Inherits the row's text color. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |
| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Label` | `cl-item-label` | The row's label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the label. Truncates to a single line. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |

Every part accepts a `render` prop for element polymorphism and forwards a ref.

## Styling

The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon and `Item.Label` hold their resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.
The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon holds its resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.

`Item.Label` chooses whether it joins that promotion. `variant='primary'` sets its own color and holds it, so a subject the row names reads at full strength either way. `variant='secondary'` sets none and inherits the row's, so it fades and brightens with the row:

| Prop | Attribute | Values | Default |
| --------- | -------------- | ------------------------ | --------- |
| `variant` | `data-variant` | `primary` \| `secondary` | `primary` |

The root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

Expand Down

20 changes: 10 additions & 10 deletions
packages/swingset/src/stories/item.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,7 +32,7 @@ export function Default() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand DownExpand Up@@ -68,7 +68,7 @@ export function Interactive() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 </Item.Root>
Expand All@@ -92,7 +92,7 @@ export function Sizes() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 </Item.Content>
 </Item.Root>
 ))}
Expand All@@ -114,7 +114,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Cameron Walker</Item.Title>
 <Item.Label>Cameron Walker</Item.Label>
 <Item.Description>cameron@clerk.com</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand DownExpand Up@@ -158,7 +158,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Label>Clerk</Item.Label>
 </Item.Content>
 <Icon
 name='check'
Expand DownExpand Up@@ -189,7 +189,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Label>Clerk</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand All@@ -215,7 +215,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>DesignCloud</Item.Title>
 <Item.Label>DesignCloud</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand All@@ -239,7 +239,7 @@ export function Group() {
 />
 </Item.Media>
 <Item.Content>
 <Item.Label>Add account</Item.Label>
 <Item.Label variant='secondary'>Add account</Item.Label>
 </Item.Content>
 </Item.Root>
 <Item.Root
Expand All@@ -260,7 +260,7 @@ export function Group() {
 />
 </Item.Media>
 <Item.Content>
 <Item.Label>Sign out of all accounts</Item.Label>
 <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand DownExpand Up@@ -324,7 +324,7 @@ export function Scrolling() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 </Item.Root>
 ))}
Expand Down

4 changes: 2 additions & 2 deletions
packages/swingset/src/stories/scroll-area.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -51,7 +51,7 @@ function OrganizationRow({ name }: { name: string }) {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 </Item.Root>
 );
Expand DownExpand Up@@ -166,7 +166,7 @@ export function Gutter() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 {/* The shift is only legible against something reaching the content's right edge. */}
 <div className='bg-border h-4 w-8 rounded-full' />
Expand Down

23 changes: 13 additions & 10 deletions
packages/ui/src/mosaic/components/item/item.styles.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -95,28 +95,31 @@ export const content = stylex.create({
 },
});

export const title = stylex.create({
export const label = stylex.create({
 base: {
 fontWeight: fontWeightVars['--cl-font-medium'],
 },

 primary: {
 color: colorVars['--cl-color-neutral'],
 fontSize: typeScaleVars['--cl-text-sm-size'],
 fontWeight: fontWeightVars['--cl-font-medium'],
 lineHeight: typeScaleVars['--cl-text-sm-leading'],
 },
});

export const description = stylex.create({
 base: {
 color: colorVars['--cl-color-neutral-faded'],
 // Declares no color, so `reset`'s `inherit` stands and the row's own color reaches it. That is
 // what carries it through the hover promotion on an interactive row, which a fixed color would
 // freeze. It has to stay undeclared here rather than restated: StyleX resolves a property to the
// last style that declares it, so `base` cannot hold a color either.
secondary: {
 fontSize: typeScaleVars['--cl-text-xs-size'],
 fontWeight: fontWeightVars['--cl-font-normal'],
 lineHeight: typeScaleVars['--cl-text-xs-leading'],
 },
});

export const label = stylex.create({
export const description = stylex.create({
 base: {
 color: colorVars['--cl-color-neutral-faded'],
 fontSize: typeScaleVars['--cl-text-xs-size'],
 fontWeight: fontWeightVars['--cl-font-medium'],
 fontWeight: fontWeightVars['--cl-font-normal'],
 lineHeight: typeScaleVars['--cl-text-xs-leading'],
 },
});
Expand Down

32 changes: 29 additions & 3 deletions
packages/ui/src/mosaic/components/item/item.test.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -44,6 +44,32 @@ describe('Mosaic Item', () => {
 expect(screen.getByTestId('media')).toHaveAttribute('data-size', 'md');
 });

 it('reflects the label variant as a data attribute, defaulting to primary', () => {
 const { rerender } = render(<Item.Label>Clerk</Item.Label>);
 expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'primary');
 rerender(<Item.Label variant='secondary'>Clerk</Item.Label>);
 expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'secondary');
 });

 // StyleX keeps only the last atom that declares a property, so the reset's `color: inherit`
 // survives on the variant that declares no color of its own. That is what puts the secondary
 // label on the row's color and carries it through the row's hover promotion. `Item.Content`
 // declares no color either, so it stands in for the untouched reset.
 it('lets the row color the secondary label, and not the primary one', () => {
 render(
 <Item.Content data-testid='reset-only'>
 <Item.Label>Primary</Item.Label>
 <Item.Label variant='secondary'>Secondary</Item.Label>
 </Item.Content>,
 );

 const atoms = (element: HTMLElement) => element.className.split(' ');
 const resetAtoms = atoms(screen.getByTestId('reset-only'));
 const inherited = (text: string) => resetAtoms.filter(atom => atoms(screen.getByText(text)).includes(atom));

 expect(inherited('Secondary')).toHaveLength(inherited('Primary').length + 1);
 });

 it('wires consumer className/style through to the element', () => {
 render(
 <Item.Root
Expand DownExpand Up@@ -71,7 +97,7 @@ describe('Mosaic Item', () => {
 )}
 >
 <Item.Content>
 <Item.Title>Settings</Item.Title>
 <Item.Label>Settings</Item.Label>
 </Item.Content>
 </Item.Root>,
 );
Expand All@@ -95,15 +121,15 @@ describe('Mosaic Item', () => {
 render(
 <Item.Root>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <button type='button'>Manage</button>
 </Item.Actions>
 </Item.Root>,
 );
 expect(screen.getByText('Test Organization')).toHaveClass('cl-item-title');
 expect(screen.getByText('Test Organization')).toHaveClass('cl-item-label');
 expect(screen.getByText('Member')).toHaveClass('cl-item-description');
 expect(screen.getByRole('button', { name: 'Manage' }).parentElement).toHaveClass('cl-item-actions');
 });
Expand Down
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
refactor(ui): rename Mosaic Item.Title to Item.Label#9412

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

alexcarpenter
merged 1 commit into

from

Aug 12, 2026
 Merged


refactor(ui): rename Mosaic Item.Title to Item.Label
#9412
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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/mosaic-item-title-to-label.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---

37 changes: 21 additions & 16 deletions
packages/swingset/src/stories/item.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import * as ItemStories from './item.stories';

# Item

Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Title`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.
Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Label`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.

Set `size` once on `Item.Root` and the row scales as a unit: it fixes the row's height and gap, and `Item.Media` picks the matching column width up from context rather than taking a size of its own.

Expand DownExpand Up@@ -76,7 +76,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand All@@ -86,38 +86,43 @@ import { Item } from '@clerk/ui/mosaic/components/item';
</Item.Group>;
```

Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:
Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. A row whose text _is_ the row, rather than naming a subject, uses `Item.Label` with `variant='secondary'`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
 <Item.Media>
 <Icon name='log-out' size='sm' />
 </Item.Media>
 <Item.Content>
 <Item.Label>Sign out of all accounts</Item.Label>
 <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
 </Item.Content>
</Item.Root>;
```

## Parts

| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the title. Truncates to a single line. |
| `Item.Label` | `cl-item-label` | Sole label on an action row, in place of a title. Inherits the row's text color. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |
| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Label` | `cl-item-label` | The row's label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the label. Truncates to a single line. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |

Every part accepts a `render` prop for element polymorphism and forwards a ref.

## Styling

The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon and `Item.Label` hold their resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.
The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon holds its resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.

`Item.Label` chooses whether it joins that promotion. `variant='primary'` sets its own color and holds it, so a subject the row names reads at full strength either way. `variant='secondary'` sets none and inherits the row's, so it fades and brightens with the row:

| Prop | Attribute | Values | Default |
| --------- | -------------- | ------------------------ | --------- |
| `variant` | `data-variant` | `primary` \| `secondary` | `primary` |

The root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

Expand Down

20 changes: 10 additions & 10 deletions
packages/swingset/src/stories/item.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,7 +32,7 @@ export function Default() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand DownExpand Up@@ -68,7 +68,7 @@ export function Interactive() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 </Item.Root>
Expand All@@ -92,7 +92,7 @@ export function Sizes() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 </Item.Content>
 </Item.Root>
 ))}
Expand All@@ -114,7 +114,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Cameron Walker</Item.Title>
 <Item.Label>Cameron Walker</Item.Label>
 <Item.Description>cameron@clerk.com</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand DownExpand Up@@ -158,7 +158,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Label>Clerk</Item.Label>
 </Item.Content>
 <Icon
 name='check'
Expand DownExpand Up@@ -189,7 +189,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Label>Clerk</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand All@@ -215,7 +215,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>DesignCloud</Item.Title>
 <Item.Label>DesignCloud</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand All@@ -239,7 +239,7 @@ export function Group() {
 />
 </Item.Media>
 <Item.Content>
 <Item.Label>Add account</Item.Label>
 <Item.Label variant='secondary'>Add account</Item.Label>
 </Item.Content>
 </Item.Root>
 <Item.Root
Expand All@@ -260,7 +260,7 @@ export function Group() {
 />
 </Item.Media>
 <Item.Content>
 <Item.Label>Sign out of all accounts</Item.Label>
 <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand DownExpand Up@@ -324,7 +324,7 @@ export function Scrolling() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 </Item.Root>
 ))}
Expand Down

4 changes: 2 additions & 2 deletions
packages/swingset/src/stories/scroll-area.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -51,7 +51,7 @@ function OrganizationRow({ name }: { name: string }) {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 </Item.Root>
 );
Expand DownExpand Up@@ -166,7 +166,7 @@ export function Gutter() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 {/* The shift is only legible against something reaching the content's right edge. */}
 <div className='bg-border h-4 w-8 rounded-full' />
Expand Down

23 changes: 13 additions & 10 deletions
packages/ui/src/mosaic/components/item/item.styles.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -95,28 +95,31 @@ export const content = stylex.create({
 },
});

export const title = stylex.create({
export const label = stylex.create({
 base: {
 fontWeight: fontWeightVars['--cl-font-medium'],
 },

 primary: {
 color: colorVars['--cl-color-neutral'],
 fontSize: typeScaleVars['--cl-text-sm-size'],
 fontWeight: fontWeightVars['--cl-font-medium'],
 lineHeight: typeScaleVars['--cl-text-sm-leading'],
 },
});

export const description = stylex.create({
 base: {
 color: colorVars['--cl-color-neutral-faded'],
 // Declares no color, so `reset`'s `inherit` stands and the row's own color reaches it. That is
 // what carries it through the hover promotion on an interactive row, which a fixed color would
 // freeze. It has to stay undeclared here rather than restated: StyleX resolves a property to the
// last style that declares it, so `base` cannot hold a color either.
secondary: {
 fontSize: typeScaleVars['--cl-text-xs-size'],
 fontWeight: fontWeightVars['--cl-font-normal'],
 lineHeight: typeScaleVars['--cl-text-xs-leading'],
 },
});

export const label = stylex.create({
export const description = stylex.create({
 base: {
 color: colorVars['--cl-color-neutral-faded'],
 fontSize: typeScaleVars['--cl-text-xs-size'],
 fontWeight: fontWeightVars['--cl-font-medium'],
 fontWeight: fontWeightVars['--cl-font-normal'],
 lineHeight: typeScaleVars['--cl-text-xs-leading'],
 },
});
Expand Down

32 changes: 29 additions & 3 deletions
packages/ui/src/mosaic/components/item/item.test.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -44,6 +44,32 @@ describe('Mosaic Item', () => {
 expect(screen.getByTestId('media')).toHaveAttribute('data-size', 'md');
 });

 it('reflects the label variant as a data attribute, defaulting to primary', () => {
 const { rerender } = render(<Item.Label>Clerk</Item.Label>);
 expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'primary');
 rerender(<Item.Label variant='secondary'>Clerk</Item.Label>);
 expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'secondary');
 });

 // StyleX keeps only the last atom that declares a property, so the reset's `color: inherit`
 // survives on the variant that declares no color of its own. That is what puts the secondary
 // label on the row's color and carries it through the row's hover promotion. `Item.Content`
 // declares no color either, so it stands in for the untouched reset.
 it('lets the row color the secondary label, and not the primary one', () => {
 render(
 <Item.Content data-testid='reset-only'>
 <Item.Label>Primary</Item.Label>
 <Item.Label variant='secondary'>Secondary</Item.Label>
 </Item.Content>,
 );

 const atoms = (element: HTMLElement) => element.className.split(' ');
 const resetAtoms = atoms(screen.getByTestId('reset-only'));
 const inherited = (text: string) => resetAtoms.filter(atom => atoms(screen.getByText(text)).includes(atom));

 expect(inherited('Secondary')).toHaveLength(inherited('Primary').length + 1);
 });

 it('wires consumer className/style through to the element', () => {
 render(
 <Item.Root
Expand DownExpand Up@@ -71,7 +97,7 @@ describe('Mosaic Item', () => {
 )}
 >
 <Item.Content>
 <Item.Title>Settings</Item.Title>
 <Item.Label>Settings</Item.Label>
 </Item.Content>
 </Item.Root>,
 );
Expand All@@ -95,15 +121,15 @@ describe('Mosaic Item', () => {
 render(
 <Item.Root>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <button type='button'>Manage</button>
 </Item.Actions>
 </Item.Root>,
 );
 expect(screen.getByText('Test Organization')).toHaveClass('cl-item-title');
 expect(screen.getByText('Test Organization')).toHaveClass('cl-item-label');
 expect(screen.getByText('Member')).toHaveClass('cl-item-description');
 expect(screen.getByRole('button', { name: 'Manage' }).parentElement).toHaveClass('cl-item-actions');
 });
Expand Down
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
refactor(ui): rename Mosaic Item.Title to Item.Label#9412

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

alexcarpenter
merged 1 commit into

from

Aug 12, 2026
 Merged


refactor(ui): rename Mosaic Item.Title to Item.Label
#9412
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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/mosaic-item-title-to-label.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---

37 changes: 21 additions & 16 deletions
packages/swingset/src/stories/item.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import * as ItemStories from './item.stories';

# Item

Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Title`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.
Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Label`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.

Set `size` once on `Item.Root` and the row scales as a unit: it fixes the row's height and gap, and `Item.Media` picks the matching column width up from context rather than taking a size of its own.

Expand DownExpand Up@@ -76,7 +76,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand All@@ -86,38 +86,43 @@ import { Item } from '@clerk/ui/mosaic/components/item';
</Item.Group>;
```

Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:
Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. A row whose text _is_ the row, rather than naming a subject, uses `Item.Label` with `variant='secondary'`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
 <Item.Media>
 <Icon name='log-out' size='sm' />
 </Item.Media>
 <Item.Content>
 <Item.Label>Sign out of all accounts</Item.Label>
 <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
 </Item.Content>
</Item.Root>;
```

## Parts

| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the title. Truncates to a single line. |
| `Item.Label` | `cl-item-label` | Sole label on an action row, in place of a title. Inherits the row's text color. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |
| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Label` | `cl-item-label` | The row's label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the label. Truncates to a single line. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |

Every part accepts a `render` prop for element polymorphism and forwards a ref.

## Styling

The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon and `Item.Label` hold their resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.
The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon holds its resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.

`Item.Label` chooses whether it joins that promotion. `variant='primary'` sets its own color and holds it, so a subject the row names reads at full strength either way. `variant='secondary'` sets none and inherits the row's, so it fades and brightens with the row:

| Prop | Attribute | Values | Default |
| --------- | -------------- | ------------------------ | --------- |
| `variant` | `data-variant` | `primary` \| `secondary` | `primary` |

The root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

Expand Down

20 changes: 10 additions & 10 deletions
packages/swingset/src/stories/item.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,7 +32,7 @@ export function Default() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand DownExpand Up@@ -68,7 +68,7 @@ export function Interactive() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 </Item.Root>
Expand All@@ -92,7 +92,7 @@ export function Sizes() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 </Item.Content>
 </Item.Root>
 ))}
Expand All@@ -114,7 +114,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Cameron Walker</Item.Title>
 <Item.Label>Cameron Walker</Item.Label>
 <Item.Description>cameron@clerk.com</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand DownExpand Up@@ -158,7 +158,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Label>Clerk</Item.Label>
 </Item.Content>
 <Icon
 name='check'
Expand DownExpand Up@@ -189,7 +189,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Label>Clerk</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand All@@ -215,7 +215,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>DesignCloud</Item.Title>
 <Item.Label>DesignCloud</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand All@@ -239,7 +239,7 @@ export function Group() {
 />
 </Item.Media>
 <Item.Content>
 <Item.Label>Add account</Item.Label>
 <Item.Label variant='secondary'>Add account</Item.Label>
 </Item.Content>
 </Item.Root>
 <Item.Root
Expand All@@ -260,7 +260,7 @@ export function Group() {
 />
 </Item.Media>
 <Item.Content>
 <Item.Label>Sign out of all accounts</Item.Label>
 <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand DownExpand Up@@ -324,7 +324,7 @@ export function Scrolling() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 </Item.Root>
 ))}
Expand Down

4 changes: 2 additions & 2 deletions
packages/swingset/src/stories/scroll-area.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -51,7 +51,7 @@ function OrganizationRow({ name }: { name: string }) {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 </Item.Root>
 );
Expand DownExpand Up@@ -166,7 +166,7 @@ export function Gutter() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 {/* The shift is only legible against something reaching the content's right edge. */}
 <div className='bg-border h-4 w-8 rounded-full' />
Expand Down

23 changes: 13 additions & 10 deletions
packages/ui/src/mosaic/components/item/item.styles.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -95,28 +95,31 @@ export const content = stylex.create({
 },
});

export const title = stylex.create({
export const label = stylex.create({
 base: {
 fontWeight: fontWeightVars['--cl-font-medium'],
 },

 primary: {
 color: colorVars['--cl-color-neutral'],
 fontSize: typeScaleVars['--cl-text-sm-size'],
 fontWeight: fontWeightVars['--cl-font-medium'],
 lineHeight: typeScaleVars['--cl-text-sm-leading'],
 },
});

export const description = stylex.create({
 base: {
 color: colorVars['--cl-color-neutral-faded'],
 // Declares no color, so `reset`'s `inherit` stands and the row's own color reaches it. That is
 // what carries it through the hover promotion on an interactive row, which a fixed color would
 // freeze. It has to stay undeclared here rather than restated: StyleX resolves a property to the
// last style that declares it, so `base` cannot hold a color either.
secondary: {
 fontSize: typeScaleVars['--cl-text-xs-size'],
 fontWeight: fontWeightVars['--cl-font-normal'],
 lineHeight: typeScaleVars['--cl-text-xs-leading'],
 },
});

export const label = stylex.create({
export const description = stylex.create({
 base: {
 color: colorVars['--cl-color-neutral-faded'],
 fontSize: typeScaleVars['--cl-text-xs-size'],
 fontWeight: fontWeightVars['--cl-font-medium'],
 fontWeight: fontWeightVars['--cl-font-normal'],
 lineHeight: typeScaleVars['--cl-text-xs-leading'],
 },
});
Expand Down

32 changes: 29 additions & 3 deletions
packages/ui/src/mosaic/components/item/item.test.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -44,6 +44,32 @@ describe('Mosaic Item', () => {
 expect(screen.getByTestId('media')).toHaveAttribute('data-size', 'md');
 });

 it('reflects the label variant as a data attribute, defaulting to primary', () => {
 const { rerender } = render(<Item.Label>Clerk</Item.Label>);
 expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'primary');
 rerender(<Item.Label variant='secondary'>Clerk</Item.Label>);
 expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'secondary');
 });

 // StyleX keeps only the last atom that declares a property, so the reset's `color: inherit`
 // survives on the variant that declares no color of its own. That is what puts the secondary
 // label on the row's color and carries it through the row's hover promotion. `Item.Content`
 // declares no color either, so it stands in for the untouched reset.
 it('lets the row color the secondary label, and not the primary one', () => {
 render(
 <Item.Content data-testid='reset-only'>
 <Item.Label>Primary</Item.Label>
 <Item.Label variant='secondary'>Secondary</Item.Label>
 </Item.Content>,
 );

 const atoms = (element: HTMLElement) => element.className.split(' ');
 const resetAtoms = atoms(screen.getByTestId('reset-only'));
 const inherited = (text: string) => resetAtoms.filter(atom => atoms(screen.getByText(text)).includes(atom));

 expect(inherited('Secondary')).toHaveLength(inherited('Primary').length + 1);
 });

 it('wires consumer className/style through to the element', () => {
 render(
 <Item.Root
Expand DownExpand Up@@ -71,7 +97,7 @@ describe('Mosaic Item', () => {
 )}
 >
 <Item.Content>
 <Item.Title>Settings</Item.Title>
 <Item.Label>Settings</Item.Label>
 </Item.Content>
 </Item.Root>,
 );
Expand All@@ -95,15 +121,15 @@ describe('Mosaic Item', () => {
 render(
 <Item.Root>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <button type='button'>Manage</button>
 </Item.Actions>
 </Item.Root>,
 );
 expect(screen.getByText('Test Organization')).toHaveClass('cl-item-title');
 expect(screen.getByText('Test Organization')).toHaveClass('cl-item-label');
 expect(screen.getByText('Member')).toHaveClass('cl-item-description');
 expect(screen.getByRole('button', { name: 'Manage' }).parentElement).toHaveClass('cl-item-actions');
 });
Expand Down
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
refactor(ui): rename Mosaic Item.Title to Item.Label#9412

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

alexcarpenter
merged 1 commit into

from

Aug 12, 2026
 Merged


refactor(ui): rename Mosaic Item.Title to Item.Label
#9412
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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/mosaic-item-title-to-label.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---

37 changes: 21 additions & 16 deletions
packages/swingset/src/stories/item.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import * as ItemStories from './item.stories';

# Item

Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Title`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.
Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Label`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.

Set `size` once on `Item.Root` and the row scales as a unit: it fixes the row's height and gap, and `Item.Media` picks the matching column width up from context rather than taking a size of its own.

Expand DownExpand Up@@ -76,7 +76,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand All@@ -86,38 +86,43 @@ import { Item } from '@clerk/ui/mosaic/components/item';
</Item.Group>;
```

Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:
Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. A row whose text _is_ the row, rather than naming a subject, uses `Item.Label` with `variant='secondary'`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
 <Item.Media>
 <Icon name='log-out' size='sm' />
 </Item.Media>
 <Item.Content>
 <Item.Label>Sign out of all accounts</Item.Label>
 <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
 </Item.Content>
</Item.Root>;
```

## Parts

| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the title. Truncates to a single line. |
| `Item.Label` | `cl-item-label` | Sole label on an action row, in place of a title. Inherits the row's text color. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |
| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Label` | `cl-item-label` | The row's label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the label. Truncates to a single line. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |

Every part accepts a `render` prop for element polymorphism and forwards a ref.

## Styling

The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon and `Item.Label` hold their resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.
The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon holds its resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.

`Item.Label` chooses whether it joins that promotion. `variant='primary'` sets its own color and holds it, so a subject the row names reads at full strength either way. `variant='secondary'` sets none and inherits the row's, so it fades and brightens with the row:

| Prop | Attribute | Values | Default |
| --------- | -------------- | ------------------------ | --------- |
| `variant` | `data-variant` | `primary` \| `secondary` | `primary` |

The root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

Expand Down

20 changes: 10 additions & 10 deletions
packages/swingset/src/stories/item.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,7 +32,7 @@ export function Default() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand DownExpand Up@@ -68,7 +68,7 @@ export function Interactive() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 </Item.Root>
Expand All@@ -92,7 +92,7 @@ export function Sizes() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 </Item.Content>
 </Item.Root>
 ))}
Expand All@@ -114,7 +114,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Cameron Walker</Item.Title>
 <Item.Label>Cameron Walker</Item.Label>
 <Item.Description>cameron@clerk.com</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand DownExpand Up@@ -158,7 +158,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Label>Clerk</Item.Label>
 </Item.Content>
 <Icon
 name='check'
Expand DownExpand Up@@ -189,7 +189,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Label>Clerk</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand All@@ -215,7 +215,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>DesignCloud</Item.Title>
 <Item.Label>DesignCloud</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand All@@ -239,7 +239,7 @@ export function Group() {
 />
 </Item.Media>
 <Item.Content>
 <Item.Label>Add account</Item.Label>
 <Item.Label variant='secondary'>Add account</Item.Label>
 </Item.Content>
 </Item.Root>
 <Item.Root
Expand All@@ -260,7 +260,7 @@ export function Group() {
 />
 </Item.Media>
 <Item.Content>
 <Item.Label>Sign out of all accounts</Item.Label>
 <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand DownExpand Up@@ -324,7 +324,7 @@ export function Scrolling() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 </Item.Root>
 ))}
Expand Down

4 changes: 2 additions & 2 deletions
packages/swingset/src/stories/scroll-area.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -51,7 +51,7 @@ function OrganizationRow({ name }: { name: string }) {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 </Item.Root>
 );
Expand DownExpand Up@@ -166,7 +166,7 @@ export function Gutter() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 {/* The shift is only legible against something reaching the content's right edge. */}
 <div className='bg-border h-4 w-8 rounded-full' />
Expand Down

23 changes: 13 additions & 10 deletions
packages/ui/src/mosaic/components/item/item.styles.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -95,28 +95,31 @@ export const content = stylex.create({
 },
});

export const title = stylex.create({
export const label = stylex.create({
 base: {
 fontWeight: fontWeightVars['--cl-font-medium'],
 },

 primary: {
 color: colorVars['--cl-color-neutral'],
 fontSize: typeScaleVars['--cl-text-sm-size'],
 fontWeight: fontWeightVars['--cl-font-medium'],
 lineHeight: typeScaleVars['--cl-text-sm-leading'],
 },
});

export const description = stylex.create({
 base: {
 color: colorVars['--cl-color-neutral-faded'],
 // Declares no color, so `reset`'s `inherit` stands and the row's own color reaches it. That is
 // what carries it through the hover promotion on an interactive row, which a fixed color would
 // freeze. It has to stay undeclared here rather than restated: StyleX resolves a property to the
// last style that declares it, so `base` cannot hold a color either.
secondary: {
 fontSize: typeScaleVars['--cl-text-xs-size'],
 fontWeight: fontWeightVars['--cl-font-normal'],
 lineHeight: typeScaleVars['--cl-text-xs-leading'],
 },
});

export const label = stylex.create({
export const description = stylex.create({
 base: {
 color: colorVars['--cl-color-neutral-faded'],
 fontSize: typeScaleVars['--cl-text-xs-size'],
 fontWeight: fontWeightVars['--cl-font-medium'],
 fontWeight: fontWeightVars['--cl-font-normal'],
 lineHeight: typeScaleVars['--cl-text-xs-leading'],
 },
});
Expand Down

32 changes: 29 additions & 3 deletions
packages/ui/src/mosaic/components/item/item.test.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -44,6 +44,32 @@ describe('Mosaic Item', () => {
 expect(screen.getByTestId('media')).toHaveAttribute('data-size', 'md');
 });

 it('reflects the label variant as a data attribute, defaulting to primary', () => {
 const { rerender } = render(<Item.Label>Clerk</Item.Label>);
 expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'primary');
 rerender(<Item.Label variant='secondary'>Clerk</Item.Label>);
 expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'secondary');
 });

 // StyleX keeps only the last atom that declares a property, so the reset's `color: inherit`
 // survives on the variant that declares no color of its own. That is what puts the secondary
 // label on the row's color and carries it through the row's hover promotion. `Item.Content`
 // declares no color either, so it stands in for the untouched reset.
 it('lets the row color the secondary label, and not the primary one', () => {
 render(
 <Item.Content data-testid='reset-only'>
 <Item.Label>Primary</Item.Label>
 <Item.Label variant='secondary'>Secondary</Item.Label>
 </Item.Content>,
 );

 const atoms = (element: HTMLElement) => element.className.split(' ');
 const resetAtoms = atoms(screen.getByTestId('reset-only'));
 const inherited = (text: string) => resetAtoms.filter(atom => atoms(screen.getByText(text)).includes(atom));

 expect(inherited('Secondary')).toHaveLength(inherited('Primary').length + 1);
 });

 it('wires consumer className/style through to the element', () => {
 render(
 <Item.Root
Expand DownExpand Up@@ -71,7 +97,7 @@ describe('Mosaic Item', () => {
 )}
 >
 <Item.Content>
 <Item.Title>Settings</Item.Title>
 <Item.Label>Settings</Item.Label>
 </Item.Content>
 </Item.Root>,
 );
Expand All@@ -95,15 +121,15 @@ describe('Mosaic Item', () => {
 render(
 <Item.Root>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <button type='button'>Manage</button>
 </Item.Actions>
 </Item.Root>,
 );
 expect(screen.getByText('Test Organization')).toHaveClass('cl-item-title');
 expect(screen.getByText('Test Organization')).toHaveClass('cl-item-label');
 expect(screen.getByText('Member')).toHaveClass('cl-item-description');
 expect(screen.getByRole('button', { name: 'Manage' }).parentElement).toHaveClass('cl-item-actions');
 });
Expand Down
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
refactor(ui): rename Mosaic Item.Title to Item.Label#9412

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

alexcarpenter
merged 1 commit into

from

Aug 12, 2026
 Merged


refactor(ui): rename Mosaic Item.Title to Item.Label
#9412
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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/mosaic-item-title-to-label.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---

37 changes: 21 additions & 16 deletions
packages/swingset/src/stories/item.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import * as ItemStories from './item.stories';

# Item

Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Title`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.
Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Root`, `Item.Media`, `Item.Content`, `Item.Label`, …). `Item.Root` renders as a `<div>` by default; pass it a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.

Set `size` once on `Item.Root` and the row scales as a unit: it fixes the row's height and gap, and `Item.Media` picks the matching column width up from context rather than taking a size of its own.

Expand DownExpand Up@@ -76,7 +76,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand All@@ -86,38 +86,43 @@ import { Item } from '@clerk/ui/mosaic/components/item';
</Item.Group>;
```

Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:
Media sizes itself from the row, so give it a child that fills its column — an `Avatar.Root` with `size='fit'`, or an `Icon`. A row whose text _is_ the row, rather than naming a subject, uses `Item.Label` with `variant='secondary'`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
 <Item.Media>
 <Icon name='log-out' size='sm' />
 </Item.Media>
 <Item.Content>
 <Item.Label>Sign out of all accounts</Item.Label>
 <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
 </Item.Content>
</Item.Root>;
```

## Parts

| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the title. Truncates to a single line. |
| `Item.Label` | `cl-item-label` | Sole label on an action row, in place of a title. Inherits the row's text color. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |
| Part | Class | Description |
| ------------------ | --------------------- | -------------------------------------------------------------------------- |
| `Item.Root` | `cl-item` | Root row. Renders a `<div>`, or a custom element via `render`. |
| `Item.Media` | `cl-item-media` | Square leading column: icon, image, or avatar. Sized by the root's `size`. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Label` | `cl-item-label` | The row's label. Truncates to a single line. |
| `Item.Description` | `cl-item-description` | Secondary text beneath the label. Truncates to a single line. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Group` | `cl-item-group` | Vertical wrapper around a set of rows (layout only, no role). |
| `Item.Separator` | `cl-item-separator` | Thin divider (`<hr>`) between rows. |

Every part accepts a `render` prop for element polymorphism and forwards a ref.

## Styling

The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon and `Item.Label` hold their resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.
The row carries the text color and, through `--_cl-icon-color`, the strength of any `Icon` inside it: faded at rest, full-strength while hovered. Only interactive rows promote — a static row isn't pointing at anything, so its icon holds its resting color. A `Button` in `Item.Actions` sets its own icon color and is unaffected.

`Item.Label` chooses whether it joins that promotion. `variant='primary'` sets its own color and holds it, so a subject the row names reads at full strength either way. `variant='secondary'` sets none and inherits the row's, so it fades and brightens with the row:

| Prop | Attribute | Values | Default |
| --------- | -------------- | ------------------------ | --------- |
| `variant` | `data-variant` | `primary` \| `secondary` | `primary` |

The root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

Expand Down

20 changes: 10 additions & 10 deletions
packages/swingset/src/stories/item.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,7 +32,7 @@ export function Default() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand DownExpand Up@@ -68,7 +68,7 @@ export function Interactive() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 </Item.Root>
Expand All@@ -92,7 +92,7 @@ export function Sizes() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 </Item.Content>
 </Item.Root>
 ))}
Expand All@@ -114,7 +114,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Cameron Walker</Item.Title>
 <Item.Label>Cameron Walker</Item.Label>
 <Item.Description>cameron@clerk.com</Item.Description>
 </Item.Content>
 <Item.Actions>
Expand DownExpand Up@@ -158,7 +158,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Label>Clerk</Item.Label>
 </Item.Content>
 <Icon
 name='check'
Expand DownExpand Up@@ -189,7 +189,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Label>Clerk</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand All@@ -215,7 +215,7 @@ export function Group() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>DesignCloud</Item.Title>
 <Item.Label>DesignCloud</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand All@@ -239,7 +239,7 @@ export function Group() {
 />
 </Item.Media>
 <Item.Content>
 <Item.Label>Add account</Item.Label>
 <Item.Label variant='secondary'>Add account</Item.Label>
 </Item.Content>
 </Item.Root>
 <Item.Root
Expand All@@ -260,7 +260,7 @@ export function Group() {
 />
 </Item.Media>
 <Item.Content>
 <Item.Label>Sign out of all accounts</Item.Label>
 <Item.Label variant='secondary'>Sign out of all accounts</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand DownExpand Up@@ -324,7 +324,7 @@ export function Scrolling() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 </Item.Root>
 ))}
Expand Down

4 changes: 2 additions & 2 deletions
packages/swingset/src/stories/scroll-area.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -51,7 +51,7 @@ function OrganizationRow({ name }: { name: string }) {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 </Item.Root>
 );
Expand DownExpand Up@@ -166,7 +166,7 @@ export function Gutter() {
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>{name}</Item.Title>
 <Item.Label>{name}</Item.Label>
 </Item.Content>
 {/* The shift is only legible against something reaching the content's right edge. */}
 <div className='bg-border h-4 w-8 rounded-full' />
Expand Down

23 changes: 13 additions & 10 deletions
packages/ui/src/mosaic/components/item/item.styles.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -95,28 +95,31 @@ export const content = stylex.create({
 },
});

export const title = stylex.create({
export const label = stylex.create({
 base: {
 fontWeight: fontWeightVars['--cl-font-medium'],
 },

 primary: {
 color: colorVars['--cl-color-neutral'],
 fontSize: typeScaleVars['--cl-text-sm-size'],
 fontWeight: fontWeightVars['--cl-font-medium'],
 lineHeight: typeScaleVars['--cl-text-sm-leading'],
 },
});

export const description = stylex.create({
 base: {
 color: colorVars['--cl-color-neutral-faded'],
 // Declares no color, so `reset`'s `inherit` stands and the row's own color reaches it. That is
 // what carries it through the hover promotion on an interactive row, which a fixed color would
 // freeze. It has to stay undeclared here rather than restated: StyleX resolves a property to the
// last style that declares it, so `base` cannot hold a color either.
secondary: {
 fontSize: typeScaleVars['--cl-text-xs-size'],
 fontWeight: fontWeightVars['--cl-font-normal'],
 lineHeight: typeScaleVars['--cl-text-xs-leading'],
 },
});

export const label = stylex.create({
export const description = stylex.create({
 base: {
 color: colorVars['--cl-color-neutral-faded'],
 fontSize: typeScaleVars['--cl-text-xs-size'],
 fontWeight: fontWeightVars['--cl-font-medium'],
 fontWeight: fontWeightVars['--cl-font-normal'],
 lineHeight: typeScaleVars['--cl-text-xs-leading'],
 },
});
Expand Down

32 changes: 29 additions & 3 deletions
packages/ui/src/mosaic/components/item/item.test.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -44,6 +44,32 @@ describe('Mosaic Item', () => {
 expect(screen.getByTestId('media')).toHaveAttribute('data-size', 'md');
 });

 it('reflects the label variant as a data attribute, defaulting to primary', () => {
 const { rerender } = render(<Item.Label>Clerk</Item.Label>);
 expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'primary');
 rerender(<Item.Label variant='secondary'>Clerk</Item.Label>);
 expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'secondary');
 });

 // StyleX keeps only the last atom that declares a property, so the reset's `color: inherit`
 // survives on the variant that declares no color of its own. That is what puts the secondary
 // label on the row's color and carries it through the row's hover promotion. `Item.Content`
 // declares no color either, so it stands in for the untouched reset.
 it('lets the row color the secondary label, and not the primary one', () => {
 render(
 <Item.Content data-testid='reset-only'>
 <Item.Label>Primary</Item.Label>
 <Item.Label variant='secondary'>Secondary</Item.Label>
 </Item.Content>,
 );

 const atoms = (element: HTMLElement) => element.className.split(' ');
 const resetAtoms = atoms(screen.getByTestId('reset-only'));
 const inherited = (text: string) => resetAtoms.filter(atom => atoms(screen.getByText(text)).includes(atom));

 expect(inherited('Secondary')).toHaveLength(inherited('Primary').length + 1);
 });

 it('wires consumer className/style through to the element', () => {
 render(
 <Item.Root
Expand DownExpand Up@@ -71,7 +97,7 @@ describe('Mosaic Item', () => {
 )}
 >
 <Item.Content>
 <Item.Title>Settings</Item.Title>
 <Item.Label>Settings</Item.Label>
 </Item.Content>
 </Item.Root>,
 );
Expand All@@ -95,15 +121,15 @@ describe('Mosaic Item', () => {
 render(
 <Item.Root>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 <Item.Label>Test Organization</Item.Label>
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <button type='button'>Manage</button>
 </Item.Actions>
 </Item.Root>,
 );
 expect(screen.getByText('Test Organization')).toHaveClass('cl-item-title');
 expect(screen.getByText('Test Organization')).toHaveClass('cl-item-label');
 expect(screen.getByText('Member')).toHaveClass('cl-item-description');
 expect(screen.getByRole('button', { name: 'Manage' }).parentElement).toHaveClass('cl-item-actions');
 });
Expand Down
Loading
Loading