An avatar is a 32-pixel square that has to work when the image is missing, when the name is one character, when forty of them appear in a row, and when the person has no photo at all. Almost every avatar bug is one of those four cases, and none of them show up in the design file.
51 public components on 21st have "avatar" in the name. Below are the shapes and the fallbacks.
The single avatar
Avatar by originui is the enhanced shadcn base. Everything interesting about it is the fallback chain, which should be three deep: the image, then initials from the name, then a neutral mark. Two initials, from the first and last word, and a background derived deterministically from the name so the same person is the same colour everywhere.
Two details that separate a good one from a default. Initials must be centred optically rather than mathematically, because a capital and a descender do not share a baseline box. And the image needs object-fit: cover with a fixed aspect ratio, or a portrait upload becomes an oval.
The group
Avatar Circles by dillionverma is the overlapping-circles pattern, and Avatar Group by Chetan Verma and Avatar Group by preetsuthar17 are the animated takes. Orbiting Avatars by Ravi Katiyar is the decorative arrangement for a call to action.
The group has one rule that is always broken: the overflow count is not decoration. "+12" has to be reachable, either as a button that opens the full list or as a tooltip that names the rest. A stack that silently hides eleven people is a stack that has lost eleven people.
Also: a row of overlapping avatars is a list. Wrap it in one, give each entry a name, and do not let a screen reader read twelve identical "avatar" labels.
The hover card
Avatar Hover Card by Moumen Soliman expands into profile information on hover. It is a genuinely good pattern for a mention in a comment thread, with two conditions: it must also open on focus, and the information inside must exist somewhere reachable without hovering, because touch has no hover.
The picker and the uploader
Avatar Picker by kokonutd is the choose-from-a-set version, useful when you would rather not handle uploads at all. Avatar Uploader by Efferd is the full path: upload, crop, preview.
Cropping is not optional if you accept uploads. Without it, half of your avatars are the top-left corner of a landscape photo. Square crop, a minimum size, a maximum file size checked before the request, and a visible progress state, because photo uploads from a phone are slow.
The profile card
Animated Profile Card by Erik X and Profile Card Testimonial Carousel by Arunachalam are the larger shape: an avatar with the identity around it.
One note that matters for search: a profile card is a person, and marking it up with Person structured data is one of the few places schema is uncontroversially useful. Name, job title, organisation, and the links out. It costs nothing and it is what lets a page about a person be understood as such.
The four cases the design file never shows
No image. The most common state in any real product. Design the initials version first and treat the photo as the enhancement.
One word. "Cher" produces one initial. Decide whether that is one letter or the first two of the word, and apply it consistently.
A name that is not Latin. Taking name[0] breaks on scripts where a character is composed of several code points, and on emoji. Use Intl.Segmenter with granularity: "grapheme" to take the first real character.
A broken URL. Images 404. The onError handler that falls back to initials is two lines and it is what stops a wall of broken-image icons the day a CDN path changes.
And the smallest one, worth saying because it is everywhere: an avatar next to the person's name should have alt="", not the name again. Otherwise a screen reader reads the name twice.
Where else to look
The honest list of alternatives, because the answer is not always us:
| Source | Best for | Trade-off |
|---|---|---|
| shadcn/ui Avatar | Image, fallback and the loading state, correctly wired | One avatar; no groups, no uploader |
| Radix / Base UI | The fallback timing behaviour without styling | Unstyled |
| DiceBear / Gravatar | Generated or hosted default images | A third-party request per avatar, and a privacy question |
| 21st | Groups, hover cards, pickers, uploaders and profile cards | Quality varies by author, so preview before you take it |
Taking one
Every component page has a live preview and the code. Installing goes through the shadcn CLI against our registry:
That key comes from your 21st account, and installs require a membership. Set API_KEY_21ST once in your shell and the command works for anything in the catalogue. The 21st MCP covers the same ground without leaving the editor: ask Claude, Cursor or Codex for an avatar, get the previews inline, and let the agent write the file.
Frequently asked
- What should an avatar show when there is no image?
- A three-deep fallback: the image, then initials taken from the name, then a neutral mark. Derive the background colour deterministically from the name so the same person is the same colour everywhere, and centre the initials optically rather than mathematically, because a capital and a descender do not share a baseline box.
- How do you take initials from a name safely?
- Not with name[0], which breaks on scripts where a character is several code points and on emoji. Use Intl.Segmenter with grapheme granularity to take the first real character of each word, and decide in advance what a single-word name produces: one letter, or the first two of the word.
- How should an avatar group handle overflow?
- The plus-N count has to be reachable, as a button that opens the full list or a tooltip that names the rest. A stack that silently hides eleven people has lost eleven people. The row is also a list: wrap it in one, give each entry a name, and avoid a screen reader reading a dozen identical avatar labels.
- What alt text should an avatar have?
- Usually empty. When the avatar sits beside the person's name in text, alt="" prevents a screen reader reading the name twice. Give it a real alt only when the image is the sole identification of the person, such as an avatar-only list.