Avatar

Purpose and Scope

Avatar is the shadcn/ui component for representing a user, team member, or account identity with an image and a fallback. In the ARIA component documentation it is described as an image element with a fallback for representing the user, and the page is marked as a component in the ARIA base family. The practical reader problem is simple: most product interfaces need a compact identity marker that still behaves predictably when an image URL is absent, slow, private, or broken. Avatar solves that by making the image and fallback separate composition pieces rather than hiding all behavior inside a single opaque widget.

Sources: apps/v4/content/docs/components/aria/avatar.mdx

The component is also a good example of the repository’s broader open-code model. The docs do not only show a rendered preview; they tell readers to install generated source into their own project, or manually copy the implementation into a local file and adjust imports. That matters because teams can style the badge, change sizing, wire the avatar into a dropdown menu, and keep the code aligned with their own component library choices. The surrounding changelog entries explain why this workflow has evolved: the CLI can install components, support multiple React frameworks, resolve files flexibly, apply presets, and inline shared Tailwind utilities when teams want to eject the package dependency.

Sources: apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx, apps/v4/content/docs/changelog/2025-04-shadcn-2-5.mdx, apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx, apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx, apps/v4/content/docs/changelog/2026-05-shadcn-eject.mdx

Relevant Source Files

• apps/v4/content/docs/components/aria/avatar.mdx - Primary reader-facing documentation for the Avatar component, including installation, import usage, composition diagrams, preview examples, sizing, dropdown use, RTL preview, and the visible API reference.
• apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx - Explains the rewritten CLI workflow behind component installation, import aliases, framework support, remote components, and monorepo improvements.
• apps/v4/content/docs/changelog/2025-04-shadcn-2-5.mdx - Provides the resolve-anywhere context for registry files and import resolution when installed component code is placed in an application.
• apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx - Describes the style and library customization model that affects how component code can be generated for different visual systems and bases.
• apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx - Describes applying presets to existing projects while preserving base and RTL settings, which is relevant when an existing Avatar implementation is restyled.
• apps/v4/content/docs/changelog/2026-05-shadcn-eject.mdx - Describes shared Tailwind utilities, RTL fixes, and the eject workflow for teams that want to inline shared CSS dependencies.

Installation and Import Flow

The documented installation path is the CLI command for adding the component by name. That command installs the Avatar source into the project, after which consumers import the named pieces from their configured component alias. The manual path is deliberately similar: copy the generated component source into the project, place it at the expected UI component location, and then update imports to match the application’s aliases. This mirrors the larger shadcn/ui principle that components are not consumed as a closed runtime package; they become local code that can be changed, reviewed, and adapted by the application team.

Sources: apps/v4/content/docs/components/aria/avatar.mdx, apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx

npx shadcn@latest add avatar

import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
 
<Avatar>
  <AvatarImage src="https://github.com/shadcn.png" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

Import alias configuration is especially important because the CLI and copied examples assume a local project alias such as the common components UI path. The August 2024 CLI changelog explains that projects should define aliases for components, utilities, UI components, library code, and hooks in their configuration when adopting the newer CLI. For Avatar this means the public import line is only correct when the project’s alias points to the generated file. In a monorepo or nonstandard source tree, readers should make the component import follow their own configured alias rather than moving unrelated project files to satisfy the example.

Sources: apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx

Core Composition

Avatar uses a small composition tree. The root wraps the visible image, the fallback, and an optional badge. The image component is responsible for displaying the user image when a source is available. The fallback component supplies initials, a short label, or another placeholder when the image cannot be shown. The badge is an optional overlay attached to the avatar, documented as positioned at the bottom right by default. This structure is useful because each concern can be styled or replaced independently while still keeping a consistent outer shape, spacing, and size.

Sources: apps/v4/content/docs/components/aria/avatar.mdx

Avatar
├── AvatarImage
├── AvatarFallback
└── AvatarBadge

A group follows the same principle at a larger scale. The group component contains multiple avatars, and each avatar may still include its own image, fallback, and badge. A group count can be added as a final item when the interface needs to say that more users exist than can be shown individually. The documentation presents Avatar Group, Avatar Group Count, and Avatar Group with Icon as separate examples, which is a useful guide for product work: start with the avatars that need to be visible, add the count when the set is truncated, and only add an icon when the count or group has an additional semantic meaning.

Sources: apps/v4/content/docs/components/aria/avatar.mdx

AvatarGroup
├── Avatar
│   ├── AvatarImage
│   ├── AvatarFallback
│   └── AvatarBadge
├── Avatar
│   ├── AvatarImage
│   ├── AvatarFallback
│   └── AvatarBadge
└── AvatarGroupCount

Variants and Usage Patterns

