Q: How is this different from just rendering an tag?

A raw ` ` shows a broken-image icon on load failure, a blank box during loading, and gives you no hook for initials/placeholder fallbacks. The Radix Avatar primitive solves all three: AvatarImage renders only after the image successfully loads, AvatarFallback renders on load failure (or after a configurable delay), and the container reserves the right dimensions from the start so there's no layout shift. Swap ` ` for this whenever the image is user-controlled.

Question 1

What is a shadcn avatar?

Accepted Answer

A shadcn avatar is a user-identity image component that shows a profile picture with a graceful fallback (initials, icon, or placeholder) when the image fails to load or isn't available. It's built on Radix UI's Avatar primitive (async image loading, fallback after a configurable delay, zero layout shift) and styled with shadcn/ui + Tailwind CSS. Each example in this gallery is a single self-contained TSX file — copy, paste, and ship.

Question 2

Are these avatar examples free?

Accepted Answer

Yes. Every avatar example on shadcn.io is free to copy and use in personal or commercial projects. There's no gated source, no attribution requirement, and no runtime dependency on shadcn.io. Browse any example, view the code, run the installer, and move on.

Question 3

How is this different from just rendering an <img> tag?

Accepted Answer

A raw `` shows a broken-image icon on load failure, a blank box during loading, and gives you no hook for initials/placeholder fallbacks. The Radix Avatar primitive solves all three: AvatarImage renders only after the image successfully loads, AvatarFallback renders on load failure (or after a configurable delay), and the container reserves the right dimensions from the start so there's no layout shift. Swap `` for this whenever the image is user-controlled.

Question 4

When should I use a square avatar instead of the default circular one?

Accepted Answer

Circular avatars are the default for social / community UIs — they match the mental model of "person = dot". Square avatars (with rounded corners) work better in dense data tables, file-manager listings, and layouts where rectangles dominate the grid — the shift from circle to square stops an avatar from feeling like a misplaced token. They're also common in design-tool UIs (Figma, Linear) where every element is a card or tile.

Question 5

How do I add an online / offline status indicator to an avatar?

Accepted Answer

The online-indicator examples wrap the Avatar in a `relative` parent and place a small colored dot absolutely at the bottom-right corner (size-3, ring-2 ring-background, bg-emerald-500 for online / bg-muted for offline). The ring matches the page background so the dot looks punched out of the avatar rather than overlapping. For multiple states (online/idle/offline/DND), use a four-color scale — emerald / amber / zinc / red.

Question 6

How do I show a count badge on an avatar (+3 more)?

Accepted Answer

Use the count-indicator example — an AvatarFallback styled as a small colored badge replaces the image slot, centered text like "+3" or a number like "12". Common in team member stacks where you show the first 3–5 avatars followed by a "+N more" badge to indicate the remaining members. Pair with a hover card or a popover to reveal the hidden list on interaction.

Question 7

Should I use initials or an icon as the fallback?

Accepted Answer

Initials win for known users (profile, team member list) — one or two characters of the person's name, uppercase, tabular. Placeholder icons (Lucide User / UserCircle) win for unknown users (signed-out state, guest reviews, placeholder cards). Match the icon color to your muted-foreground tokens so the fallback recedes visually and doesn't compete with the rest of the UI.

Question 8

How do I add a verification checkmark to an avatar?

Accepted Answer

See the verification-check example. It overlays a small BadgeCheck icon (emerald-500 fill, white checkmark) at the bottom-right of the avatar — same absolute-positioning pattern as the online indicator, just with an icon instead of a dot. Use it sparingly: verification marks inflate in visual importance as you multiply them, so reserve them for genuinely verified accounts.

Question 9

How do I install an avatar example?

Accepted Answer

Run the `npx shadcn@latest add` command shown under the Installation heading on any example's detail page. The shadcn CLI copies the example's TSX source into your project at `components/examples/avatar/…`, plus the shadcn/ui Avatar primitive if you don't already have it. Swap the sample image URL for your own user's avatar URL (or pass it through a next/image optimizer) and you're done.

Question 10

What size should I use for my avatars?

Accepted Answer

Tailwind size utilities work great: `size-8` (32px) for compact table rows, `size-10` (40px) for standard navbar / comment avatars, `size-12` (48px) for list rows, `size-16` to `size-24` for profile headers and hero sections. The Radix primitive is sizeless by default, so you pass the class through to the container. Keep avatar sizes consistent within a single context — mixing sizes in the same list reads as a visual bug.

Question 11

How do I handle user-uploaded avatars that might be huge?

Accepted Answer

Never ship full-resolution user uploads to the browser. Run them through next/image, Cloudinary, imgix, or a server-side image resizer to produce small variants (40px, 80px, 160px) and serve via srcset. The Avatar primitive will use whatever URL you pass, but rendering a 4MB JPEG into a 40px circle wastes bandwidth and hurts LCP. For user-uploaded content, the CDN/optimizer step is not optional.

Question 12

Can I use next/image inside AvatarImage?

Accepted Answer

AvatarImage is an Image primitive under the hood (Radix wraps ``). Swap it with `` from next/image directly inside the Avatar container — keep `AvatarFallback` for the fallback path. This gives you automatic srcset, lazy loading, and CLS-free rendering. The tradeoff is you lose Radix's async-load detection, so make sure next/image's onError handler flips state for the fallback render.

Question 13

Which libraries do avatar examples depend on?

Accepted Answer

Radix UI Avatar (the async-load primitive), shadcn/ui Avatar (the styled wrapper generated into your project by the CLI), Tailwind CSS (styling), and Lucide React (fallback icons + indicators). TypeScript is assumed. React 19 is the baseline. No state library — avatar state lives entirely inside the Radix primitive. Some examples add a secondary primitive (Tooltip, HoverCard) for revealed-on-hover details; those are optional.

Question 14

Are avatar examples accessible for screen reader users?

Accepted Answer

Yes. AvatarImage renders with a required `alt` attribute that screen readers announce ("John Doe profile picture"). AvatarFallback is announced as whatever content you put inside it — put the user's initials as text so SR users still get a useful identifier. For decorative avatars (e.g. a generic testimonial illustration), use `alt=""` so SR users skip them. Online-indicator dots get `aria-label="online"` / `"offline"` for context.

Question 15

Can I use these avatar examples with React Server Components?

Accepted Answer

Avatars with a static src and static fallback render cleanly as Server Components. The Radix primitive's async-load detection happens inside `<img>` event handlers in the client, so the primitive technically renders on both sides — the hydration transition is seamless. If you wrap avatars in interactive parents (hover cards, dropdown menus), those parents enforce a client boundary, but the avatars themselves don't need one.

Question 16

Do these examples work with Tailwind CSS v3 and v4?

Accepted Answer

Both. shadcn.io is authored on Tailwind v4, so the examples use the v4 class names and design tokens. If you're on Tailwind v3, the classes still apply — Tailwind v4 introduced opt-in features but kept the utility naming compatible. Size utilities (size-8, size-10, etc.) exist in both; the `ring-` utilities used for status-indicator rings are identical across versions.

React Avatar Examples for shadcn/ui

Browse every avatar example

Frequently Asked Questions