Skip to content

feat(ui): add Mosaic Avatar component #9230

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Open
alexcarpenter wants to merge 7 commits into
base: main
Choose a base branch
from
Open

feat(ui): add Mosaic Avatar component #9230

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0289259
feat(ui): add Mosaic Avatar component
alexcarpenter Jul 23, 2026
55a1e12
refactor(ui): make Mosaic Avatar a compound component
alexcarpenter Jul 23, 2026
76541d9
docs(ui): update Avatar changeset for compound API
alexcarpenter Jul 23, 2026
0a2876c
fix(ui): restore Avatar compound imports in swingset story
alexcarpenter Jul 23, 2026
8f1a8b9
docs(swingset): use Clerk logo in Avatar examples; document import-st…
alexcarpenter Jul 23, 2026
e443a8e
refactor(ui): use Avatar.Root/.Image/.Fallback namespace API
alexcarpenter Jul 23, 2026
dbf4351
refactor(ui): adopt mergeStyleProps rename in Avatar
alexcarpenter Jul 23, 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
5 changes: 5 additions & 0 deletions .changeset/mosaic-avatar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@clerk/ui': minor
---

Add a new Mosaic `Avatar` compound component (StyleX). `Avatar.Root` owns `shape` (`circle` | `square`) and `size` (`lg` | `md` | `sm` | `xs`); compose `Avatar.Image` (renders once the image loads) and `Avatar.Fallback` (shown while the image is pending or has failed, with an optional `delayMs`) inside it.
27 changes: 14 additions & 13 deletions .claude/skills/clerk-monorepo/references/setup-and-footguns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,19 +35,20 @@ reports here.

## Footguns

| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Trap | Symptom | Fix |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| System Node instead of 24.15 | Build "passes" but `Cannot find module @clerk/...` or missing types appear later | `node --version`; `nvm use` (`.nvmrc` pins 24.15.0) |
| `pnpm install` before `corepack enable` (or using npm/yarn) | `preinstall` aborts with an "only pnpm allowed" error | `corepack enable`, then `pnpm install` |
| Installing from a package subdirectory | Workspace links incomplete; runtime `Cannot resolve @clerk/shared` | Always `pnpm install` from the repo root |
| `pnpm dev` before `pnpm build` | Watch mode emits broken output; phantom type errors | Run `pnpm build` once first, then `dev` |
| Stale turbo cache after a Node/pnpm change | Old code runs, types do not update, unrelated tests fail | `pnpm nuke` (removes `.turbo`, `node_modules`, `dist`, coverage), then `pnpm install && pnpm build` |
| `pnpm --filter <pkg> build/test` expecting deps to build | Filtered pnpm scripts skip turbo's `^build`, so deps may be stale | Use `pnpm turbo build/test --filter=@clerk/<pkg>` to include dependencies |
| Stale `@clerk/shared` / types after editing shared | Type errors that "should not" exist in consumers | `pnpm turbo build --filter=@clerk/shared` |
| Editing the hosted UI but seeing no change | `ui` ships as its own `ui.browser.js` loaded alongside `clerk-js`; you watched the wrong target | Use `pnpm dev:fe-libs` so `ui` + `clerk-js` rebuild together |
| Committing integration secrets | `integration/.env.local`, `.keys.json`, `.keys.staging.json`, or `certs/sessions*.pem` leaked | Generated/fetched locally and gitignored; never add them. Under `certs/` only `sessions.pem` / `sessions-key.pem` are ignored, so keep other cert names out of git |
| Running integration tests without 1Password set up | `pnpm integration:secrets` fails to read from 1Password | Install the `op` CLI and enable desktop-app integration (below) |
| First `pnpm install` "hangs" | Large monorepo, large lockfile | Expected for the first run; give it a few minutes before assuming failure |
| Adding an `import` in a separate edit before its first use | On-save lint-fix (`unused-imports/no-unused-imports`, an `error` in `eslint.config.mjs`) deletes the not-yet-referenced import; the next edit that adds the usage then throws `X is not defined` at runtime. Common when wiring a new export across files (e.g. swingset `registry.ts` + a `*.stories.tsx`). | Add the import and its first usage in the **same** edit, or add the usage first. After a multi-file wiring change, `grep` the new symbol to confirm both its `import` and its use survived before committing. |

## Unit tests vs integration tests

Expand Down
1 change: 1 addition & 0 deletions packages/swingset/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ These require reading several files together; the `README.md` covers the step-by
- **Knobs are generated from CVA metadata, not hand-written.** A story's `meta.styles` is a Mosaic CVA style object exposing `_variants` / `_defaultVariants`. `lib/generateKnobs.ts` turns each variant into a control: variants whose keys are only `true`/`false` become boolean toggles, everything else becomes a select. Knob values are passed as props straight into the story component. This is why story functions take `Record<string, unknown>` and cast to the real prop type.

