feat(ui): add Avatar button composition

[austincalvelage]

Description

https://swingset-git-austin-user-profile-03-avatar-button.clerkstage.dev/components/avatar

Adds support for Avatar button this will eventually be used in a component like

<AvatarUploader /> as the trigger.

• Adds render support to Avatar.Root, allowing the avatar to render as a button or dialog trigger without an additional wrapper.
• Adds the Avatar.Icon
• Adds the pen glyph to the Mosaic icon registry.
• Adds the --cl-color-avatar-icon token so the edit icon can be themed independently.

import { Avatar } from '@clerk/ui/mosaic/components/avatar';
import { Button } from '@clerk/ui/mosaic/components/button';
import { Icon } from '@clerk/ui/mosaic/components/icon';

<Avatar.Root
  size='lg'
  render={
    <Button
      aria-label='Edit profile picture'
      color='neutral'
      shape='circle'
      variant='ghost'
    />
  }
>
  <Avatar.Image
    src='https://avatars.githubusercontent.com/u/51144033?v=4'
    alt='Colin'
  />
  <Avatar.Fallback>CL</Avatar.Fallback>
  <Avatar.Icon>
    <Icon name='pen' />
  </Avatar.Icon>
</Avatar.Root>;

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
swingset	Ready	Preview	Aug 12, 2026 1:39am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Skipped		Aug 12, 2026 1:39am

[changeset-bot]

🦋 Changeset detected

Latest commit: 3c92f74

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9378

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9378

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9378

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9378

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9378

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9378

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9378

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9378

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9378

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9378

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9378

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9378

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9378

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9378

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9378

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9378

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9378

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9378

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9378

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9378

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9378

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9378

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9378

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9378

commit: 3c92f74

[github-actions]

API Changes Report

Generated by Break Check on 2026-08-12T01:53:01.367Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 3c92f74.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The Avatar component now supports rendering onto custom elements such as buttons through render. It adds Avatar.Icon with context validation and accessibility-hidden output. Styles support button sizing and an overlaid icon. The icon registry adds the pen glyph with a custom viewBox. Tests cover composition and icon output. Swingset adds and documents an interactive Avatar story.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• clerk/javascript#9184: Both changes update the Swingset registry and Mosaic icon registry.
• clerk/javascript#9282: The Avatar button composition uses the updated Mosaic Button API and styles.
• clerk/javascript#9398: Both changes modify Avatar implementation, styles, tests, and documentation.

Suggested reviewers: alexcarpenter, maxyinger

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description directly explains Avatar button composition, Avatar.Icon, the pen glyph, and the related theme token.
Title check	✅ Passed	The title clearly and concisely identifies the main change: composing Avatar as a button.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.changeset/avatar-button-block.md:
- Around line 1-2: Add a non-empty Changeset entry for `@clerk/ui` declaring a
minor release and summarize the newly public Avatar.Root.render, Avatar.Icon,
and AvatarIconProps APIs.

In `@packages/swingset/src/stories/avatar.mdx`:
- Line 5: Rework the Avatar documentation page to follow the compound-component
structure: use the sections Example, Usage, Parts, and Styling in that exact
order. Replace the existing Playground, Props, and Examples structure, and
remove all Preview and PropTable usage while preserving the Avatar component
details.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 87c92f21-8289-4db6-b64c-5d034cf31131

📥 Commits

Reviewing files that changed from the base of the PR and between 44edcc9 and 3c92f74.

📒 Files selected for processing (12)

• .changeset/avatar-button-block.md
• packages/swingset/src/lib/registry.ts
• packages/swingset/src/stories/avatar.mdx
• packages/swingset/src/stories/avatar.stories.tsx
• packages/ui/src/mosaic/components/avatar/avatar.styles.ts
• packages/ui/src/mosaic/components/avatar/avatar.test.tsx
• packages/ui/src/mosaic/components/avatar/avatar.tsx
• packages/ui/src/mosaic/components/avatar/index.ts
• packages/ui/src/mosaic/components/icon/icon.test.tsx
• packages/ui/src/mosaic/icons/registry.tsx
• packages/ui/src/mosaic/styles/index.ts
• packages/ui/src/mosaic/tokens.stylex.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• clerk/clerk_go (manual)
• clerk/dashboard (manual)
• clerk/accounts (manual)
• clerk/backoffice (manual)
• clerk/clerk (manual)
• clerk/clerk-docs (manual)
• clerk/cloudflare-workers (manual)
• clerk/clerk-ios (auto-detected)
• clerk/cli (auto-detected)
• clerk/clerk-android (auto-detected)

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Add a release entry for @clerk/ui.

This PR adds public Avatar.Root.render, Avatar.Icon, and AvatarIconProps. An empty Changeset will not create a package version or changelog entry for consumers. Add an @clerk/ui minor release entry with a concise summary.

Based on learnings, empty Changesets are acceptable only when no published package requires release metadata. As per coding guidelines, “Use Changesets for version management and changelogs.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.changeset/avatar-button-block.md around lines 1 - 2, Add a non-empty
Changeset entry for `@clerk/ui` declaring a minor release and summarize the newly
public Avatar.Root.render, Avatar.Icon, and AvatarIconProps APIs.

Sources: Coding guidelines, Learnings

[coderabbitai]

📐 Maintainability & Code Quality | 🟠 Major | 🏗️ Heavy lift

Use the required compound-component documentation archetype.

Avatar is a compound component, but this page uses Playground, Props, and Examples. It also uses <Preview> and <PropTable>. Replace the page structure with Example, Usage, Parts, then Styling. Remove <Preview> and <PropTable>.

As per coding guidelines, “Compound Components pages must use the exact section order: Example, Usage, Parts, then Styling, with no <Preview> or <PropTable>.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/swingset/src/stories/avatar.mdx` at line 5, Rework the Avatar
documentation page to follow the compound-component structure: use the sections
Example, Usage, Parts, and Styling in that exact order. Replace the existing
Playground, Props, and Examples structure, and remove all Preview and PropTable
usage while preserving the Avatar component details.

Source: Coding guidelines