feat(ui): scale Mosaic Item rows from a single size prop#9297

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 3 commits into from
Jul 31, 2026
Merged

feat(ui): scale Mosaic Item rows from a single size prop #9297

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dbe0001
feat(ui): scale Mosaic Item rows from a single size prop
alexcarpenter Jul 30, 2026
fa09923
update story
alexcarpenter Jul 30, 2026
d47e2da
fix(ui): key Mosaic Item label hover to the row
alexcarpenter Jul 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .changeset/mosaic-item-size.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
---
---
67 changes: 46 additions & 21 deletions packages/swingset/src/stories/item.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -4,6 +4,8 @@ import * as ItemStories from './item.stories';

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.

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.

## Example

<Story
Expand All@@ -18,6 +20,13 @@ Item is a flexible row for lists of accounts, organizations, and settings in Mos
storyModule={ItemStories}
/>

### Sizes

<Story
name='Sizes'
storyModule={ItemStories}
/>

### Group

<Story
Expand All@@ -34,7 +43,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
<Item.Group>
<Item.Root render={({ children, ...props }) => <a {...props} href='/org'>{children}</a>}>
<Item.Media>
<Avatar.Root shape='square' size='md'>
<Avatar.Root shape='square' size='fit'>
<Avatar.Image src={org.imageUrl} alt='' />
<Avatar.Fallback>{org.name[0]}</Avatar.Fallback>
</Avatar.Root>
Expand All@@ -44,46 +53,62 @@ import { Item } from '@clerk/ui/mosaic/components/item';
<Item.Description>Member</Item.Description>
</Item.Content>
<Item.Actions>
<Button variant='outline'>Manage</Button>
<Button variant='outline' size='sm'>Manage</Button>
</Item.Actions>
</Item.Root>
</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 at `width='100%'`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
<Item.Media>
<SignOutIcon width='100%' />
</Item.Media>
<Item.Content>
<Item.Label>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` | Leading (or trailing) media: icon, image, or avatar. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. |
| `Item.Description` | `cl-item-description` | Secondary text. Renders a `<p>`. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Header` | `cl-item-header` | Header row above a group: a label with optional actions. |
| `Item.HeaderTitle` | `cl-item-header-title` | Label text within an `Item.Header`. |
| `Item.HeaderActions` | `cl-item-header-actions` | Trailing controls within an `Item.Header`. |
| `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.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. Dimmed until hovered. |
| `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 root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

| Prop | Attribute | Values | Default |
| --------- | ------------------ | ----------------------------------- | -------- |
| `variant` | `data-variant` | `entity` \| `action` | `entity` |
| `render` | `data-interactive` | present when a `render` is provided | — |
| Prop | Attribute | Values | Default |
| -------- | ------------------ | ----------------------------------- | ------- |
| `size` | `data-size` | `xs` \| `md` | `md` |
| `render` | `data-interactive` | present when a `render` is provided | — |

`variant` sets the row's vertical density (`entity` is standard, `action` is denser) and, on interactive rows, promotes the title color.
`size` fixes the row's height and gap. `Item.Media` reflects the same value as `data-size` and takes its width from it, so the two stay in step without being set twice:

```css
/* Re-theme interactive rows */
.cl-item[data-interactive] {
background-color: var(--cl-color-card);
}

/* Widen the media column on compact rows */
.cl-item-media[data-size='xs'] {
width: 1.5rem;
}
```

`Item.Media` sizes to its child and centers it; its height follows the row. Bring your own icon, avatar, or image at whatever dimensions you need, then size the slot by sizing that child. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).
`Item.Media` is a square that centers its child. Because the column is sized by the row, give it a child that fills it — an `Avatar.Root` with `size='fit'`, or an icon at `width='100%'` — rather than a fixed pixel size that won't track `size`. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).
133 changes: 78 additions & 55 deletions packages/swingset/src/stories/item.stories.tsx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -35,36 +35,6 @@ function CheckMarkIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
);
}

function EllipsisIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
return (
<svg
viewBox='0 0 16 16'
width='1em'
height='1em'
fill='none'
{...props}
>
<path
d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
fill='#747686'
/>
<path
d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
fill='#747686'
/>
<path
d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
fill='#747686'
/>
<rect
width='0.0001'
height='0.0001'
fill='#747686'
/>
</svg>
);
}

function PlusIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
return (
<svg
Expand DownExpand Up@@ -124,7 +94,12 @@ export function Default() {
<Item.Description>Member</Item.Description>
</Item.Content>
<Item.Actions>
<Button variant='outline'>Manage</Button>
<Button
variant='outline'
size='sm'
>
Manage
</Button>
</Item.Actions>
</Item.Root>
);
Expand DownExpand Up@@ -158,6 +133,31 @@ export function Interactive() {
);
}

export function Sizes() {
return (
<div className='w-full'>
{(['md', 'xs'] as const).map(size => (
<Item.Root
key={size}
size={size}
>
<Item.Media>
<Avatar.Root
shape='square'
size='fit'
>
<Avatar.Fallback>T</Avatar.Fallback>
</Avatar.Root>
</Item.Media>
<Item.Content>
<Item.Title>Test Organization</Item.Title>
</Item.Content>
</Item.Root>
))}
</div>
);
}

