If you've used shadcn/ui, you already know the components are clean, simple, and very easy to customize. The Shadcn Avatar is no different. It's a small component, but you'll use it in many places: dashboards, chat apps, profile cards, comments, and even navbars.
At its core, the shadcn avatar is just an image with a fallback. But the best part is how flexible it is. You can add a status badge, stack multiple avatars, show a skeleton loader, animate it, and more. And you don't need heavy code to do any of this.
In this guide, we'll go through practical shadcn avatar examples that you can copy, paste, and use right away. By the end, you'll know how to set it up, customize it, and pick the right variant for your UI.
Here's what we'll cover:
- A quick preview of the avatar
- Installation steps
- 11+ useful avatar variants
- When to use each one
- Best practices + FAQs
Let's get started.
Quick Preview Code
Before we go deep into all the variants, here's a quick look at a simple Shadcn Avatar. This is the version you'll use most of the time.
This gives you:
- A clean circular avatar
- A fallback if the image fails
- Works out of the box with shadcn/ui
Now let's set it up properly.
Install Instructions
Setting up the shadcn avatar is super quick. If you already have shadcn/ui installed, this will take less than a minute.
1. Add the Avatar component
Run this command:
This will generate: components/ui/avatar.tsx
2. Import it into your component
You'll use three parts:
AvatarAvatarImageAvatarFallback
Example import:
3. How it works
Avataris the wrapperAvatarImagehandles the profile imageAvatarFallbackshows initials or a backup if the image fails
4. Works with both Next.js and Vite
There's nothing extra to configure. If you're using Next.js Image, you can swap it in later, but the default works for most cases.
Shadcn Avatar Variants
Avatars look simple on the surface, but in real apps they do a lot more than just show a profile picture. You'll see them with badges, tooltips, loaders, animations, and even stacked groups.
The good news is that the shadcn avatar component is super flexible, so you can build all these variations without extra libraries or complicated CSS.
In this section, we'll walk through real, practical shadcn avatar examples you can drop directly into your project. Each variant includes:
- a quick explanation
- a live demo
- a clean copy-paste snippet
- and when it makes sense to use it
Let's start exploring the different ways you can level up your avatars.
1. Basic Avatar
This is the simplest version of the shadcn avatar. Clean, minimal, and perfect for dashboards, navbars, or profile cards.
When to Use It:
- You just need a profile image
- The user is logged in
- You want something simple with fallback initials
2. Avatar With Fallback
Sometimes the image fails or the user doesn't have one. The fallback makes your UI look clean instead of broken.
When to Use It:
- Users don't upload images
- API doesn't return image URLs
- Perfect for comments, chat messages, and lists
3. Rounded Avatar
By default, the avatar is already rounded. But you can make it even more rounded or tweak the shape for different UI styles.
When to Use It:
- Cards or grids where you prefer softer corners
- Team pages or product UIs
- Modern dashboard themes
4. Avatar With Status Badge (Online / Offline)
This one is super common in chat apps, dashboards, and team lists. You simply place a small badge (green, gray, yellow, etc.) on top of the avatar to show whether the user is online or not.
When to Use It:
- Chat apps
- Team activity pages
- User lists with live status
- Real-time dashboards
5. Avatar With Tooltip
Sometimes you want more info on hover without cluttering the UI. A tooltip is perfect for this.
When to Use It:
- User roles
- Showing usernames in a compact UI
- Comments, chat bubbles, or notifications
6. Avatar With Border
Adding a simple border helps the avatar pop, especially on dark backgrounds or colorful cards.
When to Use It:
- On dark or patterned backgrounds
- In lists where the avatar needs more separation
- Modern dashboard UIs
7. Animated Avatar (Framer Motion)
If you want your UI to feel more alive, adding a small motion effect works really well. You can animate hover, tap, or even load-in transitions using Framer Motion.
When to Use It:
- Interactive dashboards
- Modern SaaS UIs
- Profile cards
- Anywhere you want a subtle micro-interaction
- Great for "premium-feel" interfaces
8. Avatar Group (Stacked)
Stacked avatars are perfect for showing a group of users, team members, or collaborators. They save space and look clean, especially in project dashboards or activity feeds.
When to Use It:
- Team members on a project
- Activity feeds
- "People who joined" sections
- Collab features
- Group chats
9. Avatar in Navbar
This is one of the most common places you'll use an avatar. It usually sits on the top-right corner and opens a dropdown or user menu when clicked.
When to Use It:
- Top navigation bar
- Sidebar top section
- User account dropdown
- SaaS dashboards and admin panels
10. Avatar With Skeleton Loading
When your app fetches user data from an API, there might be a short loading delay. Instead of showing a blank space, you can use a skeleton to keep the UI smooth.
When to Use It:
- When loading user data
- API-based dashboards
- Chat apps while messages load
- Any place where avatars appear instantly after fetching
11. Custom Size Avatar (sm, md, lg)
Different parts of your UI need different avatar sizes. For example, a small avatar in a table, a medium one in a card, or a large one on a profile page. Shadcn makes this very easy.
When to Use It:
- Small avatars for tables, lists, compact UI
- Medium avatars for cards, sidebars, chat messages
- Large avatars for profile pages or hero sections
- Great for responsive UIs where size matters
Best Practices for Using Shadcn Avatar
Even though the avatar component is small, using it the right way can make your UI feel more consistent and polished. Here are a few practical tips to keep in mind.
1. Always provide a fallback
Images fail more often than you think. Maybe the URL breaks, the API returns null, or the user never uploaded a photo.
- Use short initials or an icon as your fallback.
- It keeps the UI clean and avoids broken-image visuals.
2. Keep avatar sizes consistent
Use a small set of sizes like:
h-8 w-8orh-10 w-10for compact UIh-12 w-12for mediumh-16 w-16or more for profile pages
Having too many random sizes makes your interface look messy.
3. Add borders on dark backgrounds
If your UI has dark sections, borders help the avatar stand out. A simple class works well:
4. Use status badges sparingly
Online/offline indicators are useful, but only show them if they add value.
For example:
- Chat apps → Yes
- Static dashboards → Not always needed
5. Skeletons improve loading UX
If your UI loads data from an API, showing a skeleton instead of a blank space gives a smoother feel. It makes your app feel faster even when it isn't.
6. Avoid adding heavy logic inside avatars
Keep avatars lightweight.
Handle user data, conditions, or loading states outside and pass clean props in.
7. Use groups for social or team-focused UI
Stacked or grouped avatars work great when you want to show multiple people in a small space, especially in:
- Projects
- Comments
- Teams
- Workspaces
Frequently Asked Questions
Conclusion
The Shadcn Avatar may look like a small component, but it's one of the most useful pieces in any UI. Whether you're building a dashboard, a chat app, a user profile, or a team page, avatars show up everywhere.
The best part is how flexible it is. You can add fallbacks, borders, badges, tooltips, animations, groups, skeletons, and custom sizes without writing heavy code or extra CSS. Just plug it in and shape it the way your product needs.
Now you've seen the most practical avatar examples, and you can easily drop them into your app. Feel free to mix, match, and customize these patterns to fit your design system.
If you want to explore more, Shadcn has a lot of other great components to pair with avatars - dropdowns, tooltips, cards, skeletons, and more.
