Thrive Design System

Components

Avatar

A flexible avatar component that supports multiple variants, sizes, status indicators, and badge notifications

Installation

npm install @thrivecart/ui
yarn add @thrivecart/ui
pnpm add @thrivecart/ui
bun add @thrivecart/ui

Usage

Import the Avatar components from the package:

import { Avatar, AvatarImage, AvatarFallback, AvatarStack } from '@thrivecart/ui';

Examples

Basic Avatar

Simple Avatar

Avatar with initials fallback

JL
<Avatar size="md">
<AvatarFallback>JL</AvatarFallback>
</Avatar>

With Image

Avatar with Image

Avatar using an image with fallback to initials

CN
<Avatar size="lg">
<AvatarImage src="https://api.dicebear.com/9.x/lorelei/svg" alt="User Avatar" />
<AvatarFallback>CN</AvatarFallback>
</Avatar>

Sizes

Avatar Sizes

Five size options from xs to xl

XS
SM
MD
LG
XL
<div className="flex items-end gap-4">
<Avatar size="xs">
  <AvatarFallback>XS</AvatarFallback>
</Avatar>
<Avatar size="sm">
  <AvatarFallback>SM</AvatarFallback>
</Avatar>
<Avatar size="md">
  <AvatarFallback>MD</AvatarFallback>
</Avatar>
<Avatar size="lg">
  <AvatarFallback>LG</AvatarFallback>
</Avatar>
<Avatar size="xl">
  <AvatarFallback>XL</AvatarFallback>
</Avatar>
</div>

Color Variants

Avatar Variants

Use different color variants for visual distinction

N
B
G
Y
R
O
P
P
I
T
<div className="flex items-center gap-4">
<Avatar size="md" variant="normal">
  <AvatarFallback>N</AvatarFallback>
</Avatar>
<Avatar size="md" variant="blue">
  <AvatarFallback>B</AvatarFallback>
</Avatar>
<Avatar size="md" variant="green">
  <AvatarFallback>G</AvatarFallback>
</Avatar>
<Avatar size="md" variant="yellow">
  <AvatarFallback>Y</AvatarFallback>
</Avatar>
<Avatar size="md" variant="red">
  <AvatarFallback>R</AvatarFallback>
</Avatar>
<Avatar size="md" variant="orange">
  <AvatarFallback>O</AvatarFallback>
</Avatar>
<Avatar size="md" variant="purple">
  <AvatarFallback>P</AvatarFallback>
</Avatar>
<Avatar size="md" variant="pink">
  <AvatarFallback>P</AvatarFallback>
</Avatar>
<Avatar size="md" variant="indigo">
  <AvatarFallback>I</AvatarFallback>
</Avatar>
<Avatar size="md" variant="teal">
  <AvatarFallback>T</AvatarFallback>
</Avatar>
</div>

Status Indicators

Status Colors

Show user presence with status indicators

JL
JL
JL
<div className="flex items-center gap-6">
<Avatar size="md" showStatus statusColor="success">
  <AvatarFallback>JL</AvatarFallback>
</Avatar>
<Avatar size="md" showStatus statusColor="warning">
  <AvatarFallback>JL</AvatarFallback>
</Avatar>
<Avatar size="md" showStatus statusColor="error">
  <AvatarFallback>JL</AvatarFallback>
</Avatar>
</div>

Badge Notifications

Notification Badges

Display notification count with automatic 99+ overflow

JL
5
JL
25
JL
99+
<div className="flex items-center gap-6">
<Avatar size="md" badgeCount={5}>
  <AvatarFallback>JL</AvatarFallback>
</Avatar>
<Avatar size="md" badgeCount={25}>
  <AvatarFallback>JL</AvatarFallback>
</Avatar>
<Avatar size="md" badgeCount={100}>
  <AvatarFallback>JL</AvatarFallback>
</Avatar>
</div>

Combined Features

Status and Badge

Combine status indicators with notification badges

CN
12
<Avatar size="lg" showStatus statusColor="success" badgeCount={12}>
<AvatarImage src="https://api.dicebear.com/9.x/lorelei/svg" alt="User Avatar" />
<AvatarFallback>CN</AvatarFallback>
</Avatar>

With Icon Fallback

Icon Fallback

Use an icon when no image or initials are available

<Avatar size="md">
<AvatarFallback showIcon />
</Avatar>

Avatar Stack

Stacked Avatars

Use AvatarStack to display multiple users in a compact overlapping layout with automatic overflow handling.

U1
U2
U3
+2
<AvatarStack max={3} size="md">
<Avatar>
  <AvatarImage src="https://api.dicebear.com/9.x/lorelei/svg?seed=user1" alt="User 1" />
  <AvatarFallback>U1</AvatarFallback>
</Avatar>
<Avatar>
  <AvatarFallback>U2</AvatarFallback>
</Avatar>
<Avatar>
  <AvatarFallback>U3</AvatarFallback>
</Avatar>
<Avatar>
  <AvatarFallback>U4</AvatarFallback>
</Avatar>
<Avatar>
  <AvatarFallback>U5</AvatarFallback>
</Avatar>
</AvatarStack>

Avatar Stack Sizes

Stack Sizes

AvatarStack supports all avatar sizes with appropriate overlap spacing.

A
B
C
D
+1
A
B
C
D
+1
A
B
C
D
+1
A
B
C
D
+1
<div className="flex flex-col gap-4">
<AvatarStack max={4} size="xs">
  <Avatar><AvatarFallback>A</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>B</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>C</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>D</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>E</AvatarFallback></Avatar>
</AvatarStack>
<AvatarStack max={4} size="sm">
  <Avatar><AvatarFallback>A</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>B</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>C</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>D</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>E</AvatarFallback></Avatar>
</AvatarStack>
<AvatarStack max={4} size="md">
  <Avatar><AvatarFallback>A</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>B</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>C</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>D</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>E</AvatarFallback></Avatar>
</AvatarStack>
<AvatarStack max={4} size="lg">
  <Avatar><AvatarFallback>A</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>B</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>C</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>D</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>E</AvatarFallback></Avatar>
</AvatarStack>
</div>

Best Practices

✓

Provide alt text

Always provide descriptive alt text for avatar images to support screen readers.

✓

Use initials as fallback

Provide initials as a fallback when images fail to load or aren't available.

✓

Choose appropriate sizes

Use smaller sizes (xs, sm) for lists and larger sizes (lg, xl) for profile pages or detailed views.

✗

Don't omit fallbacks

Always provide a fallback (initials or icon) in case the image fails to load.

✗

Don't overuse status indicators

Only use status indicators when presence information is relevant to the context.

✓

Use AvatarStack for groups

Use AvatarStack component for displaying multiple avatars - it handles overflow automatically.

Props

Avatar

Props

AvatarStack

PropTypeDefaultDescription
childrenReactNode-Avatar elements to stack
maxnumber4Maximum number of avatars to display before showing overflow
size'xs' | 'sm' | 'md' | 'lg' | 'xl''md'Size of all avatars in the stack
borderColor'panel' | 'bg' | 'transparent''panel'Border color for the ring (adapts to light/dark mode)
classNamestring-Additional className for the container

Accessibility

Image Accessibility

Always include alt text for avatar images. Use descriptive text like "John Doe's avatar" rather than just "avatar".

  • Provide meaningful alt text for all avatar images
  • Ensure status colors have sufficient contrast
  • Don't rely solely on color to convey status (status dots should be clearly visible)
  • Badge counts should be announced by screen readers
  • Use semantic HTML and ARIA attributes where appropriate