feat: Add <UserAvatar /> documentation

[tmilewski]

🔎 Previews:

• https://clerk.com/docs/pr/tom-add-user-avatar-documentation/nextjs/reference/components/user/user-avatar
• https://clerk.com/docs/pr/tom-add-user-avatar-documentation/reference/javascript/clerk#user-avatar

What does this solve?

Adds documentation for the new <UserAvatar /> component.

What changed?

• Adds sidebar "User components" element
• Adds <UserAvatar /> component reference page
• Adds [un]mountUserAvatar(...) to the Javascript reference

Checklist

• I have clicked on "Files changed" and performed a thorough self-review
• All existing checks pass

[vercel]

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

Project	Deployment	Preview	Updated (UTC)
clerk-docs	Ready	Preview	Oct 23, 2025 5:12pm

[SarahSoutoul]

@tmilewski have submitted a docs review with a few changes. Feel free to check out the commit and let me know if you have any thoughts.

I will test this with the diff SDKs, and if that's all good, then it should be good to go.

Tagging @alexisintech for visibility on this.

[tmilewski]

@SarahSoutoul Thank you!!

[SarahSoutoul]

@tmilewski One comment I had was regarding the picture - it appeared really small, so I removed the styling in my docs review, and it looks a bit better. But I feel like the avatar is still really small - wondering if we could get a better image with the actual avatar being bigger?

Before:

After:

[SarahSoutoul]

Update on this one @alexisintech:

• Have tested the code examples for all SDKs, and noticed issues with Astro, Expo and Nuxt. @tmilewski is currently fixing those.
• For the image, @tmilewski is going to create a ticket for the Design team to have some better images for the component.

[SarahSoutoul]

Update on this one @alexisintech:

• Have tested the code examples for all SDKs, and noticed issues with Astro, Expo and Nuxt. @tmilewski is currently fixing those.
• For the image, @tmilewski is going to create a ticket for the Design team to have some better images for the component.

Another update @alexisintech:

• Issues with Astro, Expo and Nuxt are now fixed, so all code examples work as expected.
• Ticket for the image for the Design team is here: https://linear.app/clerk/issue/DSN-705/imagery-docs-useravatar.

That's the remaining element before approving this, so feel free to review my docs review and any other things while we wait for the image.

[alexisintech]

@tmilewski @SarahSoutoul it looks like there's some extra props here that weren't documented: component and fallback

is there more info surrounding these?

[tmilewski]

@alexisintech Where are you seeing that?

[SarahSoutoul]

@tmilewski @SarahSoutoul it looks like there's some extra props here that weren't documented: component and fallback

is there more info surrounding these?

From the JS repo, there are only two props available:

[SarahSoutoul]

Actually, there is a merge of props @tmilewski

So on top of the UserAvatarProps, there is fallback and component

[alexisintech]

Actually, there is a merge of props @tmilewski

So on top of the UserAvatarProps, there is `fallback` and `component`

yup! let's get those documented please :)

[SarahSoutoul]

Add missing prop

@tmilewski @alexisintech have added the fallback prop here, and updated all the props as optional after looking at the JS repo. But, I am confused about component, and what it does to be honest - in the snippet below, it is part of WithClerkProp, which is something used in other components, yet, not documented on these components. Let me know thoughts!