- **`lib/registry.ts` is the single source of truth for which components exist**, and they are imported *explicitly* (never `import *`) so sidebar order is deterministic. `getSidebarGroups`, `getModuleBySlug`, and slugging (`lib/slug.ts`, from `meta.title`) read from it. Adding a component touches up to three wiring points: `registry.ts` (sidebar entry + per-page playground lookup), `DocsViewer.tsx`'s `docModules` map (MDX docs), and the hardcoded redirect in `app/page.tsx`.
- ⚠️ **Add each new import and its first usage in the same edit.** The on-save lint-fix (`unused-imports/no-unused-imports` is an `error`) deletes any import that isn't referenced yet, so importing a story export in `registry.ts` (or a component in a `*.stories.tsx`) *before* the code that uses it silently drops the import and you get `X is not defined` at runtime. After wiring, `grep` the new symbol to confirm both the import and its use survived. (Repo-wide footgun; see `clerk-monorepo` skill `references/setup-and-footguns.md`.)

- **Routing.** Each component is a single page: `/components/[component]` renders its MDX overview via `DocsViewer`. There are no per-story sub-pages — the interactive playground lives *inside* the overview. `app/page.tsx` is a static redirect (currently to `/components/button`) because `registry.ts` eagerly imports story modules (Emotion / `createContext`), so registry-derived data can't be computed in a Server Component. `DocsViewer` also renders a "View source" link (`ViewSource.tsx`) from `meta.source` — a repo-root-relative path turned into a GitHub URL by `lib/source.ts`.

Expand Down
1 change: 1 addition & 0 deletions packages/swingset/src/components/DocsViewer.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
destructive: dynamic(() => import('../stories/destructive.mdx')),
},
components: {
avatar: dynamic(() => import('../stories/avatar.mdx')),
button: dynamic(() => import('../stories/button.mdx')),
card: dynamic(() => import('../stories/card.component.mdx')),
input: dynamic(() => import('../stories/input.mdx')),
Expand Down
16 changes: 16 additions & 0 deletions packages/swingset/src/lib/registry.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,13 @@
// Import stories explicitly to control order and avoid type casting through unknown.
import { meta as accordionMeta } from '../stories/accordion.stories';
import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
import {
Fallback as AvatarFallbackStory,
meta as avatarMeta,
Primary as AvatarPrimary,
Shapes as AvatarShapes,
Sizes as AvatarSizes,
} from '../stories/avatar.stories';
import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
import {
Centered as CardCentered,
Expand Down Expand Up @@ -115,6 +122,14 @@ const organizationProfileMembersPanelModule: StoryModule = {

const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };

const avatarModule: StoryModule = {
meta: avatarMeta,
Primary: AvatarPrimary,
Fallback: AvatarFallbackStory,
Sizes: AvatarSizes,
Shapes: AvatarShapes,
};

const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };

const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
Expand Down Expand Up @@ -171,6 +186,7 @@ export const registry: StoryModule[] = [
// Blocks
destructiveModule,
// Components
avatarModule,
buttonModule,
cardComponentModule,
inputModule,
Expand Down
67 changes: 67 additions & 0 deletions packages/swingset/src/stories/avatar.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
import * as AvatarStories from './avatar.stories';

# Avatar

Avatar represents a user or entity as an image, falling back to initials or an icon when the image is missing or fails to load. It is a compound component: `Avatar.Root` clips and sizes the box, `Avatar.Image` renders the picture once it loads, and `Avatar.Fallback` shows until then.

## Playground

<Preview
name='Primary'
storyModule={AvatarStories}
/>

## Props

`shape` and `size` live on `Avatar.Root`:

<PropTable meta={AvatarStories.meta} />

## Usage

```tsx
import { Avatar } from '@clerk/ui/mosaic/components/avatar';

<Avatar.Root>
<Avatar.Image
src='https://github.com/clerk.png'
alt='@clerk'
/>
<Avatar.Fallback>CL</Avatar.Fallback>
</Avatar.Root>;
```

## Parts

| Part | Slot (`.cl-*`) | Description |
| ----------------- | -------------------- | ---------------------------------------------------------------------- |
| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape. |
| `Avatar.Image` | `cl-avatar-image` | Renders an `<img>` once the source loads; renders nothing until then. |
| `Avatar.Fallback` | `cl-avatar-fallback` | Rendered while the image is pending or has failed. Optional `delayMs`. |

---

## Examples

### Fallback

When the image fails to load, the fallback stays visible.

<Story
name='Fallback'
storyModule={AvatarStories}
/>

### Sizes

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

### Shapes

<Story
name='Shapes'
storyModule={AvatarStories}
/>
Loading
Loading