Shadcn Avatar: React Avatar Component with Image and Fallback
The Shadcn Avatar is a React avatar component for displaying user profile images with an automatic text fallback. It is styled with Tailwind CSS, fully typed with TypeScript and works on top of both Radix UI and Base UI primitives.
This page collects ready-made avatar examples you can copy straight into a React or Next.js project: circular and rounded avatars, multiple sizes, avatars with status indicators, stacked avatar groups and avatars paired with user details. Every variant ships as a single file with no extra configuration.
What is the Shadcn Avatar component?
An avatar represents a user or entity with a small image, and the Shadcn Avatar handles the hard part: when the image is missing, slow or broken, it renders a fallback with the user's initials instead of an empty circle. The swap happens automatically, so user lists never flash broken images.
Avatars show up in almost every interface: navigation bars, comment threads, chat messages, team pages, activity feeds and data tables in admin dashboards. Because the component is a thin wrapper over accessible primitives, it stays lightweight even when a page renders hundreds of avatars.
Why use the Shadcn Avatar?
- Automatic fallback: Initials render while the profile image loads and whenever it fails, so the layout never breaks.
- Every common pattern included: Sizes, shapes, status dots, notification badges and stacked avatar groups are ready to copy.
- Tailwind CSS styling: Change size, ring, radius or colors with utility classes; no custom CSS files needed.
- Accessible by default: Images keep their alt text and fallbacks are plain text, so screen readers always have something to announce.
- TypeScript included: Every example is fully typed and works in React 19 and Next.js App Router projects.
Production tips
- Always set alt text: Use the person's name as the image alt so assistive technology reads something meaningful.
- Derive initials from the name: Generate the fallback from the display name at render time instead of storing initials separately.
- Serve small images: A 40px avatar does not need a 1000px photo; request a resized thumbnail to keep lists fast.
- Keep sizes consistent: Pick two or three avatar sizes for the whole app and reuse them so interfaces look intentional.
- Cap avatar groups: In stacked groups, show the first few members and collapse the rest into a +N counter.
Integration with other components
The avatar rarely stands alone. Pair it with the Shadcn Hover Card to preview a user profile on hover, or place it inside a Shadcn Dropdown Menu trigger to build the account menu found in most application headers.
In data-heavy screens, avatars sit inside Shadcn Data Table rows and Shadcn Card layouts to make user records scannable, while a Shadcn Badge next to the avatar communicates roles or status. All of these patterns appear across the admin dashboard templates built with this design system.
Base UI and Radix UI support
The examples on this page follow the markup of the official shadcn/ui Avatar, which builds on the Radix UI Avatar primitive for image loading states and fallback timing.
The same component API also maps cleanly to the Base UI Avatar, so teams migrating between primitive libraries can keep the exact same Tailwind CSS classes and swap only the import.