Avatar

Avatars represent users or entities with images, initials, or placeholder icons. They support multiple sizes and color themes.

Avatar Playground

Preview

Code

Controls

Type:

Image

Initials

Placeholder

Size:

XXL

XXS

XXXS

Avatar Group Playground

Preview

Code

Controls

Size:

XXXS

XXS

Max Visible:

Installation

You can add the avatar component to your project manually:

Install the following dependencies:

npm

pnpm

yarn

bun

npm install class-variance-authority

Copy and paste the following code into your project.

Avatar.tsx

AvatarGroup.tsx

Material.tsx

Loading source code...

Update the import paths to match your project setup.

Update the import aliases (e.g. @/components, @/utils) in the copied files to match your project's path configuration.

Basic Usage

import { Avatar } from '@versaui/ui/components/Avatar';
// Image avatar
<Avatar type="image" person="adam-smith" size="l" />
// Initials avatar
<Avatar type="initials" initials="JD" color="primary" />
// Placeholder avatar
<Avatar type="placeholder" decorative />

Avatar Group

import { AvatarGroup } from '@versaui/ui/components/Avatar';
<AvatarGroup 
  size="m"
  max={4}
  persons={['adam-smith', 'denver-whitman', 'jacob-wilson', 'xavier-hernandez', 'zakir-khan']}
/>

Avatar Types

Avatars can be photographic, based on initials, or a generic placeholder:

// Image — uses a pre-defined person photo
<Avatar type="image" person="adam-smith" size="l" />
// Initials — displays up to two characters
<Avatar type="initials" initials="JD" color="primary" size="l" />
// Placeholder — generic user silhouette
<Avatar type="placeholder" size="l" />

Color Variants

Avatars with type="initials" or type="placeholder" support five color themes:

<Avatar type="initials" initials="AB" color="neutral" />
<Avatar type="initials" initials="CD" color="primary" />
<Avatar type="initials" initials="EF" color="secondary" />
<Avatar type="initials" initials="GH" color="tertiary" />
<Avatar type="initials" initials="IJ" color="quaternary" />

Overflow Handling

The group automatically calculates overflow based on the max prop:

// Max 3 — fourth avatar becomes a "+1" overflow indicator
<AvatarGroup 
  max={3} 
  persons={['adam-smith', 'denver-whitman', 'jacob-wilson', 'xavier-hernandez']} 
/>
// Full group — no overflow indicator
<AvatarGroup 
  max={5} 
  persons={['adam-smith', 'denver-whitman', 'jacob-wilson']} 
/>

Accessibility

The Avatar component is fully accessible:

Decorative avatars: Set decorative to hide from screen readers when the avatar is purely visual
Labeled avatars: Provide aria-label for meaningful identification
Groups: AvatarGroup conveys the total count and overflow to assistive technology

Avatar Props

Prop	Type	Default	Description
`size`	`'xxxs' \| 'xxs' \| 'xs' \| 's' \| 'm' \| 'l' \| 'xl' \| 'xxl'`	`'m'`	Avatar size.
`type`	`'image' \| 'initials' \| 'placeholder'`	`'initials'`	Visual type of avatar.
`color`	`'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'quaternary'`	`'neutral'`	Color theme for initials/placeholder.
`person`	`AvatarPerson`	`'adam-smith'`	Pre-defined person photo (image type).
`initials`	`string`	`—`	Up to two characters (initials type).
`decorative`	`boolean`	`false`	Hide from screen readers.
`aria-label`	`string`	`—`	Accessible label.

AvatarGroup Props

Prop	Type	Default	Description
`size`	`'xxxs' \| 'xxs' \| 'xs' \| 's' \| 'm' \| 'l'`	`'m'`	Size for all avatars in group.
`persons`	`AvatarPerson[]`	`[]`	Array of person identifiers.
`max`	`number`	`4`	Maximum visible avatars before overflow.
`aria-label`	`string`	`—`	Accessible label for the group.

Avatar

Install the following dependencies:

Copy and paste the following code into your project.

Update the import paths to match your project setup.

On this page