The basic pattern is the safest default for profile pictures, comment authors, navigation menus, and account switchers. Provide a source URL for the image and a short fallback value that remains useful without the image. The docs show initials as the fallback, which is a strong convention because it preserves identity recognition while avoiding layout shifts when the image fails. The examples also show an alt value on the image in the badge section. In application code, treat the fallback as user-facing content, not just a development placeholder, because it may be the only visible identity marker in privacy-conscious environments.

Sources: apps/v4/content/docs/components/aria/avatar.mdx

Badges extend the identity marker with status or metadata. The documented badge example uses a class name to customize color, including a dark-mode specific class. That is the intended customization surface for small visual states such as online, busy, verified, unread, or role indicators. Because the badge is a child of the Avatar, it travels with the avatar wherever the avatar is used. The documentation also includes a badge-with-icon example, which makes sense when a colored dot is not expressive enough. Use icons sparingly so the avatar remains readable at small sizes.

Sources: apps/v4/content/docs/components/aria/avatar.mdx

<Avatar>
  <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
  <AvatarFallback>CN</AvatarFallback>
  <AvatarBadge className="bg-green-600 dark:bg-green-800" />
</Avatar>

The size prop changes the avatar size with the documented values default, small, and large. This is preferable to ad hoc width and height classes when the surrounding component system expects consistent density. Small avatars fit dense lists, notifications, and compact tables. Default avatars work for common navigation and card layouts. Large avatars are better for profile headers or account panels where identity is a primary element. Since the newer create workflow can generate different visual styles such as compact or generous spacing, teams should treat size as the semantic control and use local styling only when the product has a design exception.

Sources: apps/v4/content/docs/components/aria/avatar.mdx, apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx

Dropdown usage turns the avatar into an account or profile menu trigger. The Avatar documentation presents this as a supported pattern rather than a separate component, which means consumers compose Avatar with the menu component used elsewhere in their system. Keep the avatar itself focused on identity display and place menu concerns in the dropdown layer: labels, account switching, sign-out actions, and keyboard interaction belong to the menu. This separation helps teams retain the same avatar source, fallback, badge, and size while changing only the surrounding command surface for navigation bars, sidebars, or profile pages.

Sources: apps/v4/content/docs/components/aria/avatar.mdx

RTL, Presets, and Generated Code

The Avatar page includes a right-to-left preview and points readers to the RTL configuration guide. That signal is important because badge placement, grouped overlap, and dropdown trigger alignment can become visually wrong when direction changes. The eject changelog explains that shared Tailwind utilities were introduced partly because RTL issues were easier to fix in one shared place than duplicate across every component. For Avatar users, the immediate next step is to enable RTL at the project level, then verify the documented RTL preview patterns for avatars, groups, badges, and dropdown triggers in the real application layout.

Sources: apps/v4/content/docs/components/aria/avatar.mdx, apps/v4/content/docs/changelog/2026-05-shadcn-eject.mdx

Presets and regeneration are part of the maintenance story. The create changelog says configuration can rewrite component code to match selected libraries, icons, base color, themes, fonts, spacing, and structure. The apply changelog adds that an existing project can switch presets without starting over, reinstall existing components, and update theme-related assets while keeping current base and RTL settings. For Avatar, this means teams should avoid treating the generated file as permanently frozen. If the project adopts a new preset, rerun the supported workflow and then reapply intentional local changes, especially custom badge colors or dropdown integrations.

Sources: apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx, apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx

The resolve-anywhere changelog also matters when Avatar is installed from a registry or into a nonstandard workspace. The CLI tracks files and performs multi-pass resolution to handle imports and aliases, which reduces the requirement that every project use the same folder layout. This does not remove the need for coherent imports; it means the installation machinery is designed to adapt to the target application. When reviewing an Avatar addition, check that the generated component path, alias, image imports, menu imports, and utility imports all resolve from the application package that owns the component.

Sources: apps/v4/content/docs/changelog/2025-04-shadcn-2-5.mdx

API Reference

The visible Avatar API documents the root component with a size prop and className prop. The size prop accepts default, small, and large values, with default as the documented default. The className prop is available for local styling. AvatarImage documents src, alt, and className, matching the examples that pass a remote image URL and, in the badge example, an alt label. AvatarFallback documents className, and its content is supplied by composition. AvatarBadge is documented as a child component that can receive className for custom colors and sizes, and it can contain an icon.

Sources: apps/v4/content/docs/components/aria/avatar.mdx

Practical Checklist

Start by installing Avatar through the CLI or copying the manual component source, then confirm that the import path matches the project’s configured aliases. Build the smallest useful composition first: root, image, and fallback. Add badges only for status that users can understand at avatar size, and prefer documented className customization over one-off structural changes. Use AvatarGroup and AvatarGroupCount when space is limited or the set is larger than the visible participants. Before shipping, test the failed-image fallback, dark mode badge colors, each documented size, dropdown trigger behavior, and RTL layout if the application supports right-to-left languages.

Sources: apps/v4/content/docs/components/aria/avatar.mdx, apps/v4/content/docs/changelog/2026-05-shadcn-eject.mdx