feat(ui): add Avatar button composition

.changeset/avatar-button-block.md

@@ -0,0 +1,2 @@
+---
+---

.changeset/mosaic-avatar-interactive-styles.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/lib/registry.ts

@@ -3,6 +3,7 @@ import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import {
  Fallback as AvatarFallbackStory,
+ Interactive as AvatarInteractive,
  meta as avatarMeta,
  Primary as AvatarPrimary,
  Shapes as AvatarShapes,
@@ -175,6 +176,7 @@ const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: Car
 const avatarModule: StoryModule = {
  meta: avatarMeta,
  Primary: AvatarPrimary,
+ Interactive: AvatarInteractive,
  Fallback: AvatarFallbackStory,
  Sizes: AvatarSizes,
  Shapes: AvatarShapes,

packages/swingset/src/stories/avatar.mdx

@@ -2,7 +2,7 @@ import * as AvatarStories from './avatar.stories';
 
 # Avatar
 
-Avatar represents a user or entity as an image, falling back to a blank placeholder 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` holds the space until then.
+Avatar represents a user or entity as an image, falling back to a blank placeholder when the image is missing or fails to load. It is a compound component: `Avatar.Root` positions and sizes the box, `Avatar.Image` renders the picture once it loads, `Avatar.Fallback` holds the space until then, and `Avatar.Icon` adds an optional corner affordance.
 
 The fallback still takes children — initials, an icon — but never paints them, so an entity without a picture reads as an absent image rather than as two letters. They stay in the DOM, held in an `avatar-fallback-content` slot that is `visibility: hidden`: out of the page, the accessibility tree, and the tab order together, and overridable by a consumer who wants them back.
 
@@ -37,10 +37,11 @@ import { Avatar } from '@clerk/ui/mosaic/components/avatar';
 
 | Part | Slot (`.cl-*`) | Description |
 | ----------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape.  |
+| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, positioning, and polymorphic rendering. |
 | `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. Carries `data-pending` while an image is still resolving. Optional `delayMs`. |
 | — | `cl-avatar-fallback-content` | Wraps whatever `Avatar.Fallback` was handed, hidden. Override its `visibility` to paint initials or an icon. |
+| `Avatar.Icon` | `cl-avatar-icon` | Renders an optional icon surface over the avatar corner. |
 
 ---
 
@@ -55,6 +56,15 @@ While an image is still resolving, the fallback carries `data-pending` and pulse
  storyModule={AvatarStories}
 />
 
+### Interactive
+
+Use `render` to compose the avatar onto a button or another trigger without introducing a separate wrapper component. The `lg` avatar and button are both 48×48.
+
+<Story
+ name='Interactive'
+ storyModule={AvatarStories}
+/>
+
 ### Fallback
 
 Once the image fails, the pulse stops and the fallback settles into a plain fill. Nothing is on its way for an entity that has no picture, so its mark holds still rather than claiming to be loading one.

packages/swingset/src/stories/avatar.stories.tsx

@@ -1,6 +1,7 @@
 /** @jsxImportSource @emotion/react */
 import type { AvatarProps } from '@clerk/ui/mosaic/components/avatar';
 import { Avatar } from '@clerk/ui/mosaic/components/avatar';
+import { Icon } from '@clerk/ui/mosaic/components/icon';
 
 import type { StoryMeta } from '@/lib/types';
 
@@ -33,6 +34,7 @@ function knobsAsProps(props: Record<string, unknown>) {
 }
 
 const IMAGE_SRC = 'https://github.com/clerk.png';
+const COLIN_IMAGE_SRC = 'https://avatars.githubusercontent.com/u/51144033?v=4';
 
 export function Primary(props: Record<string, unknown>) {
  return (
@@ -70,6 +72,30 @@ export function Fallback(props: Record<string, unknown>) {
  );
 }
 
+export function Interactive(props: Record<string, unknown>) {
+ return (
+ <Avatar.Root
+ {...knobsAsProps(props)}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Image
+ src={COLIN_IMAGE_SRC}
+ alt='Colin'
+ />
+ <Avatar.Fallback>CL</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>
+ );
+}
+
 export function Sizes(props: Record<string, unknown>) {
  return (
  <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>

packages/ui/src/mosaic/components/avatar/avatar.styles.ts

@@ -8,9 +8,8 @@ const pulse = stylex.keyframes({
 });
 
 export const styles = stylex.create({
- // root — clips its parts to the shape/size; fill comes from the image or fallback
+ // root — sizes and positions its parts; fill comes from the image or fallback
  base: {
- overflow: 'hidden',
  alignItems: 'center',
  aspectRatio: '1 / 1',
  display: 'inline-flex',
@@ -24,6 +23,22 @@ export const styles = stylex.create({
  verticalAlign: 'middle',
  },
 
+ interactive: {
+ background: 'transparent',
+ // An avatar used as a native button has no border shrinking the avatar inside it.
+ borderWidth: 0,
+ outline: {
+ default: 'none',
+ ':focus-visible': `2px solid ${colorVars['--cl-color-primary']}`,
+ },
+ appearance: 'none',
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled, [aria-disabled="true"])': 'not-allowed',
+ },
+ outlineOffset: '2px',
+ },
+
  // Carries the root's radius rather than leaning on the clip alone, so a part that paints its own
  // fill rounds off cleanly instead of showing a corner.
  image: {
@@ -63,6 +78,24 @@ export const styles = stylex.create({
  },
  animationTimingFunction: 'cubic-bezier(0.4, 0, 0.6, 1)',
  },
+
+ icon: {
+ borderColor: colorVars['--cl-color-border'],
+ borderRadius: radiusVars['--cl-radius-full'],
+ borderStyle: 'solid',
+ borderWidth: '1px',
+ overflow: 'hidden',
+ alignItems: 'center',
+ backgroundColor: colorVars['--cl-color-card'],
+ boxSizing: 'border-box',
+ display: 'flex',
+ insetBlockEnd: `calc(${space['2']} * -1)`,
+ insetInlineStart: `calc(${space['1']} * -1)`,
+ justifyContent: 'center',
+ position: 'absolute',
+ height: space['6'],
+ width: space['6'],
+ },
 });
 
 // shape — square shares its radius with Button; circle rounds fully

packages/ui/src/mosaic/components/avatar/avatar.test.tsx

@@ -4,6 +4,7 @@ import { flushSync } from 'react-dom';
 import { createRoot } from 'react-dom/client';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
+import { Icon } from '../icon';
 import { Avatar } from './avatar';
 
 // React reads this off the global object and ships no typing for it.
@@ -280,9 +281,37 @@ describe('Mosaic Avatar', () => {
  expect(avatar).toHaveStyle({ marginTop: '8px' });
  });
 
+ it('composes its root onto another element and renders an icon affordance', () => {
+ const ref = React.createRef<HTMLSpanElement>();
+ render(
+ <Avatar.Root
+ ref={ref}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Fallback>CN</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>,
+ );
+
+ const button = screen.getByRole('button', { name: 'Edit profile picture' });
+ expect(button).toHaveClass('cl-avatar');
+ expect(button).toHaveAttribute('data-size', 'lg');
+ expect(ref.current).toBe(button);
+ expect(button.querySelector('.cl-avatar-icon')).toHaveAttribute('aria-hidden', 'true');
+ });
+
  it('throws when a part is rendered outside <Avatar.Root>', () => {
  const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
  expect(() => render(<Avatar.Fallback>CN</Avatar.Fallback>)).toThrow(/must be rendered inside <Avatar.Root>/);
+ expect(() => render(<Avatar.Icon />)).toThrow(/must be rendered inside <Avatar.Root>/);
  spy.mockRestore();
  });
 });

packages/ui/src/mosaic/components/avatar/avatar.tsx

@@ -1,7 +1,9 @@
+import { useRender } from '@clerk/headless/utils';
 import { useSafeLayoutEffect } from '@clerk/shared/react';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
+import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { reset } from '../reset.styles';
 import { shapes, sizes, styles } from './avatar.styles';
@@ -23,34 +25,34 @@ function useAvatarContext(part: string): AvatarContextValue {
  return context;
 }
 
-export interface AvatarProps extends React.ComponentPropsWithRef<'span'> {
+export interface AvatarProps extends MosaicComponentProps<'span'> {
  shape?: 'circle' | 'square';
  size?: 'fit' | 'lg' | 'md' | 'sm' | 'xs';
 }
 
 const AvatarRoot = React.forwardRef<HTMLSpanElement, AvatarProps>(function MosaicAvatarRoot(
- { shape = 'circle', size = 'md', className, style, children, ...rest },
+ { shape = 'circle', size = 'md', render, className, style, ...rest },
  ref,
 ) {
  const [status, setStatus] = React.useState<ImageLoadingStatus>('idle');
  const value = React.useMemo<AvatarContextValue>(() => ({ status, onStatusChange: setStatus }), [status]);
+ const interactive = Boolean(render);
+ const element = useRender({
+ defaultTagName: 'span',
+ render,
+ ref,
+ props: {
+ ...mergeStyleProps(
+ themeProps('avatar', { shape, size }),
+ stylex.props(reset.base, styles.base, shapes[shape], sizes[size], interactive && styles.interactive),
+ className,
+ style,
+ ),
+ ...rest,
+ },
+ });
 
- return (
- <AvatarContext.Provider value={value}>
- <span
- ref={ref}
- {...mergeStyleProps(
- themeProps('avatar', { shape, size }),
- stylex.props(reset.base, styles.base, shapes[shape], sizes[size]),
- className,
- style,
- )}
- {...rest}
- >
- {children}
- </span>
- </AvatarContext.Provider>
- );
+ return <AvatarContext.Provider value={value}>{element}</AvatarContext.Provider>;
 });
 
 export type AvatarImageProps = React.ComponentPropsWithRef<'img'>;
@@ -152,13 +154,33 @@ const AvatarFallback = React.forwardRef<HTMLSpanElement, AvatarFallbackProps>(fu
  );
 });
 
+export type AvatarIconProps = React.ComponentPropsWithRef<'span'>;
+
+const AvatarIcon = React.forwardRef<HTMLSpanElement, AvatarIconProps>(function MosaicAvatarIcon(
+ { className, style, ...rest },
+ ref,
+) {
+ useAvatarContext('Avatar.Icon');
+
+ return (
+ <span
+ ref={ref}
+ aria-hidden
+ {...mergeStyleProps(themeProps('avatar-icon'), stylex.props(reset.base, styles.icon), className, style)}
+ {...rest}
+ />
+ );
+});
+
 /**
- * Compound avatar. `Avatar.Root` clips and sizes the box; `Avatar.Image` renders
+ * Compound avatar. `Avatar.Root` positions and sizes the box; `Avatar.Image` renders
  * once its source loads; `Avatar.Fallback` holds the space until then, as a blank
- * placeholder that pulses only while an image is actually on its way.
+ * placeholder that pulses only while an image is actually on its way; `Avatar.Icon`
+ * adds an optional corner affordance.
  */
 export const Avatar = {
  Root: AvatarRoot,
  Image: AvatarImage,
  Fallback: AvatarFallback,
+ Icon: AvatarIcon,
 };

packages/ui/src/mosaic/components/avatar/index.ts

@@ -1,2 +1,2 @@
 export { Avatar } from './avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from './avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from './avatar';

packages/ui/src/mosaic/icons/registry.tsx

@@ -9,11 +9,11 @@ type IconComponent = React.ForwardRefExoticComponent<
  * Builds a glyph from its inner `<path>` markup. Glyphs omit `width`/`height` so the `Icon` recipe
  * controls size, and use `currentColor` so they inherit text color. Grow the set on demand.
  */
-function glyph(children: React.ReactNode): IconComponent {
+function glyph(children: React.ReactNode, viewBox = '0 0 16 16'): IconComponent {
  return React.forwardRef<SVGSVGElement, React.ComponentPropsWithoutRef<'svg'>>((props, ref) => (
  <svg
  ref={ref}
- viewBox='0 0 16 16'
+ viewBox={viewBox}
  fill='none'
  xmlns='http://www.w3.org/2000/svg'
  {...props}
@@ -94,6 +94,15 @@ const Plus = glyph(
  />,
 );
 
+const Pen = glyph(
+ <path
+ d='M12.03 3.972a1.59 1.59 0 0 0-2.261 0l-.01.01-5.056 4.89a1.25 1.25 0 0 0-.351.627l-.61 2.747 2.542-.598a1.25 1.25 0 0 0 .59-.325L12.085 6.2c.573-.638.549-1.62-.057-2.228M8.71 2.909a3.09 3.09 0 0 1 4.383.005 3.126 3.126 0 0 1 .06 4.341l-5.228 5.138a2.75 2.75 0 0 1-1.298.715l-3.705.872a.75.75 0 0 1-.904-.893l.87-3.914a2.75 2.75 0 0 1 .772-1.38z'
+ fill='currentColor'
+ fillRule='evenodd'
+ clipRule='evenodd'
+ />,
+);
+
 const LogOut = glyph(
  <path
  d='M6.25 13.25H3.75V2.75H6.25M10.25 10.75L13 8L10.25 5.25M13 8H6.25'
@@ -141,6 +150,7 @@ export const iconRegistry = {
  check: Check,
  close: Close,
  ellipsis: Ellipsis,
+ pen: Pen,
  plus: Plus,
  'log-out': LogOut,
  cog: Cog,

packages/ui/src/mosaic/styles/index.ts

@@ -7,7 +7,7 @@
 export type { MosaicComponentProps, MosaicElementProps } from '../props';
 
 export { Avatar } from '../components/avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from '../components/avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from '../components/avatar';
 export { Badge } from '../components/badge';
 export type { BadgeProps } from '../components/badge';
 export { Button, SubmitButton } from '../components/button';

.changeset/avatar-button-block.md

@@ -0,0 +1,2 @@
+---
+---

.changeset/mosaic-avatar-interactive-styles.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/lib/registry.ts

@@ -3,6 +3,7 @@ import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import {
  Fallback as AvatarFallbackStory,
+ Interactive as AvatarInteractive,
  meta as avatarMeta,
  Primary as AvatarPrimary,
  Shapes as AvatarShapes,
@@ -175,6 +176,7 @@ const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: Car
 const avatarModule: StoryModule = {
  meta: avatarMeta,
  Primary: AvatarPrimary,
+ Interactive: AvatarInteractive,
  Fallback: AvatarFallbackStory,
  Sizes: AvatarSizes,
  Shapes: AvatarShapes,

packages/swingset/src/stories/avatar.mdx

@@ -2,7 +2,7 @@ import * as AvatarStories from './avatar.stories';
 
 # Avatar
 
-Avatar represents a user or entity as an image, falling back to a blank placeholder 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` holds the space until then.
+Avatar represents a user or entity as an image, falling back to a blank placeholder when the image is missing or fails to load. It is a compound component: `Avatar.Root` positions and sizes the box, `Avatar.Image` renders the picture once it loads, `Avatar.Fallback` holds the space until then, and `Avatar.Icon` adds an optional corner affordance.
 
 The fallback still takes children — initials, an icon — but never paints them, so an entity without a picture reads as an absent image rather than as two letters. They stay in the DOM, held in an `avatar-fallback-content` slot that is `visibility: hidden`: out of the page, the accessibility tree, and the tab order together, and overridable by a consumer who wants them back.
 
@@ -37,10 +37,11 @@ import { Avatar } from '@clerk/ui/mosaic/components/avatar';
 
 | Part | Slot (`.cl-*`) | Description |
 | ----------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape.  |
+| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, positioning, and polymorphic rendering. |
 | `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. Carries `data-pending` while an image is still resolving. Optional `delayMs`. |
 | — | `cl-avatar-fallback-content` | Wraps whatever `Avatar.Fallback` was handed, hidden. Override its `visibility` to paint initials or an icon. |
+| `Avatar.Icon` | `cl-avatar-icon` | Renders an optional icon surface over the avatar corner. |
 
 ---
 
@@ -55,6 +56,15 @@ While an image is still resolving, the fallback carries `data-pending` and pulse
  storyModule={AvatarStories}
 />
 
+### Interactive
+
+Use `render` to compose the avatar onto a button or another trigger without introducing a separate wrapper component. The `lg` avatar and button are both 48×48.
+
+<Story
+ name='Interactive'
+ storyModule={AvatarStories}
+/>
+
 ### Fallback
 
 Once the image fails, the pulse stops and the fallback settles into a plain fill. Nothing is on its way for an entity that has no picture, so its mark holds still rather than claiming to be loading one.

packages/swingset/src/stories/avatar.stories.tsx

@@ -1,6 +1,7 @@
 /** @jsxImportSource @emotion/react */
 import type { AvatarProps } from '@clerk/ui/mosaic/components/avatar';
 import { Avatar } from '@clerk/ui/mosaic/components/avatar';
+import { Icon } from '@clerk/ui/mosaic/components/icon';
 
 import type { StoryMeta } from '@/lib/types';
 
@@ -33,6 +34,7 @@ function knobsAsProps(props: Record<string, unknown>) {
 }
 
 const IMAGE_SRC = 'https://github.com/clerk.png';
+const COLIN_IMAGE_SRC = 'https://avatars.githubusercontent.com/u/51144033?v=4';
 
 export function Primary(props: Record<string, unknown>) {
  return (
@@ -70,6 +72,30 @@ export function Fallback(props: Record<string, unknown>) {
  );
 }
 
+export function Interactive(props: Record<string, unknown>) {
+ return (
+ <Avatar.Root
+ {...knobsAsProps(props)}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Image
+ src={COLIN_IMAGE_SRC}
+ alt='Colin'
+ />
+ <Avatar.Fallback>CL</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>
+ );
+}
+
 export function Sizes(props: Record<string, unknown>) {
  return (
  <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>

packages/ui/src/mosaic/components/avatar/avatar.styles.ts

@@ -8,9 +8,8 @@ const pulse = stylex.keyframes({
 });
 
 export const styles = stylex.create({
- // root — clips its parts to the shape/size; fill comes from the image or fallback
+ // root — sizes and positions its parts; fill comes from the image or fallback
  base: {
- overflow: 'hidden',
  alignItems: 'center',
  aspectRatio: '1 / 1',
  display: 'inline-flex',
@@ -24,6 +23,22 @@ export const styles = stylex.create({
  verticalAlign: 'middle',
  },
 
+ interactive: {
+ background: 'transparent',
+ // An avatar used as a native button has no border shrinking the avatar inside it.
+ borderWidth: 0,
+ outline: {
+ default: 'none',
+ ':focus-visible': `2px solid ${colorVars['--cl-color-primary']}`,
+ },
+ appearance: 'none',
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled, [aria-disabled="true"])': 'not-allowed',
+ },
+ outlineOffset: '2px',
+ },
+
  // Carries the root's radius rather than leaning on the clip alone, so a part that paints its own
  // fill rounds off cleanly instead of showing a corner.
  image: {
@@ -63,6 +78,24 @@ export const styles = stylex.create({
  },
  animationTimingFunction: 'cubic-bezier(0.4, 0, 0.6, 1)',
  },
+
+ icon: {
+ borderColor: colorVars['--cl-color-border'],
+ borderRadius: radiusVars['--cl-radius-full'],
+ borderStyle: 'solid',
+ borderWidth: '1px',
+ overflow: 'hidden',
+ alignItems: 'center',
+ backgroundColor: colorVars['--cl-color-card'],
+ boxSizing: 'border-box',
+ display: 'flex',
+ insetBlockEnd: `calc(${space['2']} * -1)`,
+ insetInlineStart: `calc(${space['1']} * -1)`,
+ justifyContent: 'center',
+ position: 'absolute',
+ height: space['6'],
+ width: space['6'],
+ },
 });
 
 // shape — square shares its radius with Button; circle rounds fully

packages/ui/src/mosaic/components/avatar/avatar.test.tsx

@@ -4,6 +4,7 @@ import { flushSync } from 'react-dom';
 import { createRoot } from 'react-dom/client';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
+import { Icon } from '../icon';
 import { Avatar } from './avatar';
 
 // React reads this off the global object and ships no typing for it.
@@ -280,9 +281,37 @@ describe('Mosaic Avatar', () => {
  expect(avatar).toHaveStyle({ marginTop: '8px' });
  });
 
+ it('composes its root onto another element and renders an icon affordance', () => {
+ const ref = React.createRef<HTMLSpanElement>();
+ render(
+ <Avatar.Root
+ ref={ref}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Fallback>CN</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>,
+ );
+
+ const button = screen.getByRole('button', { name: 'Edit profile picture' });
+ expect(button).toHaveClass('cl-avatar');
+ expect(button).toHaveAttribute('data-size', 'lg');
+ expect(ref.current).toBe(button);
+ expect(button.querySelector('.cl-avatar-icon')).toHaveAttribute('aria-hidden', 'true');
+ });
+
  it('throws when a part is rendered outside <Avatar.Root>', () => {
  const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
  expect(() => render(<Avatar.Fallback>CN</Avatar.Fallback>)).toThrow(/must be rendered inside <Avatar.Root>/);
+ expect(() => render(<Avatar.Icon />)).toThrow(/must be rendered inside <Avatar.Root>/);
  spy.mockRestore();
  });
 });

packages/ui/src/mosaic/components/avatar/avatar.tsx

@@ -1,7 +1,9 @@
+import { useRender } from '@clerk/headless/utils';
 import { useSafeLayoutEffect } from '@clerk/shared/react';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
+import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { reset } from '../reset.styles';
 import { shapes, sizes, styles } from './avatar.styles';
@@ -23,34 +25,34 @@ function useAvatarContext(part: string): AvatarContextValue {
  return context;
 }
 
-export interface AvatarProps extends React.ComponentPropsWithRef<'span'> {
+export interface AvatarProps extends MosaicComponentProps<'span'> {
  shape?: 'circle' | 'square';
  size?: 'fit' | 'lg' | 'md' | 'sm' | 'xs';
 }
 
 const AvatarRoot = React.forwardRef<HTMLSpanElement, AvatarProps>(function MosaicAvatarRoot(
- { shape = 'circle', size = 'md', className, style, children, ...rest },
+ { shape = 'circle', size = 'md', render, className, style, ...rest },
  ref,
 ) {
  const [status, setStatus] = React.useState<ImageLoadingStatus>('idle');
  const value = React.useMemo<AvatarContextValue>(() => ({ status, onStatusChange: setStatus }), [status]);
+ const interactive = Boolean(render);
+ const element = useRender({
+ defaultTagName: 'span',
+ render,
+ ref,
+ props: {
+ ...mergeStyleProps(
+ themeProps('avatar', { shape, size }),
+ stylex.props(reset.base, styles.base, shapes[shape], sizes[size], interactive && styles.interactive),
+ className,
+ style,
+ ),
+ ...rest,
+ },
+ });
 
- return (
- <AvatarContext.Provider value={value}>
- <span
- ref={ref}
- {...mergeStyleProps(
- themeProps('avatar', { shape, size }),
- stylex.props(reset.base, styles.base, shapes[shape], sizes[size]),
- className,
- style,
- )}
- {...rest}
- >
- {children}
- </span>
- </AvatarContext.Provider>
- );
+ return <AvatarContext.Provider value={value}>{element}</AvatarContext.Provider>;
 });
 
 export type AvatarImageProps = React.ComponentPropsWithRef<'img'>;
@@ -152,13 +154,33 @@ const AvatarFallback = React.forwardRef<HTMLSpanElement, AvatarFallbackProps>(fu
  );
 });
 
+export type AvatarIconProps = React.ComponentPropsWithRef<'span'>;
+
+const AvatarIcon = React.forwardRef<HTMLSpanElement, AvatarIconProps>(function MosaicAvatarIcon(
+ { className, style, ...rest },
+ ref,
+) {
+ useAvatarContext('Avatar.Icon');
+
+ return (
+ <span
+ ref={ref}
+ aria-hidden
+ {...mergeStyleProps(themeProps('avatar-icon'), stylex.props(reset.base, styles.icon), className, style)}
+ {...rest}
+ />
+ );
+});
+
 /**
- * Compound avatar. `Avatar.Root` clips and sizes the box; `Avatar.Image` renders
+ * Compound avatar. `Avatar.Root` positions and sizes the box; `Avatar.Image` renders
  * once its source loads; `Avatar.Fallback` holds the space until then, as a blank
- * placeholder that pulses only while an image is actually on its way.
+ * placeholder that pulses only while an image is actually on its way; `Avatar.Icon`
+ * adds an optional corner affordance.
  */
 export const Avatar = {
  Root: AvatarRoot,
  Image: AvatarImage,
  Fallback: AvatarFallback,
+ Icon: AvatarIcon,
 };

packages/ui/src/mosaic/components/avatar/index.ts

@@ -1,2 +1,2 @@
 export { Avatar } from './avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from './avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from './avatar';

packages/ui/src/mosaic/icons/registry.tsx

@@ -9,11 +9,11 @@ type IconComponent = React.ForwardRefExoticComponent<
  * Builds a glyph from its inner `<path>` markup. Glyphs omit `width`/`height` so the `Icon` recipe
  * controls size, and use `currentColor` so they inherit text color. Grow the set on demand.
  */
-function glyph(children: React.ReactNode): IconComponent {
+function glyph(children: React.ReactNode, viewBox = '0 0 16 16'): IconComponent {
  return React.forwardRef<SVGSVGElement, React.ComponentPropsWithoutRef<'svg'>>((props, ref) => (
  <svg
  ref={ref}
- viewBox='0 0 16 16'
+ viewBox={viewBox}
  fill='none'
  xmlns='http://www.w3.org/2000/svg'
  {...props}
@@ -94,6 +94,15 @@ const Plus = glyph(
  />,
 );
 
+const Pen = glyph(
+ <path
+ d='M12.03 3.972a1.59 1.59 0 0 0-2.261 0l-.01.01-5.056 4.89a1.25 1.25 0 0 0-.351.627l-.61 2.747 2.542-.598a1.25 1.25 0 0 0 .59-.325L12.085 6.2c.573-.638.549-1.62-.057-2.228M8.71 2.909a3.09 3.09 0 0 1 4.383.005 3.126 3.126 0 0 1 .06 4.341l-5.228 5.138a2.75 2.75 0 0 1-1.298.715l-3.705.872a.75.75 0 0 1-.904-.893l.87-3.914a2.75 2.75 0 0 1 .772-1.38z'
+ fill='currentColor'
+ fillRule='evenodd'
+ clipRule='evenodd'
+ />,
+);
+
 const LogOut = glyph(
  <path
  d='M6.25 13.25H3.75V2.75H6.25M10.25 10.75L13 8L10.25 5.25M13 8H6.25'
@@ -141,6 +150,7 @@ export const iconRegistry = {
  check: Check,
  close: Close,
  ellipsis: Ellipsis,
+ pen: Pen,
  plus: Plus,
  'log-out': LogOut,
  cog: Cog,

packages/ui/src/mosaic/styles/index.ts

@@ -7,7 +7,7 @@
 export type { MosaicComponentProps, MosaicElementProps } from '../props';
 
 export { Avatar } from '../components/avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from '../components/avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from '../components/avatar';
 export { Badge } from '../components/badge';
 export type { BadgeProps } from '../components/badge';
 export { Button, SubmitButton } from '../components/button';

.changeset/avatar-button-block.md

@@ -0,0 +1,2 @@
+---
+---

.changeset/mosaic-avatar-interactive-styles.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/lib/registry.ts

@@ -3,6 +3,7 @@ import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import {
  Fallback as AvatarFallbackStory,
+ Interactive as AvatarInteractive,
  meta as avatarMeta,
  Primary as AvatarPrimary,
  Shapes as AvatarShapes,
@@ -175,6 +176,7 @@ const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: Car
 const avatarModule: StoryModule = {
  meta: avatarMeta,
  Primary: AvatarPrimary,
+ Interactive: AvatarInteractive,
  Fallback: AvatarFallbackStory,
  Sizes: AvatarSizes,
  Shapes: AvatarShapes,

packages/swingset/src/stories/avatar.mdx

@@ -2,7 +2,7 @@ import * as AvatarStories from './avatar.stories';
 
 # Avatar
 
-Avatar represents a user or entity as an image, falling back to a blank placeholder 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` holds the space until then.
+Avatar represents a user or entity as an image, falling back to a blank placeholder when the image is missing or fails to load. It is a compound component: `Avatar.Root` positions and sizes the box, `Avatar.Image` renders the picture once it loads, `Avatar.Fallback` holds the space until then, and `Avatar.Icon` adds an optional corner affordance.
 
 The fallback still takes children — initials, an icon — but never paints them, so an entity without a picture reads as an absent image rather than as two letters. They stay in the DOM, held in an `avatar-fallback-content` slot that is `visibility: hidden`: out of the page, the accessibility tree, and the tab order together, and overridable by a consumer who wants them back.
 
@@ -37,10 +37,11 @@ import { Avatar } from '@clerk/ui/mosaic/components/avatar';
 
 | Part | Slot (`.cl-*`) | Description |
 | ----------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape.  |
+| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, positioning, and polymorphic rendering. |
 | `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. Carries `data-pending` while an image is still resolving. Optional `delayMs`. |
 | — | `cl-avatar-fallback-content` | Wraps whatever `Avatar.Fallback` was handed, hidden. Override its `visibility` to paint initials or an icon. |
+| `Avatar.Icon` | `cl-avatar-icon` | Renders an optional icon surface over the avatar corner. |
 
 ---
 
@@ -55,6 +56,15 @@ While an image is still resolving, the fallback carries `data-pending` and pulse
  storyModule={AvatarStories}
 />
 
+### Interactive
+
+Use `render` to compose the avatar onto a button or another trigger without introducing a separate wrapper component. The `lg` avatar and button are both 48×48.
+
+<Story
+ name='Interactive'
+ storyModule={AvatarStories}
+/>
+
 ### Fallback
 
 Once the image fails, the pulse stops and the fallback settles into a plain fill. Nothing is on its way for an entity that has no picture, so its mark holds still rather than claiming to be loading one.

packages/swingset/src/stories/avatar.stories.tsx

@@ -1,6 +1,7 @@
 /** @jsxImportSource @emotion/react */
 import type { AvatarProps } from '@clerk/ui/mosaic/components/avatar';
 import { Avatar } from '@clerk/ui/mosaic/components/avatar';
+import { Icon } from '@clerk/ui/mosaic/components/icon';
 
 import type { StoryMeta } from '@/lib/types';
 
@@ -33,6 +34,7 @@ function knobsAsProps(props: Record<string, unknown>) {
 }
 
 const IMAGE_SRC = 'https://github.com/clerk.png';
+const COLIN_IMAGE_SRC = 'https://avatars.githubusercontent.com/u/51144033?v=4';
 
 export function Primary(props: Record<string, unknown>) {
  return (
@@ -70,6 +72,30 @@ export function Fallback(props: Record<string, unknown>) {
  );
 }
 
+export function Interactive(props: Record<string, unknown>) {
+ return (
+ <Avatar.Root
+ {...knobsAsProps(props)}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Image
+ src={COLIN_IMAGE_SRC}
+ alt='Colin'
+ />
+ <Avatar.Fallback>CL</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>
+ );
+}
+
 export function Sizes(props: Record<string, unknown>) {
  return (
  <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>

packages/ui/src/mosaic/components/avatar/avatar.styles.ts

@@ -8,9 +8,8 @@ const pulse = stylex.keyframes({
 });
 
 export const styles = stylex.create({
- // root — clips its parts to the shape/size; fill comes from the image or fallback
+ // root — sizes and positions its parts; fill comes from the image or fallback
  base: {
- overflow: 'hidden',
  alignItems: 'center',
  aspectRatio: '1 / 1',
  display: 'inline-flex',
@@ -24,6 +23,22 @@ export const styles = stylex.create({
  verticalAlign: 'middle',
  },
 
+ interactive: {
+ background: 'transparent',
+ // An avatar used as a native button has no border shrinking the avatar inside it.
+ borderWidth: 0,
+ outline: {
+ default: 'none',
+ ':focus-visible': `2px solid ${colorVars['--cl-color-primary']}`,
+ },
+ appearance: 'none',
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled, [aria-disabled="true"])': 'not-allowed',
+ },
+ outlineOffset: '2px',
+ },
+
  // Carries the root's radius rather than leaning on the clip alone, so a part that paints its own
  // fill rounds off cleanly instead of showing a corner.
  image: {
@@ -63,6 +78,24 @@ export const styles = stylex.create({
  },
  animationTimingFunction: 'cubic-bezier(0.4, 0, 0.6, 1)',
  },
+
+ icon: {
+ borderColor: colorVars['--cl-color-border'],
+ borderRadius: radiusVars['--cl-radius-full'],
+ borderStyle: 'solid',
+ borderWidth: '1px',
+ overflow: 'hidden',
+ alignItems: 'center',
+ backgroundColor: colorVars['--cl-color-card'],
+ boxSizing: 'border-box',
+ display: 'flex',
+ insetBlockEnd: `calc(${space['2']} * -1)`,
+ insetInlineStart: `calc(${space['1']} * -1)`,
+ justifyContent: 'center',
+ position: 'absolute',
+ height: space['6'],
+ width: space['6'],
+ },
 });
 
 // shape — square shares its radius with Button; circle rounds fully

packages/ui/src/mosaic/components/avatar/avatar.test.tsx

@@ -4,6 +4,7 @@ import { flushSync } from 'react-dom';
 import { createRoot } from 'react-dom/client';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
+import { Icon } from '../icon';
 import { Avatar } from './avatar';
 
 // React reads this off the global object and ships no typing for it.
@@ -280,9 +281,37 @@ describe('Mosaic Avatar', () => {
  expect(avatar).toHaveStyle({ marginTop: '8px' });
  });
 
+ it('composes its root onto another element and renders an icon affordance', () => {
+ const ref = React.createRef<HTMLSpanElement>();
+ render(
+ <Avatar.Root
+ ref={ref}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Fallback>CN</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>,
+ );
+
+ const button = screen.getByRole('button', { name: 'Edit profile picture' });
+ expect(button).toHaveClass('cl-avatar');
+ expect(button).toHaveAttribute('data-size', 'lg');
+ expect(ref.current).toBe(button);
+ expect(button.querySelector('.cl-avatar-icon')).toHaveAttribute('aria-hidden', 'true');
+ });
+
  it('throws when a part is rendered outside <Avatar.Root>', () => {
  const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
  expect(() => render(<Avatar.Fallback>CN</Avatar.Fallback>)).toThrow(/must be rendered inside <Avatar.Root>/);
+ expect(() => render(<Avatar.Icon />)).toThrow(/must be rendered inside <Avatar.Root>/);
  spy.mockRestore();
  });
 });

packages/ui/src/mosaic/components/avatar/avatar.tsx

@@ -1,7 +1,9 @@
+import { useRender } from '@clerk/headless/utils';
 import { useSafeLayoutEffect } from '@clerk/shared/react';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
+import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { reset } from '../reset.styles';
 import { shapes, sizes, styles } from './avatar.styles';
@@ -23,34 +25,34 @@ function useAvatarContext(part: string): AvatarContextValue {
  return context;
 }
 
-export interface AvatarProps extends React.ComponentPropsWithRef<'span'> {
+export interface AvatarProps extends MosaicComponentProps<'span'> {
  shape?: 'circle' | 'square';
  size?: 'fit' | 'lg' | 'md' | 'sm' | 'xs';
 }
 
 const AvatarRoot = React.forwardRef<HTMLSpanElement, AvatarProps>(function MosaicAvatarRoot(
- { shape = 'circle', size = 'md', className, style, children, ...rest },
+ { shape = 'circle', size = 'md', render, className, style, ...rest },
  ref,
 ) {
  const [status, setStatus] = React.useState<ImageLoadingStatus>('idle');
  const value = React.useMemo<AvatarContextValue>(() => ({ status, onStatusChange: setStatus }), [status]);
+ const interactive = Boolean(render);
+ const element = useRender({
+ defaultTagName: 'span',
+ render,
+ ref,
+ props: {
+ ...mergeStyleProps(
+ themeProps('avatar', { shape, size }),
+ stylex.props(reset.base, styles.base, shapes[shape], sizes[size], interactive && styles.interactive),
+ className,
+ style,
+ ),
+ ...rest,
+ },
+ });
 
- return (
- <AvatarContext.Provider value={value}>
- <span
- ref={ref}
- {...mergeStyleProps(
- themeProps('avatar', { shape, size }),
- stylex.props(reset.base, styles.base, shapes[shape], sizes[size]),
- className,
- style,
- )}
- {...rest}
- >
- {children}
- </span>
- </AvatarContext.Provider>
- );
+ return <AvatarContext.Provider value={value}>{element}</AvatarContext.Provider>;
 });
 
 export type AvatarImageProps = React.ComponentPropsWithRef<'img'>;
@@ -152,13 +154,33 @@ const AvatarFallback = React.forwardRef<HTMLSpanElement, AvatarFallbackProps>(fu
  );
 });
 
+export type AvatarIconProps = React.ComponentPropsWithRef<'span'>;
+
+const AvatarIcon = React.forwardRef<HTMLSpanElement, AvatarIconProps>(function MosaicAvatarIcon(
+ { className, style, ...rest },
+ ref,
+) {
+ useAvatarContext('Avatar.Icon');
+
+ return (
+ <span
+ ref={ref}
+ aria-hidden
+ {...mergeStyleProps(themeProps('avatar-icon'), stylex.props(reset.base, styles.icon), className, style)}
+ {...rest}
+ />
+ );
+});
+
 /**
- * Compound avatar. `Avatar.Root` clips and sizes the box; `Avatar.Image` renders
+ * Compound avatar. `Avatar.Root` positions and sizes the box; `Avatar.Image` renders
  * once its source loads; `Avatar.Fallback` holds the space until then, as a blank
- * placeholder that pulses only while an image is actually on its way.
+ * placeholder that pulses only while an image is actually on its way; `Avatar.Icon`
+ * adds an optional corner affordance.
  */
 export const Avatar = {
  Root: AvatarRoot,
  Image: AvatarImage,
  Fallback: AvatarFallback,
+ Icon: AvatarIcon,
 };

packages/ui/src/mosaic/components/avatar/index.ts

@@ -1,2 +1,2 @@
 export { Avatar } from './avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from './avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from './avatar';

packages/ui/src/mosaic/icons/registry.tsx

@@ -9,11 +9,11 @@ type IconComponent = React.ForwardRefExoticComponent<
  * Builds a glyph from its inner `<path>` markup. Glyphs omit `width`/`height` so the `Icon` recipe
  * controls size, and use `currentColor` so they inherit text color. Grow the set on demand.
  */
-function glyph(children: React.ReactNode): IconComponent {
+function glyph(children: React.ReactNode, viewBox = '0 0 16 16'): IconComponent {
  return React.forwardRef<SVGSVGElement, React.ComponentPropsWithoutRef<'svg'>>((props, ref) => (
  <svg
  ref={ref}
- viewBox='0 0 16 16'
+ viewBox={viewBox}
  fill='none'
  xmlns='http://www.w3.org/2000/svg'
  {...props}
@@ -94,6 +94,15 @@ const Plus = glyph(
  />,
 );
 
+const Pen = glyph(
+ <path
+ d='M12.03 3.972a1.59 1.59 0 0 0-2.261 0l-.01.01-5.056 4.89a1.25 1.25 0 0 0-.351.627l-.61 2.747 2.542-.598a1.25 1.25 0 0 0 .59-.325L12.085 6.2c.573-.638.549-1.62-.057-2.228M8.71 2.909a3.09 3.09 0 0 1 4.383.005 3.126 3.126 0 0 1 .06 4.341l-5.228 5.138a2.75 2.75 0 0 1-1.298.715l-3.705.872a.75.75 0 0 1-.904-.893l.87-3.914a2.75 2.75 0 0 1 .772-1.38z'
+ fill='currentColor'
+ fillRule='evenodd'
+ clipRule='evenodd'
+ />,
+);
+
 const LogOut = glyph(
  <path
  d='M6.25 13.25H3.75V2.75H6.25M10.25 10.75L13 8L10.25 5.25M13 8H6.25'
@@ -141,6 +150,7 @@ export const iconRegistry = {
  check: Check,
  close: Close,
  ellipsis: Ellipsis,
+ pen: Pen,
  plus: Plus,
  'log-out': LogOut,
  cog: Cog,

packages/ui/src/mosaic/styles/index.ts

@@ -7,7 +7,7 @@
 export type { MosaicComponentProps, MosaicElementProps } from '../props';
 
 export { Avatar } from '../components/avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from '../components/avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from '../components/avatar';
 export { Badge } from '../components/badge';
 export type { BadgeProps } from '../components/badge';
 export { Button, SubmitButton } from '../components/button';

.changeset/avatar-button-block.md

@@ -0,0 +1,2 @@
+---
+---

.changeset/mosaic-avatar-interactive-styles.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/lib/registry.ts

@@ -3,6 +3,7 @@ import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import {
  Fallback as AvatarFallbackStory,
+ Interactive as AvatarInteractive,
  meta as avatarMeta,
  Primary as AvatarPrimary,
  Shapes as AvatarShapes,
@@ -175,6 +176,7 @@ const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: Car
 const avatarModule: StoryModule = {
  meta: avatarMeta,
  Primary: AvatarPrimary,
+ Interactive: AvatarInteractive,
  Fallback: AvatarFallbackStory,
  Sizes: AvatarSizes,
  Shapes: AvatarShapes,

packages/swingset/src/stories/avatar.mdx

@@ -2,7 +2,7 @@ import * as AvatarStories from './avatar.stories';
 
 # Avatar
 
-Avatar represents a user or entity as an image, falling back to a blank placeholder 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` holds the space until then.
+Avatar represents a user or entity as an image, falling back to a blank placeholder when the image is missing or fails to load. It is a compound component: `Avatar.Root` positions and sizes the box, `Avatar.Image` renders the picture once it loads, `Avatar.Fallback` holds the space until then, and `Avatar.Icon` adds an optional corner affordance.
 
 The fallback still takes children — initials, an icon — but never paints them, so an entity without a picture reads as an absent image rather than as two letters. They stay in the DOM, held in an `avatar-fallback-content` slot that is `visibility: hidden`: out of the page, the accessibility tree, and the tab order together, and overridable by a consumer who wants them back.
 
@@ -37,10 +37,11 @@ import { Avatar } from '@clerk/ui/mosaic/components/avatar';
 
 | Part | Slot (`.cl-*`) | Description |
 | ----------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape.  |
+| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, positioning, and polymorphic rendering. |
 | `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. Carries `data-pending` while an image is still resolving. Optional `delayMs`. |
 | — | `cl-avatar-fallback-content` | Wraps whatever `Avatar.Fallback` was handed, hidden. Override its `visibility` to paint initials or an icon. |
+| `Avatar.Icon` | `cl-avatar-icon` | Renders an optional icon surface over the avatar corner. |
 
 ---
 
@@ -55,6 +56,15 @@ While an image is still resolving, the fallback carries `data-pending` and pulse
  storyModule={AvatarStories}
 />
 
+### Interactive
+
+Use `render` to compose the avatar onto a button or another trigger without introducing a separate wrapper component. The `lg` avatar and button are both 48×48.
+
+<Story
+ name='Interactive'
+ storyModule={AvatarStories}
+/>
+
 ### Fallback
 
 Once the image fails, the pulse stops and the fallback settles into a plain fill. Nothing is on its way for an entity that has no picture, so its mark holds still rather than claiming to be loading one.

packages/swingset/src/stories/avatar.stories.tsx

@@ -1,6 +1,7 @@
 /** @jsxImportSource @emotion/react */
 import type { AvatarProps } from '@clerk/ui/mosaic/components/avatar';
 import { Avatar } from '@clerk/ui/mosaic/components/avatar';
+import { Icon } from '@clerk/ui/mosaic/components/icon';
 
 import type { StoryMeta } from '@/lib/types';
 
@@ -33,6 +34,7 @@ function knobsAsProps(props: Record<string, unknown>) {
 }
 
 const IMAGE_SRC = 'https://github.com/clerk.png';
+const COLIN_IMAGE_SRC = 'https://avatars.githubusercontent.com/u/51144033?v=4';
 
 export function Primary(props: Record<string, unknown>) {
  return (
@@ -70,6 +72,30 @@ export function Fallback(props: Record<string, unknown>) {
  );
 }
 
+export function Interactive(props: Record<string, unknown>) {
+ return (
+ <Avatar.Root
+ {...knobsAsProps(props)}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Image
+ src={COLIN_IMAGE_SRC}
+ alt='Colin'
+ />
+ <Avatar.Fallback>CL</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>
+ );
+}
+
 export function Sizes(props: Record<string, unknown>) {
  return (
  <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>

packages/ui/src/mosaic/components/avatar/avatar.styles.ts

@@ -8,9 +8,8 @@ const pulse = stylex.keyframes({
 });
 
 export const styles = stylex.create({
- // root — clips its parts to the shape/size; fill comes from the image or fallback
+ // root — sizes and positions its parts; fill comes from the image or fallback
  base: {
- overflow: 'hidden',
  alignItems: 'center',
  aspectRatio: '1 / 1',
  display: 'inline-flex',
@@ -24,6 +23,22 @@ export const styles = stylex.create({
  verticalAlign: 'middle',
  },
 
+ interactive: {
+ background: 'transparent',
+ // An avatar used as a native button has no border shrinking the avatar inside it.
+ borderWidth: 0,
+ outline: {
+ default: 'none',
+ ':focus-visible': `2px solid ${colorVars['--cl-color-primary']}`,
+ },
+ appearance: 'none',
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled, [aria-disabled="true"])': 'not-allowed',
+ },
+ outlineOffset: '2px',
+ },
+
  // Carries the root's radius rather than leaning on the clip alone, so a part that paints its own
  // fill rounds off cleanly instead of showing a corner.
  image: {
@@ -63,6 +78,24 @@ export const styles = stylex.create({
  },
  animationTimingFunction: 'cubic-bezier(0.4, 0, 0.6, 1)',
  },
+
+ icon: {
+ borderColor: colorVars['--cl-color-border'],
+ borderRadius: radiusVars['--cl-radius-full'],
+ borderStyle: 'solid',
+ borderWidth: '1px',
+ overflow: 'hidden',
+ alignItems: 'center',
+ backgroundColor: colorVars['--cl-color-card'],
+ boxSizing: 'border-box',
+ display: 'flex',
+ insetBlockEnd: `calc(${space['2']} * -1)`,
+ insetInlineStart: `calc(${space['1']} * -1)`,
+ justifyContent: 'center',
+ position: 'absolute',
+ height: space['6'],
+ width: space['6'],
+ },
 });
 
 // shape — square shares its radius with Button; circle rounds fully

packages/ui/src/mosaic/components/avatar/avatar.test.tsx

@@ -4,6 +4,7 @@ import { flushSync } from 'react-dom';
 import { createRoot } from 'react-dom/client';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
+import { Icon } from '../icon';
 import { Avatar } from './avatar';
 
 // React reads this off the global object and ships no typing for it.
@@ -280,9 +281,37 @@ describe('Mosaic Avatar', () => {
  expect(avatar).toHaveStyle({ marginTop: '8px' });
  });
 
+ it('composes its root onto another element and renders an icon affordance', () => {
+ const ref = React.createRef<HTMLSpanElement>();
+ render(
+ <Avatar.Root
+ ref={ref}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Fallback>CN</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>,
+ );
+
+ const button = screen.getByRole('button', { name: 'Edit profile picture' });
+ expect(button).toHaveClass('cl-avatar');
+ expect(button).toHaveAttribute('data-size', 'lg');
+ expect(ref.current).toBe(button);
+ expect(button.querySelector('.cl-avatar-icon')).toHaveAttribute('aria-hidden', 'true');
+ });
+
  it('throws when a part is rendered outside <Avatar.Root>', () => {
  const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
  expect(() => render(<Avatar.Fallback>CN</Avatar.Fallback>)).toThrow(/must be rendered inside <Avatar.Root>/);
+ expect(() => render(<Avatar.Icon />)).toThrow(/must be rendered inside <Avatar.Root>/);
  spy.mockRestore();
  });
 });

packages/ui/src/mosaic/components/avatar/avatar.tsx

@@ -1,7 +1,9 @@
+import { useRender } from '@clerk/headless/utils';
 import { useSafeLayoutEffect } from '@clerk/shared/react';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
+import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { reset } from '../reset.styles';
 import { shapes, sizes, styles } from './avatar.styles';
@@ -23,34 +25,34 @@ function useAvatarContext(part: string): AvatarContextValue {
  return context;
 }
 
-export interface AvatarProps extends React.ComponentPropsWithRef<'span'> {
+export interface AvatarProps extends MosaicComponentProps<'span'> {
  shape?: 'circle' | 'square';
  size?: 'fit' | 'lg' | 'md' | 'sm' | 'xs';
 }
 
 const AvatarRoot = React.forwardRef<HTMLSpanElement, AvatarProps>(function MosaicAvatarRoot(
- { shape = 'circle', size = 'md', className, style, children, ...rest },
+ { shape = 'circle', size = 'md', render, className, style, ...rest },
  ref,
 ) {
  const [status, setStatus] = React.useState<ImageLoadingStatus>('idle');
  const value = React.useMemo<AvatarContextValue>(() => ({ status, onStatusChange: setStatus }), [status]);
+ const interactive = Boolean(render);
+ const element = useRender({
+ defaultTagName: 'span',
+ render,
+ ref,
+ props: {
+ ...mergeStyleProps(
+ themeProps('avatar', { shape, size }),
+ stylex.props(reset.base, styles.base, shapes[shape], sizes[size], interactive && styles.interactive),
+ className,
+ style,
+ ),
+ ...rest,
+ },
+ });
 
- return (
- <AvatarContext.Provider value={value}>
- <span
- ref={ref}
- {...mergeStyleProps(
- themeProps('avatar', { shape, size }),
- stylex.props(reset.base, styles.base, shapes[shape], sizes[size]),
- className,
- style,
- )}
- {...rest}
- >
- {children}
- </span>
- </AvatarContext.Provider>
- );
+ return <AvatarContext.Provider value={value}>{element}</AvatarContext.Provider>;
 });
 
 export type AvatarImageProps = React.ComponentPropsWithRef<'img'>;
@@ -152,13 +154,33 @@ const AvatarFallback = React.forwardRef<HTMLSpanElement, AvatarFallbackProps>(fu
  );
 });
 
+export type AvatarIconProps = React.ComponentPropsWithRef<'span'>;
+
+const AvatarIcon = React.forwardRef<HTMLSpanElement, AvatarIconProps>(function MosaicAvatarIcon(
+ { className, style, ...rest },
+ ref,
+) {
+ useAvatarContext('Avatar.Icon');
+
+ return (
+ <span
+ ref={ref}
+ aria-hidden
+ {...mergeStyleProps(themeProps('avatar-icon'), stylex.props(reset.base, styles.icon), className, style)}
+ {...rest}
+ />
+ );
+});
+
 /**
- * Compound avatar. `Avatar.Root` clips and sizes the box; `Avatar.Image` renders
+ * Compound avatar. `Avatar.Root` positions and sizes the box; `Avatar.Image` renders
  * once its source loads; `Avatar.Fallback` holds the space until then, as a blank
- * placeholder that pulses only while an image is actually on its way.
+ * placeholder that pulses only while an image is actually on its way; `Avatar.Icon`
+ * adds an optional corner affordance.
  */
 export const Avatar = {
  Root: AvatarRoot,
  Image: AvatarImage,
  Fallback: AvatarFallback,
+ Icon: AvatarIcon,
 };

packages/ui/src/mosaic/components/avatar/index.ts

@@ -1,2 +1,2 @@
 export { Avatar } from './avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from './avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from './avatar';

packages/ui/src/mosaic/icons/registry.tsx

@@ -9,11 +9,11 @@ type IconComponent = React.ForwardRefExoticComponent<
  * Builds a glyph from its inner `<path>` markup. Glyphs omit `width`/`height` so the `Icon` recipe
  * controls size, and use `currentColor` so they inherit text color. Grow the set on demand.
  */
-function glyph(children: React.ReactNode): IconComponent {
+function glyph(children: React.ReactNode, viewBox = '0 0 16 16'): IconComponent {
  return React.forwardRef<SVGSVGElement, React.ComponentPropsWithoutRef<'svg'>>((props, ref) => (
  <svg
  ref={ref}
- viewBox='0 0 16 16'
+ viewBox={viewBox}
  fill='none'
  xmlns='http://www.w3.org/2000/svg'
  {...props}
@@ -94,6 +94,15 @@ const Plus = glyph(
  />,
 );
 
+const Pen = glyph(
+ <path
+ d='M12.03 3.972a1.59 1.59 0 0 0-2.261 0l-.01.01-5.056 4.89a1.25 1.25 0 0 0-.351.627l-.61 2.747 2.542-.598a1.25 1.25 0 0 0 .59-.325L12.085 6.2c.573-.638.549-1.62-.057-2.228M8.71 2.909a3.09 3.09 0 0 1 4.383.005 3.126 3.126 0 0 1 .06 4.341l-5.228 5.138a2.75 2.75 0 0 1-1.298.715l-3.705.872a.75.75 0 0 1-.904-.893l.87-3.914a2.75 2.75 0 0 1 .772-1.38z'
+ fill='currentColor'
+ fillRule='evenodd'
+ clipRule='evenodd'
+ />,
+);
+
 const LogOut = glyph(
  <path
  d='M6.25 13.25H3.75V2.75H6.25M10.25 10.75L13 8L10.25 5.25M13 8H6.25'
@@ -141,6 +150,7 @@ export const iconRegistry = {
  check: Check,
  close: Close,
  ellipsis: Ellipsis,
+ pen: Pen,
  plus: Plus,
  'log-out': LogOut,
  cog: Cog,

packages/ui/src/mosaic/styles/index.ts

@@ -7,7 +7,7 @@
 export type { MosaicComponentProps, MosaicElementProps } from '../props';
 
 export { Avatar } from '../components/avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from '../components/avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from '../components/avatar';
 export { Badge } from '../components/badge';
 export type { BadgeProps } from '../components/badge';
 export { Button, SubmitButton } from '../components/button';

.changeset/avatar-button-block.md

@@ -0,0 +1,2 @@
+---
+---

.changeset/mosaic-avatar-interactive-styles.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/lib/registry.ts

@@ -3,6 +3,7 @@ import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import {
  Fallback as AvatarFallbackStory,
+ Interactive as AvatarInteractive,
  meta as avatarMeta,
  Primary as AvatarPrimary,
  Shapes as AvatarShapes,
@@ -175,6 +176,7 @@ const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: Car
 const avatarModule: StoryModule = {
  meta: avatarMeta,
  Primary: AvatarPrimary,
+ Interactive: AvatarInteractive,
  Fallback: AvatarFallbackStory,
  Sizes: AvatarSizes,
  Shapes: AvatarShapes,

packages/swingset/src/stories/avatar.mdx

@@ -2,7 +2,7 @@ import * as AvatarStories from './avatar.stories';
 
 # Avatar
 
-Avatar represents a user or entity as an image, falling back to a blank placeholder 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` holds the space until then.
+Avatar represents a user or entity as an image, falling back to a blank placeholder when the image is missing or fails to load. It is a compound component: `Avatar.Root` positions and sizes the box, `Avatar.Image` renders the picture once it loads, `Avatar.Fallback` holds the space until then, and `Avatar.Icon` adds an optional corner affordance.
 
 The fallback still takes children — initials, an icon — but never paints them, so an entity without a picture reads as an absent image rather than as two letters. They stay in the DOM, held in an `avatar-fallback-content` slot that is `visibility: hidden`: out of the page, the accessibility tree, and the tab order together, and overridable by a consumer who wants them back.
 
@@ -37,10 +37,11 @@ import { Avatar } from '@clerk/ui/mosaic/components/avatar';
 
 | Part | Slot (`.cl-*`) | Description |
 | ----------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape.  |
+| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, positioning, and polymorphic rendering. |
 | `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. Carries `data-pending` while an image is still resolving. Optional `delayMs`. |
 | — | `cl-avatar-fallback-content` | Wraps whatever `Avatar.Fallback` was handed, hidden. Override its `visibility` to paint initials or an icon. |
+| `Avatar.Icon` | `cl-avatar-icon` | Renders an optional icon surface over the avatar corner. |
 
 ---
 
@@ -55,6 +56,15 @@ While an image is still resolving, the fallback carries `data-pending` and pulse
  storyModule={AvatarStories}
 />
 
+### Interactive
+
+Use `render` to compose the avatar onto a button or another trigger without introducing a separate wrapper component. The `lg` avatar and button are both 48×48.
+
+<Story
+ name='Interactive'
+ storyModule={AvatarStories}
+/>
+
 ### Fallback
 
 Once the image fails, the pulse stops and the fallback settles into a plain fill. Nothing is on its way for an entity that has no picture, so its mark holds still rather than claiming to be loading one.

packages/swingset/src/stories/avatar.stories.tsx

@@ -1,6 +1,7 @@
 /** @jsxImportSource @emotion/react */
 import type { AvatarProps } from '@clerk/ui/mosaic/components/avatar';
 import { Avatar } from '@clerk/ui/mosaic/components/avatar';
+import { Icon } from '@clerk/ui/mosaic/components/icon';
 
 import type { StoryMeta } from '@/lib/types';
 
@@ -33,6 +34,7 @@ function knobsAsProps(props: Record<string, unknown>) {
 }
 
 const IMAGE_SRC = 'https://github.com/clerk.png';
+const COLIN_IMAGE_SRC = 'https://avatars.githubusercontent.com/u/51144033?v=4';
 
 export function Primary(props: Record<string, unknown>) {
  return (
@@ -70,6 +72,30 @@ export function Fallback(props: Record<string, unknown>) {
  );
 }
 
+export function Interactive(props: Record<string, unknown>) {
+ return (
+ <Avatar.Root
+ {...knobsAsProps(props)}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Image
+ src={COLIN_IMAGE_SRC}
+ alt='Colin'
+ />
+ <Avatar.Fallback>CL</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>
+ );
+}
+
 export function Sizes(props: Record<string, unknown>) {
  return (
  <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>

packages/ui/src/mosaic/components/avatar/avatar.styles.ts

@@ -8,9 +8,8 @@ const pulse = stylex.keyframes({
 });
 
 export const styles = stylex.create({
- // root — clips its parts to the shape/size; fill comes from the image or fallback
+ // root — sizes and positions its parts; fill comes from the image or fallback
  base: {
- overflow: 'hidden',
  alignItems: 'center',
  aspectRatio: '1 / 1',
  display: 'inline-flex',
@@ -24,6 +23,22 @@ export const styles = stylex.create({
  verticalAlign: 'middle',
  },
 
+ interactive: {
+ background: 'transparent',
+ // An avatar used as a native button has no border shrinking the avatar inside it.
+ borderWidth: 0,
+ outline: {
+ default: 'none',
+ ':focus-visible': `2px solid ${colorVars['--cl-color-primary']}`,
+ },
+ appearance: 'none',
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled, [aria-disabled="true"])': 'not-allowed',
+ },
+ outlineOffset: '2px',
+ },
+
  // Carries the root's radius rather than leaning on the clip alone, so a part that paints its own
  // fill rounds off cleanly instead of showing a corner.
  image: {
@@ -63,6 +78,24 @@ export const styles = stylex.create({
  },
  animationTimingFunction: 'cubic-bezier(0.4, 0, 0.6, 1)',
  },
+
+ icon: {
+ borderColor: colorVars['--cl-color-border'],
+ borderRadius: radiusVars['--cl-radius-full'],
+ borderStyle: 'solid',
+ borderWidth: '1px',
+ overflow: 'hidden',
+ alignItems: 'center',
+ backgroundColor: colorVars['--cl-color-card'],
+ boxSizing: 'border-box',
+ display: 'flex',
+ insetBlockEnd: `calc(${space['2']} * -1)`,
+ insetInlineStart: `calc(${space['1']} * -1)`,
+ justifyContent: 'center',
+ position: 'absolute',
+ height: space['6'],
+ width: space['6'],
+ },
 });
 
 // shape — square shares its radius with Button; circle rounds fully

packages/ui/src/mosaic/components/avatar/avatar.test.tsx

@@ -4,6 +4,7 @@ import { flushSync } from 'react-dom';
 import { createRoot } from 'react-dom/client';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
+import { Icon } from '../icon';
 import { Avatar } from './avatar';
 
 // React reads this off the global object and ships no typing for it.
@@ -280,9 +281,37 @@ describe('Mosaic Avatar', () => {
  expect(avatar).toHaveStyle({ marginTop: '8px' });
  });
 
+ it('composes its root onto another element and renders an icon affordance', () => {
+ const ref = React.createRef<HTMLSpanElement>();
+ render(
+ <Avatar.Root
+ ref={ref}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Fallback>CN</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>,
+ );
+
+ const button = screen.getByRole('button', { name: 'Edit profile picture' });
+ expect(button).toHaveClass('cl-avatar');
+ expect(button).toHaveAttribute('data-size', 'lg');
+ expect(ref.current).toBe(button);
+ expect(button.querySelector('.cl-avatar-icon')).toHaveAttribute('aria-hidden', 'true');
+ });
+
  it('throws when a part is rendered outside <Avatar.Root>', () => {
  const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
  expect(() => render(<Avatar.Fallback>CN</Avatar.Fallback>)).toThrow(/must be rendered inside <Avatar.Root>/);
+ expect(() => render(<Avatar.Icon />)).toThrow(/must be rendered inside <Avatar.Root>/);
  spy.mockRestore();
  });
 });

packages/ui/src/mosaic/components/avatar/avatar.tsx

@@ -1,7 +1,9 @@
+import { useRender } from '@clerk/headless/utils';
 import { useSafeLayoutEffect } from '@clerk/shared/react';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
+import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { reset } from '../reset.styles';
 import { shapes, sizes, styles } from './avatar.styles';
@@ -23,34 +25,34 @@ function useAvatarContext(part: string): AvatarContextValue {
  return context;
 }
 
-export interface AvatarProps extends React.ComponentPropsWithRef<'span'> {
+export interface AvatarProps extends MosaicComponentProps<'span'> {
  shape?: 'circle' | 'square';
  size?: 'fit' | 'lg' | 'md' | 'sm' | 'xs';
 }
 
 const AvatarRoot = React.forwardRef<HTMLSpanElement, AvatarProps>(function MosaicAvatarRoot(
- { shape = 'circle', size = 'md', className, style, children, ...rest },
+ { shape = 'circle', size = 'md', render, className, style, ...rest },
  ref,
 ) {
  const [status, setStatus] = React.useState<ImageLoadingStatus>('idle');
  const value = React.useMemo<AvatarContextValue>(() => ({ status, onStatusChange: setStatus }), [status]);
+ const interactive = Boolean(render);
+ const element = useRender({
+ defaultTagName: 'span',
+ render,
+ ref,
+ props: {
+ ...mergeStyleProps(
+ themeProps('avatar', { shape, size }),
+ stylex.props(reset.base, styles.base, shapes[shape], sizes[size], interactive && styles.interactive),
+ className,
+ style,
+ ),
+ ...rest,
+ },
+ });
 
- return (
- <AvatarContext.Provider value={value}>
- <span
- ref={ref}
- {...mergeStyleProps(
- themeProps('avatar', { shape, size }),
- stylex.props(reset.base, styles.base, shapes[shape], sizes[size]),
- className,
- style,
- )}
- {...rest}
- >
- {children}
- </span>
- </AvatarContext.Provider>
- );
+ return <AvatarContext.Provider value={value}>{element}</AvatarContext.Provider>;
 });
 
 export type AvatarImageProps = React.ComponentPropsWithRef<'img'>;
@@ -152,13 +154,33 @@ const AvatarFallback = React.forwardRef<HTMLSpanElement, AvatarFallbackProps>(fu
  );
 });
 
+export type AvatarIconProps = React.ComponentPropsWithRef<'span'>;
+
+const AvatarIcon = React.forwardRef<HTMLSpanElement, AvatarIconProps>(function MosaicAvatarIcon(
+ { className, style, ...rest },
+ ref,
+) {
+ useAvatarContext('Avatar.Icon');
+
+ return (
+ <span
+ ref={ref}
+ aria-hidden
+ {...mergeStyleProps(themeProps('avatar-icon'), stylex.props(reset.base, styles.icon), className, style)}
+ {...rest}
+ />
+ );
+});
+
 /**
- * Compound avatar. `Avatar.Root` clips and sizes the box; `Avatar.Image` renders
+ * Compound avatar. `Avatar.Root` positions and sizes the box; `Avatar.Image` renders
  * once its source loads; `Avatar.Fallback` holds the space until then, as a blank
- * placeholder that pulses only while an image is actually on its way.
+ * placeholder that pulses only while an image is actually on its way; `Avatar.Icon`
+ * adds an optional corner affordance.
  */
 export const Avatar = {
  Root: AvatarRoot,
  Image: AvatarImage,
  Fallback: AvatarFallback,
+ Icon: AvatarIcon,
 };

packages/ui/src/mosaic/components/avatar/index.ts

@@ -1,2 +1,2 @@
 export { Avatar } from './avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from './avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from './avatar';

packages/ui/src/mosaic/icons/registry.tsx

@@ -9,11 +9,11 @@ type IconComponent = React.ForwardRefExoticComponent<
  * Builds a glyph from its inner `<path>` markup. Glyphs omit `width`/`height` so the `Icon` recipe
  * controls size, and use `currentColor` so they inherit text color. Grow the set on demand.
  */
-function glyph(children: React.ReactNode): IconComponent {
+function glyph(children: React.ReactNode, viewBox = '0 0 16 16'): IconComponent {
  return React.forwardRef<SVGSVGElement, React.ComponentPropsWithoutRef<'svg'>>((props, ref) => (
  <svg
  ref={ref}
- viewBox='0 0 16 16'
+ viewBox={viewBox}
  fill='none'
  xmlns='http://www.w3.org/2000/svg'
  {...props}
@@ -94,6 +94,15 @@ const Plus = glyph(
  />,
 );
 
+const Pen = glyph(
+ <path
+ d='M12.03 3.972a1.59 1.59 0 0 0-2.261 0l-.01.01-5.056 4.89a1.25 1.25 0 0 0-.351.627l-.61 2.747 2.542-.598a1.25 1.25 0 0 0 .59-.325L12.085 6.2c.573-.638.549-1.62-.057-2.228M8.71 2.909a3.09 3.09 0 0 1 4.383.005 3.126 3.126 0 0 1 .06 4.341l-5.228 5.138a2.75 2.75 0 0 1-1.298.715l-3.705.872a.75.75 0 0 1-.904-.893l.87-3.914a2.75 2.75 0 0 1 .772-1.38z'
+ fill='currentColor'
+ fillRule='evenodd'
+ clipRule='evenodd'
+ />,
+);
+
 const LogOut = glyph(
  <path
  d='M6.25 13.25H3.75V2.75H6.25M10.25 10.75L13 8L10.25 5.25M13 8H6.25'
@@ -141,6 +150,7 @@ export const iconRegistry = {
  check: Check,
  close: Close,
  ellipsis: Ellipsis,
+ pen: Pen,
  plus: Plus,
  'log-out': LogOut,
  cog: Cog,

packages/ui/src/mosaic/styles/index.ts

@@ -7,7 +7,7 @@
 export type { MosaicComponentProps, MosaicElementProps } from '../props';
 
 export { Avatar } from '../components/avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from '../components/avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from '../components/avatar';
 export { Badge } from '../components/badge';
 export type { BadgeProps } from '../components/badge';
 export { Button, SubmitButton } from '../components/button';

.changeset/avatar-button-block.md

@@ -0,0 +1,2 @@
+---
+---

.changeset/mosaic-avatar-interactive-styles.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/lib/registry.ts

@@ -3,6 +3,7 @@ import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import {
  Fallback as AvatarFallbackStory,
+ Interactive as AvatarInteractive,
  meta as avatarMeta,
  Primary as AvatarPrimary,
  Shapes as AvatarShapes,
@@ -175,6 +176,7 @@ const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: Car
 const avatarModule: StoryModule = {
  meta: avatarMeta,
  Primary: AvatarPrimary,
+ Interactive: AvatarInteractive,
  Fallback: AvatarFallbackStory,
  Sizes: AvatarSizes,
  Shapes: AvatarShapes,

packages/swingset/src/stories/avatar.mdx

@@ -2,7 +2,7 @@ import * as AvatarStories from './avatar.stories';
 
 # Avatar
 
-Avatar represents a user or entity as an image, falling back to a blank placeholder 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` holds the space until then.
+Avatar represents a user or entity as an image, falling back to a blank placeholder when the image is missing or fails to load. It is a compound component: `Avatar.Root` positions and sizes the box, `Avatar.Image` renders the picture once it loads, `Avatar.Fallback` holds the space until then, and `Avatar.Icon` adds an optional corner affordance.
 
 The fallback still takes children — initials, an icon — but never paints them, so an entity without a picture reads as an absent image rather than as two letters. They stay in the DOM, held in an `avatar-fallback-content` slot that is `visibility: hidden`: out of the page, the accessibility tree, and the tab order together, and overridable by a consumer who wants them back.
 
@@ -37,10 +37,11 @@ import { Avatar } from '@clerk/ui/mosaic/components/avatar';
 
 | Part | Slot (`.cl-*`) | Description |
 | ----------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape.  |
+| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, positioning, and polymorphic rendering. |
 | `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. Carries `data-pending` while an image is still resolving. Optional `delayMs`. |
 | — | `cl-avatar-fallback-content` | Wraps whatever `Avatar.Fallback` was handed, hidden. Override its `visibility` to paint initials or an icon. |
+| `Avatar.Icon` | `cl-avatar-icon` | Renders an optional icon surface over the avatar corner. |
 
 ---
 
@@ -55,6 +56,15 @@ While an image is still resolving, the fallback carries `data-pending` and pulse
  storyModule={AvatarStories}
 />
 
+### Interactive
+
+Use `render` to compose the avatar onto a button or another trigger without introducing a separate wrapper component. The `lg` avatar and button are both 48×48.
+
+<Story
+ name='Interactive'
+ storyModule={AvatarStories}
+/>
+
 ### Fallback
 
 Once the image fails, the pulse stops and the fallback settles into a plain fill. Nothing is on its way for an entity that has no picture, so its mark holds still rather than claiming to be loading one.

packages/swingset/src/stories/avatar.stories.tsx

@@ -1,6 +1,7 @@
 /** @jsxImportSource @emotion/react */
 import type { AvatarProps } from '@clerk/ui/mosaic/components/avatar';
 import { Avatar } from '@clerk/ui/mosaic/components/avatar';
+import { Icon } from '@clerk/ui/mosaic/components/icon';
 
 import type { StoryMeta } from '@/lib/types';
 
@@ -33,6 +34,7 @@ function knobsAsProps(props: Record<string, unknown>) {
 }
 
 const IMAGE_SRC = 'https://github.com/clerk.png';
+const COLIN_IMAGE_SRC = 'https://avatars.githubusercontent.com/u/51144033?v=4';
 
 export function Primary(props: Record<string, unknown>) {
  return (
@@ -70,6 +72,30 @@ export function Fallback(props: Record<string, unknown>) {
  );
 }
 
+export function Interactive(props: Record<string, unknown>) {
+ return (
+ <Avatar.Root
+ {...knobsAsProps(props)}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Image
+ src={COLIN_IMAGE_SRC}
+ alt='Colin'
+ />
+ <Avatar.Fallback>CL</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>
+ );
+}
+
 export function Sizes(props: Record<string, unknown>) {
  return (
  <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>

packages/ui/src/mosaic/components/avatar/avatar.styles.ts

@@ -8,9 +8,8 @@ const pulse = stylex.keyframes({
 });
 
 export const styles = stylex.create({
- // root — clips its parts to the shape/size; fill comes from the image or fallback
+ // root — sizes and positions its parts; fill comes from the image or fallback
  base: {
- overflow: 'hidden',
  alignItems: 'center',
  aspectRatio: '1 / 1',
  display: 'inline-flex',
@@ -24,6 +23,22 @@ export const styles = stylex.create({
  verticalAlign: 'middle',
  },
 
+ interactive: {
+ background: 'transparent',
+ // An avatar used as a native button has no border shrinking the avatar inside it.
+ borderWidth: 0,
+ outline: {
+ default: 'none',
+ ':focus-visible': `2px solid ${colorVars['--cl-color-primary']}`,
+ },
+ appearance: 'none',
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled, [aria-disabled="true"])': 'not-allowed',
+ },
+ outlineOffset: '2px',
+ },
+
  // Carries the root's radius rather than leaning on the clip alone, so a part that paints its own
  // fill rounds off cleanly instead of showing a corner.
  image: {
@@ -63,6 +78,24 @@ export const styles = stylex.create({
  },
  animationTimingFunction: 'cubic-bezier(0.4, 0, 0.6, 1)',
  },
+
+ icon: {
+ borderColor: colorVars['--cl-color-border'],
+ borderRadius: radiusVars['--cl-radius-full'],
+ borderStyle: 'solid',
+ borderWidth: '1px',
+ overflow: 'hidden',
+ alignItems: 'center',
+ backgroundColor: colorVars['--cl-color-card'],
+ boxSizing: 'border-box',
+ display: 'flex',
+ insetBlockEnd: `calc(${space['2']} * -1)`,
+ insetInlineStart: `calc(${space['1']} * -1)`,
+ justifyContent: 'center',
+ position: 'absolute',
+ height: space['6'],
+ width: space['6'],
+ },
 });
 
 // shape — square shares its radius with Button; circle rounds fully

packages/ui/src/mosaic/components/avatar/avatar.test.tsx

@@ -4,6 +4,7 @@ import { flushSync } from 'react-dom';
 import { createRoot } from 'react-dom/client';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
+import { Icon } from '../icon';
 import { Avatar } from './avatar';
 
 // React reads this off the global object and ships no typing for it.
@@ -280,9 +281,37 @@ describe('Mosaic Avatar', () => {
  expect(avatar).toHaveStyle({ marginTop: '8px' });
  });
 
+ it('composes its root onto another element and renders an icon affordance', () => {
+ const ref = React.createRef<HTMLSpanElement>();
+ render(
+ <Avatar.Root
+ ref={ref}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Fallback>CN</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>,
+ );
+
+ const button = screen.getByRole('button', { name: 'Edit profile picture' });
+ expect(button).toHaveClass('cl-avatar');
+ expect(button).toHaveAttribute('data-size', 'lg');
+ expect(ref.current).toBe(button);
+ expect(button.querySelector('.cl-avatar-icon')).toHaveAttribute('aria-hidden', 'true');
+ });
+
  it('throws when a part is rendered outside <Avatar.Root>', () => {
  const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
  expect(() => render(<Avatar.Fallback>CN</Avatar.Fallback>)).toThrow(/must be rendered inside <Avatar.Root>/);
+ expect(() => render(<Avatar.Icon />)).toThrow(/must be rendered inside <Avatar.Root>/);
  spy.mockRestore();
  });
 });

packages/ui/src/mosaic/components/avatar/avatar.tsx

@@ -1,7 +1,9 @@
+import { useRender } from '@clerk/headless/utils';
 import { useSafeLayoutEffect } from '@clerk/shared/react';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
+import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { reset } from '../reset.styles';
 import { shapes, sizes, styles } from './avatar.styles';
@@ -23,34 +25,34 @@ function useAvatarContext(part: string): AvatarContextValue {
  return context;
 }
 
-export interface AvatarProps extends React.ComponentPropsWithRef<'span'> {
+export interface AvatarProps extends MosaicComponentProps<'span'> {
  shape?: 'circle' | 'square';
  size?: 'fit' | 'lg' | 'md' | 'sm' | 'xs';
 }
 
 const AvatarRoot = React.forwardRef<HTMLSpanElement, AvatarProps>(function MosaicAvatarRoot(
- { shape = 'circle', size = 'md', className, style, children, ...rest },
+ { shape = 'circle', size = 'md', render, className, style, ...rest },
  ref,
 ) {
  const [status, setStatus] = React.useState<ImageLoadingStatus>('idle');
  const value = React.useMemo<AvatarContextValue>(() => ({ status, onStatusChange: setStatus }), [status]);
+ const interactive = Boolean(render);
+ const element = useRender({
+ defaultTagName: 'span',
+ render,
+ ref,
+ props: {
+ ...mergeStyleProps(
+ themeProps('avatar', { shape, size }),
+ stylex.props(reset.base, styles.base, shapes[shape], sizes[size], interactive && styles.interactive),
+ className,
+ style,
+ ),
+ ...rest,
+ },
+ });
 
- return (
- <AvatarContext.Provider value={value}>
- <span
- ref={ref}
- {...mergeStyleProps(
- themeProps('avatar', { shape, size }),
- stylex.props(reset.base, styles.base, shapes[shape], sizes[size]),
- className,
- style,
- )}
- {...rest}
- >
- {children}
- </span>
- </AvatarContext.Provider>
- );
+ return <AvatarContext.Provider value={value}>{element}</AvatarContext.Provider>;
 });
 
 export type AvatarImageProps = React.ComponentPropsWithRef<'img'>;
@@ -152,13 +154,33 @@ const AvatarFallback = React.forwardRef<HTMLSpanElement, AvatarFallbackProps>(fu
  );
 });
 
+export type AvatarIconProps = React.ComponentPropsWithRef<'span'>;
+
+const AvatarIcon = React.forwardRef<HTMLSpanElement, AvatarIconProps>(function MosaicAvatarIcon(
+ { className, style, ...rest },
+ ref,
+) {
+ useAvatarContext('Avatar.Icon');
+
+ return (
+ <span
+ ref={ref}
+ aria-hidden
+ {...mergeStyleProps(themeProps('avatar-icon'), stylex.props(reset.base, styles.icon), className, style)}
+ {...rest}
+ />
+ );
+});
+
 /**
- * Compound avatar. `Avatar.Root` clips and sizes the box; `Avatar.Image` renders
+ * Compound avatar. `Avatar.Root` positions and sizes the box; `Avatar.Image` renders
  * once its source loads; `Avatar.Fallback` holds the space until then, as a blank
- * placeholder that pulses only while an image is actually on its way.
+ * placeholder that pulses only while an image is actually on its way; `Avatar.Icon`
+ * adds an optional corner affordance.
  */
 export const Avatar = {
  Root: AvatarRoot,
  Image: AvatarImage,
  Fallback: AvatarFallback,
+ Icon: AvatarIcon,
 };

packages/ui/src/mosaic/components/avatar/index.ts

@@ -1,2 +1,2 @@
 export { Avatar } from './avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from './avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from './avatar';

packages/ui/src/mosaic/icons/registry.tsx

@@ -9,11 +9,11 @@ type IconComponent = React.ForwardRefExoticComponent<
  * Builds a glyph from its inner `<path>` markup. Glyphs omit `width`/`height` so the `Icon` recipe
  * controls size, and use `currentColor` so they inherit text color. Grow the set on demand.
  */
-function glyph(children: React.ReactNode): IconComponent {
+function glyph(children: React.ReactNode, viewBox = '0 0 16 16'): IconComponent {
  return React.forwardRef<SVGSVGElement, React.ComponentPropsWithoutRef<'svg'>>((props, ref) => (
  <svg
  ref={ref}
- viewBox='0 0 16 16'
+ viewBox={viewBox}
  fill='none'
  xmlns='http://www.w3.org/2000/svg'
  {...props}
@@ -94,6 +94,15 @@ const Plus = glyph(
  />,
 );
 
+const Pen = glyph(
+ <path
+ d='M12.03 3.972a1.59 1.59 0 0 0-2.261 0l-.01.01-5.056 4.89a1.25 1.25 0 0 0-.351.627l-.61 2.747 2.542-.598a1.25 1.25 0 0 0 .59-.325L12.085 6.2c.573-.638.549-1.62-.057-2.228M8.71 2.909a3.09 3.09 0 0 1 4.383.005 3.126 3.126 0 0 1 .06 4.341l-5.228 5.138a2.75 2.75 0 0 1-1.298.715l-3.705.872a.75.75 0 0 1-.904-.893l.87-3.914a2.75 2.75 0 0 1 .772-1.38z'
+ fill='currentColor'
+ fillRule='evenodd'
+ clipRule='evenodd'
+ />,
+);
+
 const LogOut = glyph(
  <path
  d='M6.25 13.25H3.75V2.75H6.25M10.25 10.75L13 8L10.25 5.25M13 8H6.25'
@@ -141,6 +150,7 @@ export const iconRegistry = {
  check: Check,
  close: Close,
  ellipsis: Ellipsis,
+ pen: Pen,
  plus: Plus,
  'log-out': LogOut,
  cog: Cog,

packages/ui/src/mosaic/styles/index.ts

@@ -7,7 +7,7 @@
 export type { MosaicComponentProps, MosaicElementProps } from '../props';
 
 export { Avatar } from '../components/avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from '../components/avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from '../components/avatar';
 export { Badge } from '../components/badge';
 export type { BadgeProps } from '../components/badge';
 export { Button, SubmitButton } from '../components/button';

.changeset/avatar-button-block.md

@@ -0,0 +1,2 @@
+---
+---

.changeset/mosaic-avatar-interactive-styles.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/lib/registry.ts

@@ -3,6 +3,7 @@ import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import {
  Fallback as AvatarFallbackStory,
+ Interactive as AvatarInteractive,
  meta as avatarMeta,
  Primary as AvatarPrimary,
  Shapes as AvatarShapes,
@@ -175,6 +176,7 @@ const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: Car
 const avatarModule: StoryModule = {
  meta: avatarMeta,
  Primary: AvatarPrimary,
+ Interactive: AvatarInteractive,
  Fallback: AvatarFallbackStory,
  Sizes: AvatarSizes,
  Shapes: AvatarShapes,

packages/swingset/src/stories/avatar.mdx

@@ -2,7 +2,7 @@ import * as AvatarStories from './avatar.stories';
 
 # Avatar
 
-Avatar represents a user or entity as an image, falling back to a blank placeholder 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` holds the space until then.
+Avatar represents a user or entity as an image, falling back to a blank placeholder when the image is missing or fails to load. It is a compound component: `Avatar.Root` positions and sizes the box, `Avatar.Image` renders the picture once it loads, `Avatar.Fallback` holds the space until then, and `Avatar.Icon` adds an optional corner affordance.
 
 The fallback still takes children — initials, an icon — but never paints them, so an entity without a picture reads as an absent image rather than as two letters. They stay in the DOM, held in an `avatar-fallback-content` slot that is `visibility: hidden`: out of the page, the accessibility tree, and the tab order together, and overridable by a consumer who wants them back.
 
@@ -37,10 +37,11 @@ import { Avatar } from '@clerk/ui/mosaic/components/avatar';
 
 | Part | Slot (`.cl-*`) | Description |
 | ----------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape.  |
+| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, positioning, and polymorphic rendering. |
 | `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. Carries `data-pending` while an image is still resolving. Optional `delayMs`. |
 | — | `cl-avatar-fallback-content` | Wraps whatever `Avatar.Fallback` was handed, hidden. Override its `visibility` to paint initials or an icon. |
+| `Avatar.Icon` | `cl-avatar-icon` | Renders an optional icon surface over the avatar corner. |
 
 ---
 
@@ -55,6 +56,15 @@ While an image is still resolving, the fallback carries `data-pending` and pulse
  storyModule={AvatarStories}
 />
 
+### Interactive
+
+Use `render` to compose the avatar onto a button or another trigger without introducing a separate wrapper component. The `lg` avatar and button are both 48×48.
+
+<Story
+ name='Interactive'
+ storyModule={AvatarStories}
+/>
+
 ### Fallback
 
 Once the image fails, the pulse stops and the fallback settles into a plain fill. Nothing is on its way for an entity that has no picture, so its mark holds still rather than claiming to be loading one.

packages/swingset/src/stories/avatar.stories.tsx

@@ -1,6 +1,7 @@
 /** @jsxImportSource @emotion/react */
 import type { AvatarProps } from '@clerk/ui/mosaic/components/avatar';
 import { Avatar } from '@clerk/ui/mosaic/components/avatar';
+import { Icon } from '@clerk/ui/mosaic/components/icon';
 
 import type { StoryMeta } from '@/lib/types';
 
@@ -33,6 +34,7 @@ function knobsAsProps(props: Record<string, unknown>) {
 }
 
 const IMAGE_SRC = 'https://github.com/clerk.png';
+const COLIN_IMAGE_SRC = 'https://avatars.githubusercontent.com/u/51144033?v=4';
 
 export function Primary(props: Record<string, unknown>) {
  return (
@@ -70,6 +72,30 @@ export function Fallback(props: Record<string, unknown>) {
  );
 }
 
+export function Interactive(props: Record<string, unknown>) {
+ return (
+ <Avatar.Root
+ {...knobsAsProps(props)}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Image
+ src={COLIN_IMAGE_SRC}
+ alt='Colin'
+ />
+ <Avatar.Fallback>CL</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>
+ );
+}
+
 export function Sizes(props: Record<string, unknown>) {
  return (
  <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>

packages/ui/src/mosaic/components/avatar/avatar.styles.ts

@@ -8,9 +8,8 @@ const pulse = stylex.keyframes({
 });
 
 export const styles = stylex.create({
- // root — clips its parts to the shape/size; fill comes from the image or fallback
+ // root — sizes and positions its parts; fill comes from the image or fallback
  base: {
- overflow: 'hidden',
  alignItems: 'center',
  aspectRatio: '1 / 1',
  display: 'inline-flex',
@@ -24,6 +23,22 @@ export const styles = stylex.create({
  verticalAlign: 'middle',
  },
 
+ interactive: {
+ background: 'transparent',
+ // An avatar used as a native button has no border shrinking the avatar inside it.
+ borderWidth: 0,
+ outline: {
+ default: 'none',
+ ':focus-visible': `2px solid ${colorVars['--cl-color-primary']}`,
+ },
+ appearance: 'none',
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled, [aria-disabled="true"])': 'not-allowed',
+ },
+ outlineOffset: '2px',
+ },
+
  // Carries the root's radius rather than leaning on the clip alone, so a part that paints its own
  // fill rounds off cleanly instead of showing a corner.
  image: {
@@ -63,6 +78,24 @@ export const styles = stylex.create({
  },
  animationTimingFunction: 'cubic-bezier(0.4, 0, 0.6, 1)',
  },
+
+ icon: {
+ borderColor: colorVars['--cl-color-border'],
+ borderRadius: radiusVars['--cl-radius-full'],
+ borderStyle: 'solid',
+ borderWidth: '1px',
+ overflow: 'hidden',
+ alignItems: 'center',
+ backgroundColor: colorVars['--cl-color-card'],
+ boxSizing: 'border-box',
+ display: 'flex',
+ insetBlockEnd: `calc(${space['2']} * -1)`,
+ insetInlineStart: `calc(${space['1']} * -1)`,
+ justifyContent: 'center',
+ position: 'absolute',
+ height: space['6'],
+ width: space['6'],
+ },
 });
 
 // shape — square shares its radius with Button; circle rounds fully

packages/ui/src/mosaic/components/avatar/avatar.test.tsx

@@ -4,6 +4,7 @@ import { flushSync } from 'react-dom';
 import { createRoot } from 'react-dom/client';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
+import { Icon } from '../icon';
 import { Avatar } from './avatar';
 
 // React reads this off the global object and ships no typing for it.
@@ -280,9 +281,37 @@ describe('Mosaic Avatar', () => {
  expect(avatar).toHaveStyle({ marginTop: '8px' });
  });
 
+ it('composes its root onto another element and renders an icon affordance', () => {
+ const ref = React.createRef<HTMLSpanElement>();
+ render(
+ <Avatar.Root
+ ref={ref}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Fallback>CN</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>,
+ );
+
+ const button = screen.getByRole('button', { name: 'Edit profile picture' });
+ expect(button).toHaveClass('cl-avatar');
+ expect(button).toHaveAttribute('data-size', 'lg');
+ expect(ref.current).toBe(button);
+ expect(button.querySelector('.cl-avatar-icon')).toHaveAttribute('aria-hidden', 'true');
+ });
+
  it('throws when a part is rendered outside <Avatar.Root>', () => {
  const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
  expect(() => render(<Avatar.Fallback>CN</Avatar.Fallback>)).toThrow(/must be rendered inside <Avatar.Root>/);
+ expect(() => render(<Avatar.Icon />)).toThrow(/must be rendered inside <Avatar.Root>/);
  spy.mockRestore();
  });
 });

packages/ui/src/mosaic/components/avatar/avatar.tsx

@@ -1,7 +1,9 @@
+import { useRender } from '@clerk/headless/utils';
 import { useSafeLayoutEffect } from '@clerk/shared/react';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
+import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { reset } from '../reset.styles';
 import { shapes, sizes, styles } from './avatar.styles';
@@ -23,34 +25,34 @@ function useAvatarContext(part: string): AvatarContextValue {
  return context;
 }
 
-export interface AvatarProps extends React.ComponentPropsWithRef<'span'> {
+export interface AvatarProps extends MosaicComponentProps<'span'> {
  shape?: 'circle' | 'square';
  size?: 'fit' | 'lg' | 'md' | 'sm' | 'xs';
 }
 
 const AvatarRoot = React.forwardRef<HTMLSpanElement, AvatarProps>(function MosaicAvatarRoot(
- { shape = 'circle', size = 'md', className, style, children, ...rest },
+ { shape = 'circle', size = 'md', render, className, style, ...rest },
  ref,
 ) {
  const [status, setStatus] = React.useState<ImageLoadingStatus>('idle');
  const value = React.useMemo<AvatarContextValue>(() => ({ status, onStatusChange: setStatus }), [status]);
+ const interactive = Boolean(render);
+ const element = useRender({
+ defaultTagName: 'span',
+ render,
+ ref,
+ props: {
+ ...mergeStyleProps(
+ themeProps('avatar', { shape, size }),
+ stylex.props(reset.base, styles.base, shapes[shape], sizes[size], interactive && styles.interactive),
+ className,
+ style,
+ ),
+ ...rest,
+ },
+ });
 
- return (
- <AvatarContext.Provider value={value}>
- <span
- ref={ref}
- {...mergeStyleProps(
- themeProps('avatar', { shape, size }),
- stylex.props(reset.base, styles.base, shapes[shape], sizes[size]),
- className,
- style,
- )}
- {...rest}
- >
- {children}
- </span>
- </AvatarContext.Provider>
- );
+ return <AvatarContext.Provider value={value}>{element}</AvatarContext.Provider>;
 });
 
 export type AvatarImageProps = React.ComponentPropsWithRef<'img'>;
@@ -152,13 +154,33 @@ const AvatarFallback = React.forwardRef<HTMLSpanElement, AvatarFallbackProps>(fu
  );
 });
 
+export type AvatarIconProps = React.ComponentPropsWithRef<'span'>;
+
+const AvatarIcon = React.forwardRef<HTMLSpanElement, AvatarIconProps>(function MosaicAvatarIcon(
+ { className, style, ...rest },
+ ref,
+) {
+ useAvatarContext('Avatar.Icon');
+
+ return (
+ <span
+ ref={ref}
+ aria-hidden
+ {...mergeStyleProps(themeProps('avatar-icon'), stylex.props(reset.base, styles.icon), className, style)}
+ {...rest}
+ />
+ );
+});
+
 /**
- * Compound avatar. `Avatar.Root` clips and sizes the box; `Avatar.Image` renders
+ * Compound avatar. `Avatar.Root` positions and sizes the box; `Avatar.Image` renders
  * once its source loads; `Avatar.Fallback` holds the space until then, as a blank
- * placeholder that pulses only while an image is actually on its way.
+ * placeholder that pulses only while an image is actually on its way; `Avatar.Icon`
+ * adds an optional corner affordance.
  */
 export const Avatar = {
  Root: AvatarRoot,
  Image: AvatarImage,
  Fallback: AvatarFallback,
+ Icon: AvatarIcon,
 };

packages/ui/src/mosaic/components/avatar/index.ts

@@ -1,2 +1,2 @@
 export { Avatar } from './avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from './avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from './avatar';

packages/ui/src/mosaic/icons/registry.tsx

@@ -9,11 +9,11 @@ type IconComponent = React.ForwardRefExoticComponent<
  * Builds a glyph from its inner `<path>` markup. Glyphs omit `width`/`height` so the `Icon` recipe
  * controls size, and use `currentColor` so they inherit text color. Grow the set on demand.
  */
-function glyph(children: React.ReactNode): IconComponent {
+function glyph(children: React.ReactNode, viewBox = '0 0 16 16'): IconComponent {
  return React.forwardRef<SVGSVGElement, React.ComponentPropsWithoutRef<'svg'>>((props, ref) => (
  <svg
  ref={ref}
- viewBox='0 0 16 16'
+ viewBox={viewBox}
  fill='none'
  xmlns='http://www.w3.org/2000/svg'
  {...props}
@@ -94,6 +94,15 @@ const Plus = glyph(
  />,
 );
 
+const Pen = glyph(
+ <path
+ d='M12.03 3.972a1.59 1.59 0 0 0-2.261 0l-.01.01-5.056 4.89a1.25 1.25 0 0 0-.351.627l-.61 2.747 2.542-.598a1.25 1.25 0 0 0 .59-.325L12.085 6.2c.573-.638.549-1.62-.057-2.228M8.71 2.909a3.09 3.09 0 0 1 4.383.005 3.126 3.126 0 0 1 .06 4.341l-5.228 5.138a2.75 2.75 0 0 1-1.298.715l-3.705.872a.75.75 0 0 1-.904-.893l.87-3.914a2.75 2.75 0 0 1 .772-1.38z'
+ fill='currentColor'
+ fillRule='evenodd'
+ clipRule='evenodd'
+ />,
+);
+
 const LogOut = glyph(
  <path
  d='M6.25 13.25H3.75V2.75H6.25M10.25 10.75L13 8L10.25 5.25M13 8H6.25'
@@ -141,6 +150,7 @@ export const iconRegistry = {
  check: Check,
  close: Close,
  ellipsis: Ellipsis,
+ pen: Pen,
  plus: Plus,
  'log-out': LogOut,
  cog: Cog,

packages/ui/src/mosaic/styles/index.ts

@@ -7,7 +7,7 @@
 export type { MosaicComponentProps, MosaicElementProps } from '../props';
 
 export { Avatar } from '../components/avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from '../components/avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from '../components/avatar';
 export { Badge } from '../components/badge';
 export type { BadgeProps } from '../components/badge';
 export { Button, SubmitButton } from '../components/button';

.changeset/avatar-button-block.md

@@ -0,0 +1,2 @@
+---
+---

.changeset/mosaic-avatar-interactive-styles.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/lib/registry.ts

@@ -3,6 +3,7 @@ import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import {
  Fallback as AvatarFallbackStory,
+ Interactive as AvatarInteractive,
  meta as avatarMeta,
  Primary as AvatarPrimary,
  Shapes as AvatarShapes,
@@ -175,6 +176,7 @@ const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: Car
 const avatarModule: StoryModule = {
  meta: avatarMeta,
  Primary: AvatarPrimary,
+ Interactive: AvatarInteractive,
  Fallback: AvatarFallbackStory,
  Sizes: AvatarSizes,
  Shapes: AvatarShapes,

packages/swingset/src/stories/avatar.mdx

@@ -2,7 +2,7 @@ import * as AvatarStories from './avatar.stories';
 
 # Avatar
 
-Avatar represents a user or entity as an image, falling back to a blank placeholder 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` holds the space until then.
+Avatar represents a user or entity as an image, falling back to a blank placeholder when the image is missing or fails to load. It is a compound component: `Avatar.Root` positions and sizes the box, `Avatar.Image` renders the picture once it loads, `Avatar.Fallback` holds the space until then, and `Avatar.Icon` adds an optional corner affordance.
 
 The fallback still takes children — initials, an icon — but never paints them, so an entity without a picture reads as an absent image rather than as two letters. They stay in the DOM, held in an `avatar-fallback-content` slot that is `visibility: hidden`: out of the page, the accessibility tree, and the tab order together, and overridable by a consumer who wants them back.
 
@@ -37,10 +37,11 @@ import { Avatar } from '@clerk/ui/mosaic/components/avatar';
 
 | Part | Slot (`.cl-*`) | Description |
 | ----------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, clips its children to the shape.  |
+| `Avatar.Root` | `cl-avatar` | Owns `shape` / `size`, positioning, and polymorphic rendering. |
 | `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. Carries `data-pending` while an image is still resolving. Optional `delayMs`. |
 | — | `cl-avatar-fallback-content` | Wraps whatever `Avatar.Fallback` was handed, hidden. Override its `visibility` to paint initials or an icon. |
+| `Avatar.Icon` | `cl-avatar-icon` | Renders an optional icon surface over the avatar corner. |
 
 ---
 
@@ -55,6 +56,15 @@ While an image is still resolving, the fallback carries `data-pending` and pulse
  storyModule={AvatarStories}
 />
 
+### Interactive
+
+Use `render` to compose the avatar onto a button or another trigger without introducing a separate wrapper component. The `lg` avatar and button are both 48×48.
+
+<Story
+ name='Interactive'
+ storyModule={AvatarStories}
+/>
+
 ### Fallback
 
 Once the image fails, the pulse stops and the fallback settles into a plain fill. Nothing is on its way for an entity that has no picture, so its mark holds still rather than claiming to be loading one.

packages/swingset/src/stories/avatar.stories.tsx

@@ -1,6 +1,7 @@
 /** @jsxImportSource @emotion/react */
 import type { AvatarProps } from '@clerk/ui/mosaic/components/avatar';
 import { Avatar } from '@clerk/ui/mosaic/components/avatar';
+import { Icon } from '@clerk/ui/mosaic/components/icon';
 
 import type { StoryMeta } from '@/lib/types';
 
@@ -33,6 +34,7 @@ function knobsAsProps(props: Record<string, unknown>) {
 }
 
 const IMAGE_SRC = 'https://github.com/clerk.png';
+const COLIN_IMAGE_SRC = 'https://avatars.githubusercontent.com/u/51144033?v=4';
 
 export function Primary(props: Record<string, unknown>) {
  return (
@@ -70,6 +72,30 @@ export function Fallback(props: Record<string, unknown>) {
  );
 }
 
+export function Interactive(props: Record<string, unknown>) {
+ return (
+ <Avatar.Root
+ {...knobsAsProps(props)}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Image
+ src={COLIN_IMAGE_SRC}
+ alt='Colin'
+ />
+ <Avatar.Fallback>CL</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>
+ );
+}
+
 export function Sizes(props: Record<string, unknown>) {
  return (
  <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>

packages/ui/src/mosaic/components/avatar/avatar.styles.ts

@@ -8,9 +8,8 @@ const pulse = stylex.keyframes({
 });
 
 export const styles = stylex.create({
- // root — clips its parts to the shape/size; fill comes from the image or fallback
+ // root — sizes and positions its parts; fill comes from the image or fallback
  base: {
- overflow: 'hidden',
  alignItems: 'center',
  aspectRatio: '1 / 1',
  display: 'inline-flex',
@@ -24,6 +23,22 @@ export const styles = stylex.create({
  verticalAlign: 'middle',
  },
 
+ interactive: {
+ background: 'transparent',
+ // An avatar used as a native button has no border shrinking the avatar inside it.
+ borderWidth: 0,
+ outline: {
+ default: 'none',
+ ':focus-visible': `2px solid ${colorVars['--cl-color-primary']}`,
+ },
+ appearance: 'none',
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled, [aria-disabled="true"])': 'not-allowed',
+ },
+ outlineOffset: '2px',
+ },
+
  // Carries the root's radius rather than leaning on the clip alone, so a part that paints its own
  // fill rounds off cleanly instead of showing a corner.
  image: {
@@ -63,6 +78,24 @@ export const styles = stylex.create({
  },
  animationTimingFunction: 'cubic-bezier(0.4, 0, 0.6, 1)',
  },
+
+ icon: {
+ borderColor: colorVars['--cl-color-border'],
+ borderRadius: radiusVars['--cl-radius-full'],
+ borderStyle: 'solid',
+ borderWidth: '1px',
+ overflow: 'hidden',
+ alignItems: 'center',
+ backgroundColor: colorVars['--cl-color-card'],
+ boxSizing: 'border-box',
+ display: 'flex',
+ insetBlockEnd: `calc(${space['2']} * -1)`,
+ insetInlineStart: `calc(${space['1']} * -1)`,
+ justifyContent: 'center',
+ position: 'absolute',
+ height: space['6'],
+ width: space['6'],
+ },
 });
 
 // shape — square shares its radius with Button; circle rounds fully

packages/ui/src/mosaic/components/avatar/avatar.test.tsx

@@ -4,6 +4,7 @@ import { flushSync } from 'react-dom';
 import { createRoot } from 'react-dom/client';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
+import { Icon } from '../icon';
 import { Avatar } from './avatar';
 
 // React reads this off the global object and ships no typing for it.
@@ -280,9 +281,37 @@ describe('Mosaic Avatar', () => {
  expect(avatar).toHaveStyle({ marginTop: '8px' });
  });
 
+ it('composes its root onto another element and renders an icon affordance', () => {
+ const ref = React.createRef<HTMLSpanElement>();
+ render(
+ <Avatar.Root
+ ref={ref}
+ size='lg'
+ render={
+ <button
+ type='button'
+ aria-label='Edit profile picture'
+ />
+ }
+ >
+ <Avatar.Fallback>CN</Avatar.Fallback>
+ <Avatar.Icon>
+ <Icon name='pen' />
+ </Avatar.Icon>
+ </Avatar.Root>,
+ );
+
+ const button = screen.getByRole('button', { name: 'Edit profile picture' });
+ expect(button).toHaveClass('cl-avatar');
+ expect(button).toHaveAttribute('data-size', 'lg');
+ expect(ref.current).toBe(button);
+ expect(button.querySelector('.cl-avatar-icon')).toHaveAttribute('aria-hidden', 'true');
+ });
+
  it('throws when a part is rendered outside <Avatar.Root>', () => {
  const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
  expect(() => render(<Avatar.Fallback>CN</Avatar.Fallback>)).toThrow(/must be rendered inside <Avatar.Root>/);
+ expect(() => render(<Avatar.Icon />)).toThrow(/must be rendered inside <Avatar.Root>/);
  spy.mockRestore();
  });
 });

packages/ui/src/mosaic/components/avatar/avatar.tsx

@@ -1,7 +1,9 @@
+import { useRender } from '@clerk/headless/utils';
 import { useSafeLayoutEffect } from '@clerk/shared/react';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
+import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { reset } from '../reset.styles';
 import { shapes, sizes, styles } from './avatar.styles';
@@ -23,34 +25,34 @@ function useAvatarContext(part: string): AvatarContextValue {
  return context;
 }
 
-export interface AvatarProps extends React.ComponentPropsWithRef<'span'> {
+export interface AvatarProps extends MosaicComponentProps<'span'> {
  shape?: 'circle' | 'square';
  size?: 'fit' | 'lg' | 'md' | 'sm' | 'xs';
 }
 
 const AvatarRoot = React.forwardRef<HTMLSpanElement, AvatarProps>(function MosaicAvatarRoot(
- { shape = 'circle', size = 'md', className, style, children, ...rest },
+ { shape = 'circle', size = 'md', render, className, style, ...rest },
  ref,
 ) {
  const [status, setStatus] = React.useState<ImageLoadingStatus>('idle');
  const value = React.useMemo<AvatarContextValue>(() => ({ status, onStatusChange: setStatus }), [status]);
+ const interactive = Boolean(render);
+ const element = useRender({
+ defaultTagName: 'span',
+ render,
+ ref,
+ props: {
+ ...mergeStyleProps(
+ themeProps('avatar', { shape, size }),
+ stylex.props(reset.base, styles.base, shapes[shape], sizes[size], interactive && styles.interactive),
+ className,
+ style,
+ ),
+ ...rest,
+ },
+ });
 
- return (
- <AvatarContext.Provider value={value}>
- <span
- ref={ref}
- {...mergeStyleProps(
- themeProps('avatar', { shape, size }),
- stylex.props(reset.base, styles.base, shapes[shape], sizes[size]),
- className,
- style,
- )}
- {...rest}
- >
- {children}
- </span>
- </AvatarContext.Provider>
- );
+ return <AvatarContext.Provider value={value}>{element}</AvatarContext.Provider>;
 });
 
 export type AvatarImageProps = React.ComponentPropsWithRef<'img'>;
@@ -152,13 +154,33 @@ const AvatarFallback = React.forwardRef<HTMLSpanElement, AvatarFallbackProps>(fu
  );
 });
 
+export type AvatarIconProps = React.ComponentPropsWithRef<'span'>;
+
+const AvatarIcon = React.forwardRef<HTMLSpanElement, AvatarIconProps>(function MosaicAvatarIcon(
+ { className, style, ...rest },
+ ref,
+) {
+ useAvatarContext('Avatar.Icon');
+
+ return (
+ <span
+ ref={ref}
+ aria-hidden
+ {...mergeStyleProps(themeProps('avatar-icon'), stylex.props(reset.base, styles.icon), className, style)}
+ {...rest}
+ />
+ );
+});
+
 /**
- * Compound avatar. `Avatar.Root` clips and sizes the box; `Avatar.Image` renders
+ * Compound avatar. `Avatar.Root` positions and sizes the box; `Avatar.Image` renders
  * once its source loads; `Avatar.Fallback` holds the space until then, as a blank
- * placeholder that pulses only while an image is actually on its way.
+ * placeholder that pulses only while an image is actually on its way; `Avatar.Icon`
+ * adds an optional corner affordance.
  */
 export const Avatar = {
  Root: AvatarRoot,
  Image: AvatarImage,
  Fallback: AvatarFallback,
+ Icon: AvatarIcon,
 };

packages/ui/src/mosaic/components/avatar/index.ts

@@ -1,2 +1,2 @@
 export { Avatar } from './avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from './avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from './avatar';

packages/ui/src/mosaic/icons/registry.tsx

@@ -9,11 +9,11 @@ type IconComponent = React.ForwardRefExoticComponent<
  * Builds a glyph from its inner `<path>` markup. Glyphs omit `width`/`height` so the `Icon` recipe
  * controls size, and use `currentColor` so they inherit text color. Grow the set on demand.
  */
-function glyph(children: React.ReactNode): IconComponent {
+function glyph(children: React.ReactNode, viewBox = '0 0 16 16'): IconComponent {
  return React.forwardRef<SVGSVGElement, React.ComponentPropsWithoutRef<'svg'>>((props, ref) => (
  <svg
  ref={ref}
- viewBox='0 0 16 16'
+ viewBox={viewBox}
  fill='none'
  xmlns='http://www.w3.org/2000/svg'
  {...props}
@@ -94,6 +94,15 @@ const Plus = glyph(
  />,
 );
 
+const Pen = glyph(
+ <path
+ d='M12.03 3.972a1.59 1.59 0 0 0-2.261 0l-.01.01-5.056 4.89a1.25 1.25 0 0 0-.351.627l-.61 2.747 2.542-.598a1.25 1.25 0 0 0 .59-.325L12.085 6.2c.573-.638.549-1.62-.057-2.228M8.71 2.909a3.09 3.09 0 0 1 4.383.005 3.126 3.126 0 0 1 .06 4.341l-5.228 5.138a2.75 2.75 0 0 1-1.298.715l-3.705.872a.75.75 0 0 1-.904-.893l.87-3.914a2.75 2.75 0 0 1 .772-1.38z'
+ fill='currentColor'
+ fillRule='evenodd'
+ clipRule='evenodd'
+ />,
+);
+
 const LogOut = glyph(
  <path
  d='M6.25 13.25H3.75V2.75H6.25M10.25 10.75L13 8L10.25 5.25M13 8H6.25'
@@ -141,6 +150,7 @@ export const iconRegistry = {
  check: Check,
  close: Close,
  ellipsis: Ellipsis,
+ pen: Pen,
  plus: Plus,
  'log-out': LogOut,
  cog: Cog,

packages/ui/src/mosaic/styles/index.ts

@@ -7,7 +7,7 @@
 export type { MosaicComponentProps, MosaicElementProps } from '../props';
 
 export { Avatar } from '../components/avatar';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from '../components/avatar';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps, AvatarIconProps } from '../components/avatar';
 export { Badge } from '../components/badge';
 export type { BadgeProps } from '../components/badge';
 export { Button, SubmitButton } from '../components/button';