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 number Diff line number Diff 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 number Diff line number Diff 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 number Diff line number Diff 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 Down Expand 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 Down Expand 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 number Diff line number Diff 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