export function Group() {
return (
<div className='w-full'>
Expand All@@ -173,25 +173,52 @@ export function Group() {
</Item.Media>
<Item.Content>
<Item.Title>Cameron Walker</Item.Title>
<Item.Description>cameron@clerk.com</Item.Description>
</Item.Content>
<Item.Actions>
<Button variant='outline'>Invite</Button>
<Button
variant='outline'
size='sm'
>
Invite
</Button>
</Item.Actions>
</Item.Root>
</Item.Group>
<Item.Separator />
<Item.Group>
<Item.Header>
<Item.HeaderTitle>cameron@clerk.com</Item.HeaderTitle>
<Button
size='sm'
shape='square'
variant='ghost'
>
<EllipsisIcon />
</Button>
</Item.Header>
<Item.Root>
<Item.Root size='xs'>
<Item.Content>
<Item.Description>cameron.walker@gmail.com</Item.Description>
</Item.Content>
<Item.Actions>
<Button
variant='ghost'
color='neutral'
size='sm'
shape='square'
>
<svg
width='16'
viewBox='0 0 16 16'
>
<path
d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
fill='currentColor'
/>
<path
d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
fill='currentColor'
/>
<path
d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
fill='currentColor'
/>
</svg>
</Button>
Comment thread
alexcarpenter marked this conversation as resolved.
</Item.Actions>
</Item.Root>
<Item.Root size='xs'>
<Item.Media>
<Avatar.Root
size='fit'
Expand All@@ -206,11 +233,11 @@ export function Group() {
</Item.Media>
<Item.Content>
<Item.Title>Clerk</Item.Title>
<Item.Description>24 members &bull; Basic</Item.Description>
</Item.Content>
<CheckMarkIcon width='28px' />
</Item.Root>
<Item.Root
size='xs'
render={({ children, ...props }) => (
<a
{...props}
Expand All@@ -234,13 +261,13 @@ export function Group() {
</Item.Media>
<Item.Content>
<Item.Title>Clerk</Item.Title>
<Item.Description>24 members &bull; Basic</Item.Description>
</Item.Content>
</Item.Root>
</Item.Group>
<Item.Separator />
<Item.Group>
<Item.Root
size='xs'
render={({ children, ...props }) => (
<a
{...props}
Expand All@@ -260,14 +287,13 @@ export function Group() {
</Item.Media>
<Item.Content>
<Item.Title>DesignCloud</Item.Title>
<Item.Description>12 members &bull; Pro</Item.Description>
</Item.Content>
</Item.Root>
</Item.Group>
<Item.Separator />
<Item.Group>
<Item.Root
variant='action'
size='xs'
render={({ children, ...props }) => (
<a
{...props}
Expand All@@ -278,17 +304,14 @@ export function Group() {
)}
>
<Item.Media>
<PlusIcon width='36px' />
<PlusIcon width='100%' />
</Item.Media>
<Item.Content>
<Item.Title>Add account</Item.Title>
<Item.Label>Add account</Item.Label>
</Item.Content>
</Item.Root>
</Item.Group>
<Item.Separator />
<Item.Group>
<Item.Root
variant='action'
size='xs'
render={({ children, ...props }) => (
<button
type='button'
Expand All@@ -299,10 +322,10 @@ export function Group() {
)}
>
<Item.Media>
<SignOutIcon width='36px' />
<SignOutIcon width='100%' />
</Item.Media>
<Item.Content>
<Item.Title>Sign out of all accounts</Item.Title>
<Item.Label>Sign out of all accounts</Item.Label>
</Item.Content>
</Item.Root>
</Item.Group>
Expand Down
11 changes: 11 additions & 0 deletions packages/ui/src/mosaic/components/item/item.markers.stylex.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
import * as stylex from '@stylexjs/stylex';

/**
* Scopes a part's ancestor-state selectors to a Mosaic `Item.Root`, so an unrelated hovered
* ancestor can't drive them. `Item.Root` applies it; `Item.Label` matches on it to follow the
* row's hover rather than its own.
*
* Its own module because `@stylexjs/enforce-extension` requires the define-primitives to live in
* a `.stylex.ts` file.
*/
export const itemScope = stylex.defineMarker();
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
feat(ui): scale Mosaic Item rows from a single size prop#9297

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 3 commits into

from

Jul 31, 2026
 Merged


feat(ui): scale Mosaic Item rows from a single size prop
#9297
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
dbe0001

feat(ui): scale Mosaic Item rows from a single size prop


alexcarpenter Jul 30, 2026
fa09923

update story


alexcarpenter Jul 30, 2026
d47e2da

fix(ui): key Mosaic Item label hover to the row


alexcarpenter Jul 31, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 2 additions & 0 deletions
.changeset/mosaic-item-size.md

View file


Open in desktop

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

67 changes: 46 additions & 21 deletions
packages/swingset/src/stories/item.mdx

View file


Open in desktop

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

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.

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.

## Example

<Story
Expand All@@ -18,6 +20,13 @@ Item is a flexible row for lists of accounts, organizations, and settings in Mos
 storyModule={ItemStories}
/>

### Sizes

<Story
 name='Sizes'
 storyModule={ItemStories}
/>

### Group

<Story
Expand All@@ -34,7 +43,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
<Item.Group>
 <Item.Root render={({ children, ...props }) => <a {...props} href='/org'>{children}</a>}>
 <Item.Media>
 <Avatar.Root shape='square' size='md'>
 <Avatar.Root shape='square' size='fit'>
 <Avatar.Image src={org.imageUrl} alt='' />
 <Avatar.Fallback>{org.name[0]}</Avatar.Fallback>
 </Avatar.Root>
Expand All@@ -44,46 +53,62 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Manage</Button>
 <Button variant='outline' size='sm'>Manage</Button>
 </Item.Actions>
 </Item.Root>
</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 at `width='100%'`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
 <Item.Media>
 <SignOutIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Label>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` | Leading (or trailing) media: icon, image, or avatar. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. |
| `Item.Description` | `cl-item-description` | Secondary text. Renders a `<p>`. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Header` | `cl-item-header` | Header row above a group: a label with optional actions. |
| `Item.HeaderTitle` | `cl-item-header-title` | Label text within an `Item.Header`. |
| `Item.HeaderActions` | `cl-item-header-actions` | Trailing controls within an `Item.Header`. |
| `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.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. Dimmed until hovered. |
| `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 root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

| Prop | Attribute | Values | Default |
| --------- | ------------------ | ----------------------------------- | -------- |
| `variant` | `data-variant` | `entity` \| `action` | `entity` |
| `render` | `data-interactive` | present when a `render` is provided | — |
| Prop | Attribute | Values | Default |
| -------- | ------------------ | ----------------------------------- | ------- |
| `size` | `data-size` | `xs` \| `md` | `md`  |
| `render` | `data-interactive` | present when a `render` is provided | — |

`variant` sets the row's vertical density (`entity` is standard, `action` is denser) and, on interactive rows, promotes the title color.
`size` fixes the row's height and gap. `Item.Media` reflects the same value as `data-size` and takes its width from it, so the two stay in step without being set twice:

```css
/* Re-theme interactive rows */
.cl-item[data-interactive] {
 background-color: var(--cl-color-card);
}

/* Widen the media column on compact rows */
.cl-item-media[data-size='xs'] {
 width: 1.5rem;
}
```

`Item.Media` sizes to its child and centers it; its height follows the row. Bring your own icon, avatar, or image at whatever dimensions you need, then size the slot by sizing that child. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).
`Item.Media` is a square that centers its child. Because the column is sized by the row, give it a child that fills it — an `Avatar.Root` with `size='fit'`, or an icon at `width='100%'` — rather than a fixed pixel size that won't track `size`. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).

133 changes: 78 additions & 55 deletions
packages/swingset/src/stories/item.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -35,36 +35,6 @@ function CheckMarkIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 );
}

function EllipsisIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 return (
 <svg
 viewBox='0 0 16 16'
 width='1em'
 height='1em'
 fill='none'
 {...props}
 >
 <path
 d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
 fill='#747686'
 />
 <path
 d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
 fill='#747686'
 />
 <path
 d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
 fill='#747686'
 />
 <rect
 width='0.0001'
 height='0.0001'
 fill='#747686'
 />
 </svg>
 );
}

function PlusIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 return (
 <svg
Expand DownExpand Up@@ -124,7 +94,12 @@ export function Default() {
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Manage</Button>
 <Button
 variant='outline'
 size='sm'
 >
 Manage
 </Button>
 </Item.Actions>
 </Item.Root>
 );
Expand DownExpand Up@@ -158,6 +133,31 @@ export function Interactive() {
 );
}

export function Sizes() {
 return (
 <div className='w-full'>
 {(['md', 'xs'] as const).map(size => (
 <Item.Root
 key={size}
 size={size}
 >
 <Item.Media>
 <Avatar.Root
 shape='square'
 size='fit'
 >
 <Avatar.Fallback>T</Avatar.Fallback>
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 </Item.Content>
 </Item.Root>
 ))}
 </div>
 );
}

export function Group() {
 return (
 <div className='w-full'>
Expand All@@ -173,25 +173,52 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Cameron Walker</Item.Title>
 <Item.Description>cameron@clerk.com</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Invite</Button>
 <Button
 variant='outline'
 size='sm'
 >
 Invite
 </Button>
 </Item.Actions>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Header>
 <Item.HeaderTitle>cameron@clerk.com</Item.HeaderTitle>
 <Button
 size='sm'
 shape='square'
 variant='ghost'
 >
 <EllipsisIcon />
 </Button>
 </Item.Header>
 <Item.Root>
 <Item.Root size='xs'>
 <Item.Content>
 <Item.Description>cameron.walker@gmail.com</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button
 variant='ghost'
 color='neutral'
 size='sm'
 shape='square'
 >
 <svg
 width='16'
 viewBox='0 0 16 16'
 >
 <path
 d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
 fill='currentColor'
 />
 <path
 d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
 fill='currentColor'
 />
 <path
 d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
 fill='currentColor'
 />
 </svg>
 </Button>
Comment thread
alexcarpenter marked this conversation as resolved.

 </Item.Actions>
 </Item.Root>
 <Item.Root size='xs'>
 <Item.Media>
 <Avatar.Root
 size='fit'
Expand All@@ -206,11 +233,11 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Description>24 members &bull; Basic</Item.Description>
 </Item.Content>
 <CheckMarkIcon width='28px' />
 </Item.Root>
 <Item.Root
 size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -234,13 +261,13 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Description>24 members &bull; Basic</Item.Description>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
 size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -260,14 +287,13 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>DesignCloud</Item.Title>
 <Item.Description>12 members &bull; Pro</Item.Description>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
variant='action'
size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -278,17 +304,14 @@ export function Group() {
 )}
 >
 <Item.Media>
 <PlusIcon width='36px' />
 <PlusIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Title>Add account</Item.Title>
 <Item.Label>Add account</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
variant='action'
size='xs'
 render={({ children, ...props }) => (
 <button
 type='button'
Expand All@@ -299,10 +322,10 @@ export function Group() {
 )}
 >
 <Item.Media>
 <SignOutIcon width='36px' />
 <SignOutIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Title>Sign out of all accounts</Item.Title>
 <Item.Label>Sign out of all accounts</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand Down

11 changes: 11 additions & 0 deletions
packages/ui/src/mosaic/components/item/item.markers.stylex.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
import * as stylex from '@stylexjs/stylex';

/**
 * Scopes a part's ancestor-state selectors to a Mosaic `Item.Root`, so an unrelated hovered
 * ancestor can't drive them. `Item.Root` applies it; `Item.Label` matches on it to follow the
 * row's hover rather than its own.
 *
 * Its own module because `@stylexjs/enforce-extension` requires the define-primitives to live in
 * a `.stylex.ts` file.
 */
export const itemScope = stylex.defineMarker();
Loading
Loading

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

Skip to content
feat(ui): scale Mosaic Item rows from a single size prop#9297

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 3 commits into

from

Jul 31, 2026
 Merged


feat(ui): scale Mosaic Item rows from a single size prop
#9297
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
dbe0001

feat(ui): scale Mosaic Item rows from a single size prop


alexcarpenter Jul 30, 2026
fa09923

update story


alexcarpenter Jul 30, 2026
d47e2da

fix(ui): key Mosaic Item label hover to the row


alexcarpenter Jul 31, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 2 additions & 0 deletions
.changeset/mosaic-item-size.md

View file


Open in desktop

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

67 changes: 46 additions & 21 deletions
packages/swingset/src/stories/item.mdx

View file


Open in desktop

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

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.

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.

## Example

<Story
Expand All@@ -18,6 +20,13 @@ Item is a flexible row for lists of accounts, organizations, and settings in Mos
 storyModule={ItemStories}
/>

### Sizes

<Story
 name='Sizes'
 storyModule={ItemStories}
/>

### Group

<Story
Expand All@@ -34,7 +43,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
<Item.Group>
 <Item.Root render={({ children, ...props }) => <a {...props} href='/org'>{children}</a>}>
 <Item.Media>
 <Avatar.Root shape='square' size='md'>
 <Avatar.Root shape='square' size='fit'>
 <Avatar.Image src={org.imageUrl} alt='' />
 <Avatar.Fallback>{org.name[0]}</Avatar.Fallback>
 </Avatar.Root>
Expand All@@ -44,46 +53,62 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Manage</Button>
 <Button variant='outline' size='sm'>Manage</Button>
 </Item.Actions>
 </Item.Root>
</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 at `width='100%'`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
 <Item.Media>
 <SignOutIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Label>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` | Leading (or trailing) media: icon, image, or avatar. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. |
| `Item.Description` | `cl-item-description` | Secondary text. Renders a `<p>`. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Header` | `cl-item-header` | Header row above a group: a label with optional actions. |
| `Item.HeaderTitle` | `cl-item-header-title` | Label text within an `Item.Header`. |
| `Item.HeaderActions` | `cl-item-header-actions` | Trailing controls within an `Item.Header`. |
| `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.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. Dimmed until hovered. |
| `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 root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

| Prop | Attribute | Values | Default |
| --------- | ------------------ | ----------------------------------- | -------- |
| `variant` | `data-variant` | `entity` \| `action` | `entity` |
| `render` | `data-interactive` | present when a `render` is provided | — |
| Prop | Attribute | Values | Default |
| -------- | ------------------ | ----------------------------------- | ------- |
| `size` | `data-size` | `xs` \| `md` | `md`  |
| `render` | `data-interactive` | present when a `render` is provided | — |

`variant` sets the row's vertical density (`entity` is standard, `action` is denser) and, on interactive rows, promotes the title color.
`size` fixes the row's height and gap. `Item.Media` reflects the same value as `data-size` and takes its width from it, so the two stay in step without being set twice:

```css
/* Re-theme interactive rows */
.cl-item[data-interactive] {
 background-color: var(--cl-color-card);
}

/* Widen the media column on compact rows */
.cl-item-media[data-size='xs'] {
 width: 1.5rem;
}
```

`Item.Media` sizes to its child and centers it; its height follows the row. Bring your own icon, avatar, or image at whatever dimensions you need, then size the slot by sizing that child. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).
`Item.Media` is a square that centers its child. Because the column is sized by the row, give it a child that fills it — an `Avatar.Root` with `size='fit'`, or an icon at `width='100%'` — rather than a fixed pixel size that won't track `size`. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).

133 changes: 78 additions & 55 deletions
packages/swingset/src/stories/item.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -35,36 +35,6 @@ function CheckMarkIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 );
}

function EllipsisIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 return (
 <svg
 viewBox='0 0 16 16'
 width='1em'
 height='1em'
 fill='none'
 {...props}
 >
 <path
 d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
 fill='#747686'
 />
 <path
 d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
 fill='#747686'
 />
 <path
 d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
 fill='#747686'
 />
 <rect
 width='0.0001'
 height='0.0001'
 fill='#747686'
 />
 </svg>
 );
}

function PlusIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 return (
 <svg
Expand DownExpand Up@@ -124,7 +94,12 @@ export function Default() {
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Manage</Button>
 <Button
 variant='outline'
 size='sm'
 >
 Manage
 </Button>
 </Item.Actions>
 </Item.Root>
 );
Expand DownExpand Up@@ -158,6 +133,31 @@ export function Interactive() {
 );
}

export function Sizes() {
 return (
 <div className='w-full'>
 {(['md', 'xs'] as const).map(size => (
 <Item.Root
 key={size}
 size={size}
 >
 <Item.Media>
 <Avatar.Root
 shape='square'
 size='fit'
 >
 <Avatar.Fallback>T</Avatar.Fallback>
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 </Item.Content>
 </Item.Root>
 ))}
 </div>
 );
}

export function Group() {
 return (
 <div className='w-full'>
Expand All@@ -173,25 +173,52 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Cameron Walker</Item.Title>
 <Item.Description>cameron@clerk.com</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Invite</Button>
 <Button
 variant='outline'
 size='sm'
 >
 Invite
 </Button>
 </Item.Actions>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Header>
 <Item.HeaderTitle>cameron@clerk.com</Item.HeaderTitle>
 <Button
 size='sm'
 shape='square'
 variant='ghost'
 >
 <EllipsisIcon />
 </Button>
 </Item.Header>
 <Item.Root>
 <Item.Root size='xs'>
 <Item.Content>
 <Item.Description>cameron.walker@gmail.com</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button
 variant='ghost'
 color='neutral'
 size='sm'
 shape='square'
 >
 <svg
 width='16'
 viewBox='0 0 16 16'
 >
 <path
 d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
 fill='currentColor'
 />
 <path
 d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
 fill='currentColor'
 />
 <path
 d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
 fill='currentColor'
 />
 </svg>
 </Button>
Comment thread
alexcarpenter marked this conversation as resolved.

 </Item.Actions>
 </Item.Root>
 <Item.Root size='xs'>
 <Item.Media>
 <Avatar.Root
 size='fit'
Expand All@@ -206,11 +233,11 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Description>24 members &bull; Basic</Item.Description>
 </Item.Content>
 <CheckMarkIcon width='28px' />
 </Item.Root>
 <Item.Root
 size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -234,13 +261,13 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Description>24 members &bull; Basic</Item.Description>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
 size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -260,14 +287,13 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>DesignCloud</Item.Title>
 <Item.Description>12 members &bull; Pro</Item.Description>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
variant='action'
size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -278,17 +304,14 @@ export function Group() {
 )}
 >
 <Item.Media>
 <PlusIcon width='36px' />
 <PlusIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Title>Add account</Item.Title>
 <Item.Label>Add account</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
variant='action'
size='xs'
 render={({ children, ...props }) => (
 <button
 type='button'
Expand All@@ -299,10 +322,10 @@ export function Group() {
 )}
 >
 <Item.Media>
 <SignOutIcon width='36px' />
 <SignOutIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Title>Sign out of all accounts</Item.Title>
 <Item.Label>Sign out of all accounts</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand Down

11 changes: 11 additions & 0 deletions
packages/ui/src/mosaic/components/item/item.markers.stylex.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
import * as stylex from '@stylexjs/stylex';

/**
 * Scopes a part's ancestor-state selectors to a Mosaic `Item.Root`, so an unrelated hovered
 * ancestor can't drive them. `Item.Root` applies it; `Item.Label` matches on it to follow the
 * row's hover rather than its own.
 *
 * Its own module because `@stylexjs/enforce-extension` requires the define-primitives to live in
 * a `.stylex.ts` file.
 */
export const itemScope = stylex.defineMarker();
Loading
Loading

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

Skip to content
feat(ui): scale Mosaic Item rows from a single size prop#9297

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 3 commits into

from

Jul 31, 2026
 Merged


feat(ui): scale Mosaic Item rows from a single size prop
#9297
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
dbe0001

feat(ui): scale Mosaic Item rows from a single size prop


alexcarpenter Jul 30, 2026
fa09923

update story


alexcarpenter Jul 30, 2026
d47e2da

fix(ui): key Mosaic Item label hover to the row


alexcarpenter Jul 31, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 2 additions & 0 deletions
.changeset/mosaic-item-size.md

View file


Open in desktop

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

67 changes: 46 additions & 21 deletions
packages/swingset/src/stories/item.mdx

View file


Open in desktop

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

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.

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.

## Example

<Story
Expand All@@ -18,6 +20,13 @@ Item is a flexible row for lists of accounts, organizations, and settings in Mos
 storyModule={ItemStories}
/>

### Sizes

<Story
 name='Sizes'
 storyModule={ItemStories}
/>

### Group

<Story
Expand All@@ -34,7 +43,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
<Item.Group>
 <Item.Root render={({ children, ...props }) => <a {...props} href='/org'>{children}</a>}>
 <Item.Media>
 <Avatar.Root shape='square' size='md'>
 <Avatar.Root shape='square' size='fit'>
 <Avatar.Image src={org.imageUrl} alt='' />
 <Avatar.Fallback>{org.name[0]}</Avatar.Fallback>
 </Avatar.Root>
Expand All@@ -44,46 +53,62 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Manage</Button>
 <Button variant='outline' size='sm'>Manage</Button>
 </Item.Actions>
 </Item.Root>
</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 at `width='100%'`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
 <Item.Media>
 <SignOutIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Label>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` | Leading (or trailing) media: icon, image, or avatar. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. |
| `Item.Description` | `cl-item-description` | Secondary text. Renders a `<p>`. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Header` | `cl-item-header` | Header row above a group: a label with optional actions. |
| `Item.HeaderTitle` | `cl-item-header-title` | Label text within an `Item.Header`. |
| `Item.HeaderActions` | `cl-item-header-actions` | Trailing controls within an `Item.Header`. |
| `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.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. Dimmed until hovered. |
| `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 root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

| Prop | Attribute | Values | Default |
| --------- | ------------------ | ----------------------------------- | -------- |
| `variant` | `data-variant` | `entity` \| `action` | `entity` |
| `render` | `data-interactive` | present when a `render` is provided | — |
| Prop | Attribute | Values | Default |
| -------- | ------------------ | ----------------------------------- | ------- |
| `size` | `data-size` | `xs` \| `md` | `md`  |
| `render` | `data-interactive` | present when a `render` is provided | — |

`variant` sets the row's vertical density (`entity` is standard, `action` is denser) and, on interactive rows, promotes the title color.
`size` fixes the row's height and gap. `Item.Media` reflects the same value as `data-size` and takes its width from it, so the two stay in step without being set twice:

```css
/* Re-theme interactive rows */
.cl-item[data-interactive] {
 background-color: var(--cl-color-card);
}

/* Widen the media column on compact rows */
.cl-item-media[data-size='xs'] {
 width: 1.5rem;
}
```

`Item.Media` sizes to its child and centers it; its height follows the row. Bring your own icon, avatar, or image at whatever dimensions you need, then size the slot by sizing that child. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).
`Item.Media` is a square that centers its child. Because the column is sized by the row, give it a child that fills it — an `Avatar.Root` with `size='fit'`, or an icon at `width='100%'` — rather than a fixed pixel size that won't track `size`. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).

133 changes: 78 additions & 55 deletions
packages/swingset/src/stories/item.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -35,36 +35,6 @@ function CheckMarkIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 );
}

function EllipsisIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 return (
 <svg
 viewBox='0 0 16 16'
 width='1em'
 height='1em'
 fill='none'
 {...props}
 >
 <path
 d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
 fill='#747686'
 />
 <path
 d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
 fill='#747686'
 />
 <path
 d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
 fill='#747686'
 />
 <rect
 width='0.0001'
 height='0.0001'
 fill='#747686'
 />
 </svg>
 );
}

function PlusIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 return (
 <svg
Expand DownExpand Up@@ -124,7 +94,12 @@ export function Default() {
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Manage</Button>
 <Button
 variant='outline'
 size='sm'
 >
 Manage
 </Button>
 </Item.Actions>
 </Item.Root>
 );
Expand DownExpand Up@@ -158,6 +133,31 @@ export function Interactive() {
 );
}

export function Sizes() {
 return (
 <div className='w-full'>
 {(['md', 'xs'] as const).map(size => (
 <Item.Root
 key={size}
 size={size}
 >
 <Item.Media>
 <Avatar.Root
 shape='square'
 size='fit'
 >
 <Avatar.Fallback>T</Avatar.Fallback>
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 </Item.Content>
 </Item.Root>
 ))}
 </div>
 );
}

export function Group() {
 return (
 <div className='w-full'>
Expand All@@ -173,25 +173,52 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Cameron Walker</Item.Title>
 <Item.Description>cameron@clerk.com</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Invite</Button>
 <Button
 variant='outline'
 size='sm'
 >
 Invite
 </Button>
 </Item.Actions>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Header>
 <Item.HeaderTitle>cameron@clerk.com</Item.HeaderTitle>
 <Button
 size='sm'
 shape='square'
 variant='ghost'
 >
 <EllipsisIcon />
 </Button>
 </Item.Header>
 <Item.Root>
 <Item.Root size='xs'>
 <Item.Content>
 <Item.Description>cameron.walker@gmail.com</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button
 variant='ghost'
 color='neutral'
 size='sm'
 shape='square'
 >
 <svg
 width='16'
 viewBox='0 0 16 16'
 >
 <path
 d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
 fill='currentColor'
 />
 <path
 d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
 fill='currentColor'
 />
 <path
 d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
 fill='currentColor'
 />
 </svg>
 </Button>
Comment thread
alexcarpenter marked this conversation as resolved.

 </Item.Actions>
 </Item.Root>
 <Item.Root size='xs'>
 <Item.Media>
 <Avatar.Root
 size='fit'
Expand All@@ -206,11 +233,11 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Description>24 members &bull; Basic</Item.Description>
 </Item.Content>
 <CheckMarkIcon width='28px' />
 </Item.Root>
 <Item.Root
 size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -234,13 +261,13 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Description>24 members &bull; Basic</Item.Description>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
 size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -260,14 +287,13 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>DesignCloud</Item.Title>
 <Item.Description>12 members &bull; Pro</Item.Description>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
variant='action'
size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -278,17 +304,14 @@ export function Group() {
 )}
 >
 <Item.Media>
 <PlusIcon width='36px' />
 <PlusIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Title>Add account</Item.Title>
 <Item.Label>Add account</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
variant='action'
size='xs'
 render={({ children, ...props }) => (
 <button
 type='button'
Expand All@@ -299,10 +322,10 @@ export function Group() {
 )}
 >
 <Item.Media>
 <SignOutIcon width='36px' />
 <SignOutIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Title>Sign out of all accounts</Item.Title>
 <Item.Label>Sign out of all accounts</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand Down

11 changes: 11 additions & 0 deletions
packages/ui/src/mosaic/components/item/item.markers.stylex.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
import * as stylex from '@stylexjs/stylex';

/**
 * Scopes a part's ancestor-state selectors to a Mosaic `Item.Root`, so an unrelated hovered
 * ancestor can't drive them. `Item.Root` applies it; `Item.Label` matches on it to follow the
 * row's hover rather than its own.
 *
 * Its own module because `@stylexjs/enforce-extension` requires the define-primitives to live in
 * a `.stylex.ts` file.
 */
export const itemScope = stylex.defineMarker();
Loading
Loading

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

Skip to content
feat(ui): scale Mosaic Item rows from a single size prop#9297

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 3 commits into

from

Jul 31, 2026
 Merged


feat(ui): scale Mosaic Item rows from a single size prop
#9297
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
dbe0001

feat(ui): scale Mosaic Item rows from a single size prop


alexcarpenter Jul 30, 2026
fa09923

update story


alexcarpenter Jul 30, 2026
d47e2da

fix(ui): key Mosaic Item label hover to the row


alexcarpenter Jul 31, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 2 additions & 0 deletions
.changeset/mosaic-item-size.md

View file


Open in desktop

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

67 changes: 46 additions & 21 deletions
packages/swingset/src/stories/item.mdx

View file


Open in desktop

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

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.

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.

## Example

<Story
Expand All@@ -18,6 +20,13 @@ Item is a flexible row for lists of accounts, organizations, and settings in Mos
 storyModule={ItemStories}
/>

### Sizes

<Story
 name='Sizes'
 storyModule={ItemStories}
/>

### Group

<Story
Expand All@@ -34,7 +43,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
<Item.Group>
 <Item.Root render={({ children, ...props }) => <a {...props} href='/org'>{children}</a>}>
 <Item.Media>
 <Avatar.Root shape='square' size='md'>
 <Avatar.Root shape='square' size='fit'>
 <Avatar.Image src={org.imageUrl} alt='' />
 <Avatar.Fallback>{org.name[0]}</Avatar.Fallback>
 </Avatar.Root>
Expand All@@ -44,46 +53,62 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Manage</Button>
 <Button variant='outline' size='sm'>Manage</Button>
 </Item.Actions>
 </Item.Root>
</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 at `width='100%'`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
 <Item.Media>
 <SignOutIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Label>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` | Leading (or trailing) media: icon, image, or avatar. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. |
| `Item.Description` | `cl-item-description` | Secondary text. Renders a `<p>`. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Header` | `cl-item-header` | Header row above a group: a label with optional actions. |
| `Item.HeaderTitle` | `cl-item-header-title` | Label text within an `Item.Header`. |
| `Item.HeaderActions` | `cl-item-header-actions` | Trailing controls within an `Item.Header`. |
| `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.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. Dimmed until hovered. |
| `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 root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

| Prop | Attribute | Values | Default |
| --------- | ------------------ | ----------------------------------- | -------- |
| `variant` | `data-variant` | `entity` \| `action` | `entity` |
| `render` | `data-interactive` | present when a `render` is provided | — |
| Prop | Attribute | Values | Default |
| -------- | ------------------ | ----------------------------------- | ------- |
| `size` | `data-size` | `xs` \| `md` | `md`  |
| `render` | `data-interactive` | present when a `render` is provided | — |

`variant` sets the row's vertical density (`entity` is standard, `action` is denser) and, on interactive rows, promotes the title color.
`size` fixes the row's height and gap. `Item.Media` reflects the same value as `data-size` and takes its width from it, so the two stay in step without being set twice:

```css
/* Re-theme interactive rows */
.cl-item[data-interactive] {
 background-color: var(--cl-color-card);
}

/* Widen the media column on compact rows */
.cl-item-media[data-size='xs'] {
 width: 1.5rem;
}
```

`Item.Media` sizes to its child and centers it; its height follows the row. Bring your own icon, avatar, or image at whatever dimensions you need, then size the slot by sizing that child. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).
`Item.Media` is a square that centers its child. Because the column is sized by the row, give it a child that fills it — an `Avatar.Root` with `size='fit'`, or an icon at `width='100%'` — rather than a fixed pixel size that won't track `size`. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).

133 changes: 78 additions & 55 deletions
packages/swingset/src/stories/item.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -35,36 +35,6 @@ function CheckMarkIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 );
}

function EllipsisIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 return (
 <svg
 viewBox='0 0 16 16'
 width='1em'
 height='1em'
 fill='none'
 {...props}
 >
 <path
 d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
 fill='#747686'
 />
 <path
 d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
 fill='#747686'
 />
 <path
 d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
 fill='#747686'
 />
 <rect
 width='0.0001'
 height='0.0001'
 fill='#747686'
 />
 </svg>
 );
}

function PlusIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 return (
 <svg
Expand DownExpand Up@@ -124,7 +94,12 @@ export function Default() {
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Manage</Button>
 <Button
 variant='outline'
 size='sm'
 >
 Manage
 </Button>
 </Item.Actions>
 </Item.Root>
 );
Expand DownExpand Up@@ -158,6 +133,31 @@ export function Interactive() {
 );
}

export function Sizes() {
 return (
 <div className='w-full'>
 {(['md', 'xs'] as const).map(size => (
 <Item.Root
 key={size}
 size={size}
 >
 <Item.Media>
 <Avatar.Root
 shape='square'
 size='fit'
 >
 <Avatar.Fallback>T</Avatar.Fallback>
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 </Item.Content>
 </Item.Root>
 ))}
 </div>
 );
}

export function Group() {
 return (
 <div className='w-full'>
Expand All@@ -173,25 +173,52 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Cameron Walker</Item.Title>
 <Item.Description>cameron@clerk.com</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Invite</Button>
 <Button
 variant='outline'
 size='sm'
 >
 Invite
 </Button>
 </Item.Actions>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Header>
 <Item.HeaderTitle>cameron@clerk.com</Item.HeaderTitle>
 <Button
 size='sm'
 shape='square'
 variant='ghost'
 >
 <EllipsisIcon />
 </Button>
 </Item.Header>
 <Item.Root>
 <Item.Root size='xs'>
 <Item.Content>
 <Item.Description>cameron.walker@gmail.com</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button
 variant='ghost'
 color='neutral'
 size='sm'
 shape='square'
 >
 <svg
 width='16'
 viewBox='0 0 16 16'
 >
 <path
 d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
 fill='currentColor'
 />
 <path
 d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
 fill='currentColor'
 />
 <path
 d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
 fill='currentColor'
 />
 </svg>
 </Button>
Comment thread
alexcarpenter marked this conversation as resolved.

 </Item.Actions>
 </Item.Root>
 <Item.Root size='xs'>
 <Item.Media>
 <Avatar.Root
 size='fit'
Expand All@@ -206,11 +233,11 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Description>24 members &bull; Basic</Item.Description>
 </Item.Content>
 <CheckMarkIcon width='28px' />
 </Item.Root>
 <Item.Root
 size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -234,13 +261,13 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Description>24 members &bull; Basic</Item.Description>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
 size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -260,14 +287,13 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>DesignCloud</Item.Title>
 <Item.Description>12 members &bull; Pro</Item.Description>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
variant='action'
size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -278,17 +304,14 @@ export function Group() {
 )}
 >
 <Item.Media>
 <PlusIcon width='36px' />
 <PlusIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Title>Add account</Item.Title>
 <Item.Label>Add account</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
variant='action'
size='xs'
 render={({ children, ...props }) => (
 <button
 type='button'
Expand All@@ -299,10 +322,10 @@ export function Group() {
 )}
 >
 <Item.Media>
 <SignOutIcon width='36px' />
 <SignOutIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Title>Sign out of all accounts</Item.Title>
 <Item.Label>Sign out of all accounts</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand Down

11 changes: 11 additions & 0 deletions
packages/ui/src/mosaic/components/item/item.markers.stylex.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
import * as stylex from '@stylexjs/stylex';

/**
 * Scopes a part's ancestor-state selectors to a Mosaic `Item.Root`, so an unrelated hovered
 * ancestor can't drive them. `Item.Root` applies it; `Item.Label` matches on it to follow the
 * row's hover rather than its own.
 *
 * Its own module because `@stylexjs/enforce-extension` requires the define-primitives to live in
 * a `.stylex.ts` file.
 */
export const itemScope = stylex.defineMarker();
Loading
Loading

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

Skip to content
feat(ui): scale Mosaic Item rows from a single size prop#9297

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 3 commits into

from

Jul 31, 2026
 Merged


feat(ui): scale Mosaic Item rows from a single size prop
#9297
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
dbe0001

feat(ui): scale Mosaic Item rows from a single size prop


alexcarpenter Jul 30, 2026
fa09923

update story


alexcarpenter Jul 30, 2026
d47e2da

fix(ui): key Mosaic Item label hover to the row


alexcarpenter Jul 31, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 2 additions & 0 deletions
.changeset/mosaic-item-size.md

View file


Open in desktop

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

67 changes: 46 additions & 21 deletions
packages/swingset/src/stories/item.mdx

View file


Open in desktop

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

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.

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.

## Example

<Story
Expand All@@ -18,6 +20,13 @@ Item is a flexible row for lists of accounts, organizations, and settings in Mos
 storyModule={ItemStories}
/>

### Sizes

<Story
 name='Sizes'
 storyModule={ItemStories}
/>

### Group

<Story
Expand All@@ -34,7 +43,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
<Item.Group>
 <Item.Root render={({ children, ...props }) => <a {...props} href='/org'>{children}</a>}>
 <Item.Media>
 <Avatar.Root shape='square' size='md'>
 <Avatar.Root shape='square' size='fit'>
 <Avatar.Image src={org.imageUrl} alt='' />
 <Avatar.Fallback>{org.name[0]}</Avatar.Fallback>
 </Avatar.Root>
Expand All@@ -44,46 +53,62 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Manage</Button>
 <Button variant='outline' size='sm'>Manage</Button>
 </Item.Actions>
 </Item.Root>
</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 at `width='100%'`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
 <Item.Media>
 <SignOutIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Label>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` | Leading (or trailing) media: icon, image, or avatar. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. |
| `Item.Description` | `cl-item-description` | Secondary text. Renders a `<p>`. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Header` | `cl-item-header` | Header row above a group: a label with optional actions. |
| `Item.HeaderTitle` | `cl-item-header-title` | Label text within an `Item.Header`. |
| `Item.HeaderActions` | `cl-item-header-actions` | Trailing controls within an `Item.Header`. |
| `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.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. Dimmed until hovered. |
| `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 root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

| Prop | Attribute | Values | Default |
| --------- | ------------------ | ----------------------------------- | -------- |
| `variant` | `data-variant` | `entity` \| `action` | `entity` |
| `render` | `data-interactive` | present when a `render` is provided | — |
| Prop | Attribute | Values | Default |
| -------- | ------------------ | ----------------------------------- | ------- |
| `size` | `data-size` | `xs` \| `md` | `md`  |
| `render` | `data-interactive` | present when a `render` is provided | — |

`variant` sets the row's vertical density (`entity` is standard, `action` is denser) and, on interactive rows, promotes the title color.
`size` fixes the row's height and gap. `Item.Media` reflects the same value as `data-size` and takes its width from it, so the two stay in step without being set twice:

```css
/* Re-theme interactive rows */
.cl-item[data-interactive] {
 background-color: var(--cl-color-card);
}

/* Widen the media column on compact rows */
.cl-item-media[data-size='xs'] {
 width: 1.5rem;
}
```

`Item.Media` sizes to its child and centers it; its height follows the row. Bring your own icon, avatar, or image at whatever dimensions you need, then size the slot by sizing that child. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).
`Item.Media` is a square that centers its child. Because the column is sized by the row, give it a child that fills it — an `Avatar.Root` with `size='fit'`, or an icon at `width='100%'` — rather than a fixed pixel size that won't track `size`. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).

133 changes: 78 additions & 55 deletions
packages/swingset/src/stories/item.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -35,36 +35,6 @@ function CheckMarkIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 );
}

function EllipsisIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 return (
 <svg
 viewBox='0 0 16 16'
 width='1em'
 height='1em'
 fill='none'
 {...props}
 >
 <path
 d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
 fill='#747686'
 />
 <path
 d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
 fill='#747686'
 />
 <path
 d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
 fill='#747686'
 />
 <rect
 width='0.0001'
 height='0.0001'
 fill='#747686'
 />
 </svg>
 );
}

function PlusIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 return (
 <svg
Expand DownExpand Up@@ -124,7 +94,12 @@ export function Default() {
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Manage</Button>
 <Button
 variant='outline'
 size='sm'
 >
 Manage
 </Button>
 </Item.Actions>
 </Item.Root>
 );
Expand DownExpand Up@@ -158,6 +133,31 @@ export function Interactive() {
 );
}

export function Sizes() {
 return (
 <div className='w-full'>
 {(['md', 'xs'] as const).map(size => (
 <Item.Root
 key={size}
 size={size}
 >
 <Item.Media>
 <Avatar.Root
 shape='square'
 size='fit'
 >
 <Avatar.Fallback>T</Avatar.Fallback>
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 </Item.Content>
 </Item.Root>
 ))}
 </div>
 );
}

export function Group() {
 return (
 <div className='w-full'>
Expand All@@ -173,25 +173,52 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Cameron Walker</Item.Title>
 <Item.Description>cameron@clerk.com</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Invite</Button>
 <Button
 variant='outline'
 size='sm'
 >
 Invite
 </Button>
 </Item.Actions>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Header>
 <Item.HeaderTitle>cameron@clerk.com</Item.HeaderTitle>
 <Button
 size='sm'
 shape='square'
 variant='ghost'
 >
 <EllipsisIcon />
 </Button>
 </Item.Header>
 <Item.Root>
 <Item.Root size='xs'>
 <Item.Content>
 <Item.Description>cameron.walker@gmail.com</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button
 variant='ghost'
 color='neutral'
 size='sm'
 shape='square'
 >
 <svg
 width='16'
 viewBox='0 0 16 16'
 >
 <path
 d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
 fill='currentColor'
 />
 <path
 d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
 fill='currentColor'
 />
 <path
 d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
 fill='currentColor'
 />
 </svg>
 </Button>
Comment thread
alexcarpenter marked this conversation as resolved.

 </Item.Actions>
 </Item.Root>
 <Item.Root size='xs'>
 <Item.Media>
 <Avatar.Root
 size='fit'
Expand All@@ -206,11 +233,11 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Description>24 members &bull; Basic</Item.Description>
 </Item.Content>
 <CheckMarkIcon width='28px' />
 </Item.Root>
 <Item.Root
 size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -234,13 +261,13 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Description>24 members &bull; Basic</Item.Description>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
 size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -260,14 +287,13 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>DesignCloud</Item.Title>
 <Item.Description>12 members &bull; Pro</Item.Description>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
variant='action'
size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -278,17 +304,14 @@ export function Group() {
 )}
 >
 <Item.Media>
 <PlusIcon width='36px' />
 <PlusIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Title>Add account</Item.Title>
 <Item.Label>Add account</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
variant='action'
size='xs'
 render={({ children, ...props }) => (
 <button
 type='button'
Expand All@@ -299,10 +322,10 @@ export function Group() {
 )}
 >
 <Item.Media>
 <SignOutIcon width='36px' />
 <SignOutIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Title>Sign out of all accounts</Item.Title>
 <Item.Label>Sign out of all accounts</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand Down

11 changes: 11 additions & 0 deletions
packages/ui/src/mosaic/components/item/item.markers.stylex.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
import * as stylex from '@stylexjs/stylex';

/**
 * Scopes a part's ancestor-state selectors to a Mosaic `Item.Root`, so an unrelated hovered
 * ancestor can't drive them. `Item.Root` applies it; `Item.Label` matches on it to follow the
 * row's hover rather than its own.
 *
 * Its own module because `@stylexjs/enforce-extension` requires the define-primitives to live in
 * a `.stylex.ts` file.
 */
export const itemScope = stylex.defineMarker();
Loading
Loading

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

Skip to content
feat(ui): scale Mosaic Item rows from a single size prop#9297

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 3 commits into

from

Jul 31, 2026
 Merged


feat(ui): scale Mosaic Item rows from a single size prop
#9297
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
dbe0001

feat(ui): scale Mosaic Item rows from a single size prop


alexcarpenter Jul 30, 2026
fa09923

update story


alexcarpenter Jul 30, 2026
d47e2da

fix(ui): key Mosaic Item label hover to the row


alexcarpenter Jul 31, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 2 additions & 0 deletions
.changeset/mosaic-item-size.md

View file


Open in desktop

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

67 changes: 46 additions & 21 deletions
packages/swingset/src/stories/item.mdx

View file


Open in desktop

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

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.

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.

## Example

<Story
Expand All@@ -18,6 +20,13 @@ Item is a flexible row for lists of accounts, organizations, and settings in Mos
 storyModule={ItemStories}
/>

### Sizes

<Story
 name='Sizes'
 storyModule={ItemStories}
/>

### Group

<Story
Expand All@@ -34,7 +43,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
<Item.Group>
 <Item.Root render={({ children, ...props }) => <a {...props} href='/org'>{children}</a>}>
 <Item.Media>
 <Avatar.Root shape='square' size='md'>
 <Avatar.Root shape='square' size='fit'>
 <Avatar.Image src={org.imageUrl} alt='' />
 <Avatar.Fallback>{org.name[0]}</Avatar.Fallback>
 </Avatar.Root>
Expand All@@ -44,46 +53,62 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Manage</Button>
 <Button variant='outline' size='sm'>Manage</Button>
 </Item.Actions>
 </Item.Root>
</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 at `width='100%'`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
 <Item.Media>
 <SignOutIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Label>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` | Leading (or trailing) media: icon, image, or avatar. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. |
| `Item.Description` | `cl-item-description` | Secondary text. Renders a `<p>`. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Header` | `cl-item-header` | Header row above a group: a label with optional actions. |
| `Item.HeaderTitle` | `cl-item-header-title` | Label text within an `Item.Header`. |
| `Item.HeaderActions` | `cl-item-header-actions` | Trailing controls within an `Item.Header`. |
| `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.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. Dimmed until hovered. |
| `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 root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

| Prop | Attribute | Values | Default |
| --------- | ------------------ | ----------------------------------- | -------- |
| `variant` | `data-variant` | `entity` \| `action` | `entity` |
| `render` | `data-interactive` | present when a `render` is provided | — |
| Prop | Attribute | Values | Default |
| -------- | ------------------ | ----------------------------------- | ------- |
| `size` | `data-size` | `xs` \| `md` | `md`  |
| `render` | `data-interactive` | present when a `render` is provided | — |

`variant` sets the row's vertical density (`entity` is standard, `action` is denser) and, on interactive rows, promotes the title color.
`size` fixes the row's height and gap. `Item.Media` reflects the same value as `data-size` and takes its width from it, so the two stay in step without being set twice:

```css
/* Re-theme interactive rows */
.cl-item[data-interactive] {
 background-color: var(--cl-color-card);
}

/* Widen the media column on compact rows */
.cl-item-media[data-size='xs'] {
 width: 1.5rem;
}
```

`Item.Media` sizes to its child and centers it; its height follows the row. Bring your own icon, avatar, or image at whatever dimensions you need, then size the slot by sizing that child. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).
`Item.Media` is a square that centers its child. Because the column is sized by the row, give it a child that fills it — an `Avatar.Root` with `size='fit'`, or an icon at `width='100%'` — rather than a fixed pixel size that won't track `size`. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).

133 changes: 78 additions & 55 deletions
packages/swingset/src/stories/item.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -35,36 +35,6 @@ function CheckMarkIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 );
}

function EllipsisIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 return (
 <svg
 viewBox='0 0 16 16'
 width='1em'
 height='1em'
 fill='none'
 {...props}
 >
 <path
 d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
 fill='#747686'
 />
 <path
 d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
 fill='#747686'
 />
 <path
 d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
 fill='#747686'
 />
 <rect
 width='0.0001'
 height='0.0001'
 fill='#747686'
 />
 </svg>
 );
}

function PlusIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 return (
 <svg
Expand DownExpand Up@@ -124,7 +94,12 @@ export function Default() {
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Manage</Button>
 <Button
 variant='outline'
 size='sm'
 >
 Manage
 </Button>
 </Item.Actions>
 </Item.Root>
 );
Expand DownExpand Up@@ -158,6 +133,31 @@ export function Interactive() {
 );
}

export function Sizes() {
 return (
 <div className='w-full'>
 {(['md', 'xs'] as const).map(size => (
 <Item.Root
 key={size}
 size={size}
 >
 <Item.Media>
 <Avatar.Root
 shape='square'
 size='fit'
 >
 <Avatar.Fallback>T</Avatar.Fallback>
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 </Item.Content>
 </Item.Root>
 ))}
 </div>
 );
}

export function Group() {
 return (
 <div className='w-full'>
Expand All@@ -173,25 +173,52 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Cameron Walker</Item.Title>
 <Item.Description>cameron@clerk.com</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Invite</Button>
 <Button
 variant='outline'
 size='sm'
 >
 Invite
 </Button>
 </Item.Actions>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Header>
 <Item.HeaderTitle>cameron@clerk.com</Item.HeaderTitle>
 <Button
 size='sm'
 shape='square'
 variant='ghost'
 >
 <EllipsisIcon />
 </Button>
 </Item.Header>
 <Item.Root>
 <Item.Root size='xs'>
 <Item.Content>
 <Item.Description>cameron.walker@gmail.com</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button
 variant='ghost'
 color='neutral'
 size='sm'
 shape='square'
 >
 <svg
 width='16'
 viewBox='0 0 16 16'
 >
 <path
 d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
 fill='currentColor'
 />
 <path
 d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
 fill='currentColor'
 />
 <path
 d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
 fill='currentColor'
 />
 </svg>
 </Button>
Comment thread
alexcarpenter marked this conversation as resolved.

 </Item.Actions>
 </Item.Root>
 <Item.Root size='xs'>
 <Item.Media>
 <Avatar.Root
 size='fit'
Expand All@@ -206,11 +233,11 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Description>24 members &bull; Basic</Item.Description>
 </Item.Content>
 <CheckMarkIcon width='28px' />
 </Item.Root>
 <Item.Root
 size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -234,13 +261,13 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Description>24 members &bull; Basic</Item.Description>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
 size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -260,14 +287,13 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>DesignCloud</Item.Title>
 <Item.Description>12 members &bull; Pro</Item.Description>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
variant='action'
size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -278,17 +304,14 @@ export function Group() {
 )}
 >
 <Item.Media>
 <PlusIcon width='36px' />
 <PlusIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Title>Add account</Item.Title>
 <Item.Label>Add account</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
variant='action'
size='xs'
 render={({ children, ...props }) => (
 <button
 type='button'
Expand All@@ -299,10 +322,10 @@ export function Group() {
 )}
 >
 <Item.Media>
 <SignOutIcon width='36px' />
 <SignOutIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Title>Sign out of all accounts</Item.Title>
 <Item.Label>Sign out of all accounts</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand Down

11 changes: 11 additions & 0 deletions
packages/ui/src/mosaic/components/item/item.markers.stylex.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
import * as stylex from '@stylexjs/stylex';

/**
 * Scopes a part's ancestor-state selectors to a Mosaic `Item.Root`, so an unrelated hovered
 * ancestor can't drive them. `Item.Root` applies it; `Item.Label` matches on it to follow the
 * row's hover rather than its own.
 *
 * Its own module because `@stylexjs/enforce-extension` requires the define-primitives to live in
 * a `.stylex.ts` file.
 */
export const itemScope = stylex.defineMarker();
Loading
Loading

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

Skip to content
feat(ui): scale Mosaic Item rows from a single size prop#9297

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 3 commits into

from

Jul 31, 2026
 Merged


feat(ui): scale Mosaic Item rows from a single size prop
#9297
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
dbe0001

feat(ui): scale Mosaic Item rows from a single size prop


alexcarpenter Jul 30, 2026
fa09923

update story


alexcarpenter Jul 30, 2026
d47e2da

fix(ui): key Mosaic Item label hover to the row


alexcarpenter Jul 31, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 2 additions & 0 deletions
.changeset/mosaic-item-size.md

View file


Open in desktop

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

67 changes: 46 additions & 21 deletions
packages/swingset/src/stories/item.mdx

View file


Open in desktop

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

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.

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.

## Example

<Story
Expand All@@ -18,6 +20,13 @@ Item is a flexible row for lists of accounts, organizations, and settings in Mos
 storyModule={ItemStories}
/>

### Sizes

<Story
 name='Sizes'
 storyModule={ItemStories}
/>

### Group

<Story
Expand All@@ -34,7 +43,7 @@ import { Item } from '@clerk/ui/mosaic/components/item';
<Item.Group>
 <Item.Root render={({ children, ...props }) => <a {...props} href='/org'>{children}</a>}>
 <Item.Media>
 <Avatar.Root shape='square' size='md'>
 <Avatar.Root shape='square' size='fit'>
 <Avatar.Image src={org.imageUrl} alt='' />
 <Avatar.Fallback>{org.name[0]}</Avatar.Fallback>
 </Avatar.Root>
Expand All@@ -44,46 +53,62 @@ import { Item } from '@clerk/ui/mosaic/components/item';
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Manage</Button>
 <Button variant='outline' size='sm'>Manage</Button>
 </Item.Actions>
 </Item.Root>
</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 at `width='100%'`. An action row that has no secondary text uses `Item.Label` in place of `Item.Title`:

```tsx
<Item.Root size='xs' render={({ children, ...props }) => <button type='button' {...props}>{children}</button>}>
 <Item.Media>
 <SignOutIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Label>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` | Leading (or trailing) media: icon, image, or avatar. |
| `Item.Content` | `cl-item-content` | Vertical stack that grows to fill the row between media and actions. |
| `Item.Title` | `cl-item-title` | Primary label. |
| `Item.Description` | `cl-item-description` | Secondary text. Renders a `<p>`. |
| `Item.Actions` | `cl-item-actions` | Trailing controls (buttons, badges). |
| `Item.Header` | `cl-item-header` | Header row above a group: a label with optional actions. |
| `Item.HeaderTitle` | `cl-item-header-title` | Label text within an `Item.Header`. |
| `Item.HeaderActions` | `cl-item-header-actions` | Trailing controls within an `Item.Header`. |
| `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.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. Dimmed until hovered. |
| `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 root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:

| Prop | Attribute | Values | Default |
| --------- | ------------------ | ----------------------------------- | -------- |
| `variant` | `data-variant` | `entity` \| `action` | `entity` |
| `render` | `data-interactive` | present when a `render` is provided | — |
| Prop | Attribute | Values | Default |
| -------- | ------------------ | ----------------------------------- | ------- |
| `size` | `data-size` | `xs` \| `md` | `md`  |
| `render` | `data-interactive` | present when a `render` is provided | — |

`variant` sets the row's vertical density (`entity` is standard, `action` is denser) and, on interactive rows, promotes the title color.
`size` fixes the row's height and gap. `Item.Media` reflects the same value as `data-size` and takes its width from it, so the two stay in step without being set twice:

```css
/* Re-theme interactive rows */
.cl-item[data-interactive] {
 background-color: var(--cl-color-card);
}

/* Widen the media column on compact rows */
.cl-item-media[data-size='xs'] {
 width: 1.5rem;
}
```

`Item.Media` sizes to its child and centers it; its height follows the row. Bring your own icon, avatar, or image at whatever dimensions you need, then size the slot by sizing that child. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).
`Item.Media` is a square that centers its child. Because the column is sized by the row, give it a child that fills it — an `Avatar.Root` with `size='fit'`, or an icon at `width='100%'` — rather than a fixed pixel size that won't track `size`. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).

133 changes: 78 additions & 55 deletions
packages/swingset/src/stories/item.stories.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -35,36 +35,6 @@ function CheckMarkIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 );
}

function EllipsisIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 return (
 <svg
 viewBox='0 0 16 16'
 width='1em'
 height='1em'
 fill='none'
 {...props}
 >
 <path
 d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
 fill='#747686'
 />
 <path
 d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
 fill='#747686'
 />
 <path
 d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
 fill='#747686'
 />
 <rect
 width='0.0001'
 height='0.0001'
 fill='#747686'
 />
 </svg>
 );
}

function PlusIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
 return (
 <svg
Expand DownExpand Up@@ -124,7 +94,12 @@ export function Default() {
 <Item.Description>Member</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Manage</Button>
 <Button
 variant='outline'
 size='sm'
 >
 Manage
 </Button>
 </Item.Actions>
 </Item.Root>
 );
Expand DownExpand Up@@ -158,6 +133,31 @@ export function Interactive() {
 );
}

export function Sizes() {
 return (
 <div className='w-full'>
 {(['md', 'xs'] as const).map(size => (
 <Item.Root
 key={size}
 size={size}
 >
 <Item.Media>
 <Avatar.Root
 shape='square'
 size='fit'
 >
 <Avatar.Fallback>T</Avatar.Fallback>
 </Avatar.Root>
 </Item.Media>
 <Item.Content>
 <Item.Title>Test Organization</Item.Title>
 </Item.Content>
 </Item.Root>
 ))}
 </div>
 );
}

