React Avatar Examples — Initials, Groups, Status Badges
Copy-paste React Avatar examples — user initials fallback, avatar groups, online status dots, data table cells, and account menu triggers — using Drivn.
Avatar components appear in almost every interface that involves users — comment threads, data tables, account menus, team rosters, and chat headers. In each location the avatar needs to render a profile picture when one is available and fall back gracefully to initials when it is not. The Drivn Avatar does both in a single component.
Drivn's Avatar accepts four props: src for the image URL, alt for screen reader text, fallback for the initials string, and size for the circle diameter. Four built-in sizes — sm (32 px), md (40 px, default), lg (48 px), xl (64 px) — cover most UI contexts. When src is absent the component renders the first two characters of fallback uppercased against a gradient background using the --color-primary and --color-secondary design tokens, so initials-only avatars look on-brand without any extra className.
This page collects five Avatar patterns you will actually ship: a simple user identity with initials fallback, an overlapping avatar group for team rosters, an avatar with a live online status dot, an avatar cell inside a data table, and an avatar as the trigger in a user account dropdown. Every snippet is copy-paste ready and assumes you have installed Drivn via the CLI and imported Avatar from @/components/ui/avatar. For a comparison against the shadcn/ui Avatar implementation, see Drivn vs shadcn/ui Avatar.
User identity with initials fallback
The simplest Avatar pattern shows a profile picture with initials as fallback. Pass src for the image, alt for screen reader text, and fallback as the two-letter string to show when no image exists. Drivn extracts the first two characters automatically and uppercases them, so fallback="Jane Doe" renders "JA" and fallback="JD" renders "JD". Use size="lg" for the avatar on a profile page or post header where the picture carries identity weight; use size="sm" for dense lists.
For API-driven user data, drive src from the database field directly — when the field is null or empty string the initials render without any null-check wrapper at the call site. Pair with the Tooltip component to show the user's full name on hover.
1 <Avatar 2 src="/user.jpg" 3 alt="Jane Doe" 4 fallback="JD" 5 size="md" 6 /> 7 8 {/* No image — initials render automatically */} 9 <Avatar 10 fallback="Jane Doe" 11 size="md" 12 />
Overlapping avatar group
Team rosters, shared file previews, and "people watching this" indicators often show three to five avatars in an overlapping row. Apply a negative margin-left to each avatar after the first to create the stack effect, and cap the group at a fixed count with a +N overflow label when the list is long.
The outer wrapper needs flex items-center and each Avatar after the first gets -ml-2 or -ml-3 depending on size. Apply a ring-2 ring-background className to each Avatar via the className prop — the ring draws on the background color token, adapting to light and dark themes without hardcoded colors. Combine with a Badge at the end for overflow counts longer than four.
1 const members = [ 2 { src: '/alice.jpg', name: 'Alice' }, 3 { src: '/bob.jpg', name: 'Bob' }, 4 { src: undefined, name: 'Carol Chen' }, 5 { src: '/dave.jpg', name: 'Dave' }, 6 ] 7 const visible = members.slice(0, 3) 8 const overflow = members.length - 3 9 10 <div className="flex items-center"> 11 {visible.map((m) => ( 12 <Avatar 13 key={m.name} 14 src={m.src} 15 alt={m.name} 16 fallback={m.name} 17 size="sm" 18 className="-ml-2 first:ml-0 ring-2 ring-background" 19 /> 20 ))} 21 {overflow > 0 && ( 22 <span className="ml-1 text-sm text-muted-foreground"> 23 +{overflow} 24 </span> 25 )} 26 </div>
Online status indicator
Presence indicators — a green dot for online, grey for offline, yellow for away — are a common need in team tools and chat interfaces. Because Drivn's Avatar has no built-in slot for decorations, the pattern is to wrap the Avatar in a relative container and overlay a positioned <span> for the dot. The border-background class gives the dot a halo that adapts to both light and dark themes.
For screen reader users, include the status in the Avatar's alt text — "Alice (online)" — so the presence is announced without relying on the visual dot. The bottom-0 right-0 position anchors the dot to the bottom-right of the avatar regardless of size, and w-3 h-3 scales visually with md and lg avatar sizes.
1 <div className="relative inline-flex"> 2 <Avatar 3 src="/alice.jpg" 4 alt="Alice (online)" 5 fallback="Alice" 6 size="md" 7 /> 8 <span 9 className={ 10 "absolute bottom-0 right-0 w-3 h-3 rounded-full" 11 + " bg-green-500 border-2 border-background" 12 } 13 title="Online" 14 /> 15 </div>
Avatar inside a data table cell
Data tables that list users almost always want the avatar in the first column alongside the name. Use size="sm" for table rows to keep line height consistent with surrounding text, and wrap the avatar and name in a flex container for alignment.
For tables built with Drivn's DataTable, define the user column with a custom cell renderer that returns the flex container. The size="sm" avatar at 32 px sits flush with the standard table row height. Pass fallback from the user's name field so rows without a profile picture still render a recognizable pair of initials rather than an empty circle.
1 // In your column definition 2 { 3 accessorKey: 'user', 4 header: 'User', 5 cell: ({ row }) => { 6 const user = row.original.user 7 return ( 8 <div className="flex items-center gap-2"> 9 <Avatar 10 src={user.avatarUrl} 11 alt={user.name} 12 fallback={user.name} 13 size="sm" 14 /> 15 <span className="font-medium">{user.name}</span> 16 </div> 17 ) 18 }, 19 }
Install Drivn in one command
Copy the source into your project and own every line. Zero runtime dependencies, pure React + Tailwind.
npx drivn@latest createRequires Node 18+. Works with npm, pnpm, and yarn.
Frequently asked questions
The Drivn Avatar uses a conditional render on the src prop — it shows <img> when src is truthy and the initials span when it is not. A URL that resolves to a 404 is still truthy, so the browser shows a broken image. To add error-based fallback, open src/components/ui/avatar.tsx after install and add a local const [imgError, setImgError] = React.useState(false) state, then pass onError={() => setImgError(true)} to the img element. Render the initials span when either !src or imgError is true.
Yes — wrap the Avatar in a Drivn Tooltip component. Set the content prop to the user's full name and pass the Avatar as a child of Tooltip.Trigger. The Tooltip handles all hover and focus state internally. Use a small Tooltip in dense contexts like data tables and the default size for standalone avatars on profile pages or comment threads.
Pass an empty string as fallback or omit the prop entirely. The component calls fallback?.slice(0, 2).toUpperCase(), which returns undefined when fallback is undefined and an empty string when it is "". Both cases render a gradient circle with no text. The circle uses the --color-primary and --color-secondary gradient by default, so it stays on-brand without a className override.
Yes — pass a className that overrides the rounded-full base class. The cn() utility in Drivn uses tailwind-merge, which resolves conflicting border-radius classes automatically. For a rounded square, use className="rounded-lg"; for a sharp square, use className="rounded-none". Combine with a size variant — size="lg" is common for product cards and file thumbnails that use a square avatar pattern.