export function Group() {
 return (
 <div className='w-full'>
Expand All@@ -173,25 +173,52 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Cameron Walker</Item.Title>
 <Item.Description>cameron@clerk.com</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button variant='outline'>Invite</Button>
 <Button
 variant='outline'
 size='sm'
 >
 Invite
 </Button>
 </Item.Actions>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Header>
 <Item.HeaderTitle>cameron@clerk.com</Item.HeaderTitle>
 <Button
 size='sm'
 shape='square'
 variant='ghost'
 >
 <EllipsisIcon />
 </Button>
 </Item.Header>
 <Item.Root>
 <Item.Root size='xs'>
 <Item.Content>
 <Item.Description>cameron.walker@gmail.com</Item.Description>
 </Item.Content>
 <Item.Actions>
 <Button
 variant='ghost'
 color='neutral'
 size='sm'
 shape='square'
 >
 <svg
 width='16'
 viewBox='0 0 16 16'
 >
 <path
 d='M2.75 8.01978V8.01001C2.75 7.31965 3.30964 6.76001 4 6.76001C4.69036 6.76001 5.25 7.31965 5.25 8.01001V8.01978C5.25 8.71013 4.69036 9.26978 4 9.26978C3.30964 9.26978 2.75 8.71013 2.75 8.01978Z'
 fill='currentColor'
 />
 <path
 d='M6.75 8.00977V8C6.75 7.30964 7.30964 6.75 8 6.75C8.69036 6.75 9.25 7.30964 9.25 8V8.00977C9.25 8.70012 8.69036 9.25977 8 9.25977C7.30964 9.25977 6.75 8.70012 6.75 8.00977Z'
 fill='currentColor'
 />
 <path
 d='M10.75 8.00977V8C10.75 7.30964 11.3096 6.75 12 6.75C12.6904 6.75 13.25 7.30964 13.25 8V8.00977C13.25 8.70012 12.6904 9.25977 12 9.25977C11.3096 9.25977 10.75 8.70012 10.75 8.00977Z'
 fill='currentColor'
 />
 </svg>
 </Button>
Comment thread
alexcarpenter marked this conversation as resolved.

 </Item.Actions>
 </Item.Root>
 <Item.Root size='xs'>
 <Item.Media>
 <Avatar.Root
 size='fit'
Expand All@@ -206,11 +233,11 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Description>24 members &bull; Basic</Item.Description>
 </Item.Content>
 <CheckMarkIcon width='28px' />
 </Item.Root>
 <Item.Root
 size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -234,13 +261,13 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>Clerk</Item.Title>
 <Item.Description>24 members &bull; Basic</Item.Description>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
 size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -260,14 +287,13 @@ export function Group() {
 </Item.Media>
 <Item.Content>
 <Item.Title>DesignCloud</Item.Title>
 <Item.Description>12 members &bull; Pro</Item.Description>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
variant='action'
size='xs'
 render={({ children, ...props }) => (
 <a
 {...props}
Expand All@@ -278,17 +304,14 @@ export function Group() {
 )}
 >
 <Item.Media>
 <PlusIcon width='36px' />
 <PlusIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Title>Add account</Item.Title>
 <Item.Label>Add account</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
 <Item.Separator />
 <Item.Group>
 <Item.Root
variant='action'
size='xs'
 render={({ children, ...props }) => (
 <button
 type='button'
Expand All@@ -299,10 +322,10 @@ export function Group() {
 )}
 >
 <Item.Media>
 <SignOutIcon width='36px' />
 <SignOutIcon width='100%' />
 </Item.Media>
 <Item.Content>
 <Item.Title>Sign out of all accounts</Item.Title>
 <Item.Label>Sign out of all accounts</Item.Label>
 </Item.Content>
 </Item.Root>
 </Item.Group>
Expand Down

11 changes: 11 additions & 0 deletions
packages/ui/src/mosaic/components/item/item.markers.stylex.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
import * as stylex from '@stylexjs/stylex';

/**
 * Scopes a part's ancestor-state selectors to a Mosaic `Item.Root`, so an unrelated hovered
 * ancestor can't drive them. `Item.Root` applies it; `Item.Label` matches on it to follow the
 * row's hover rather than its own.
 *
 * Its own module because `@stylexjs/enforce-extension` requires the define-primitives to live in
 * a `.stylex.ts` file.
 */
export const itemScope = stylex.defineMarker();
Loading
Loading