Skip to content
Platform Codeالعربية

Avatar

A person's picture, initials or a generic icon. Seven sizes, circle or square, and avatar groups.

Version 0.2.0 ·

Avatar
Direction
Theme
Viewport

Installation

bunx --bun shadcn@latest add @dga/avatar

Usage

page.tsx
tsx
import { Avatar, AvatarGroup } from "@/components/ui/avatar";

<Avatar src="/people/noura.jpg" alt="نورة القحطاني" initials="ن ق" />

<AvatarGroup>
  <Avatar size={32} src="/people/noura.jpg" alt="نورة" />
  <Avatar size={32} initials="+3" aria-label="3 أشخاص آخرون" />
</AvatarGroup>

Built on the Base UI Avatar, which shows the fallback while the image loads and if it fails.

Anatomy

  • Avatar: the root, with the image or the fallback.
  • Image: the picture.
  • Fallback: initials, or a generic user icon.
  • AvatarGroup: a row of avatars, stacked or spaced.

Examples

Sizes and shape

24, 32, 40 (default), 48, 64, 80 and 120px. square uses radius-md; bordered adds a white ring.

Groups

AvatarGroup overlaps its children by 4px with a white ring (stacked, the default). Set stacked={false} to space them.

RTL

A group stacks from the start side, so the overlap direction flips in Arabic.

LTR (English)
RTL (Arabic)

Accessibility

  • Give the image an alt with the person's name, unless the name is already shown next to it (then use alt="").
  • Initials are read as text. For a "+3" overflow avatar, add an aria-label such as "3 more people".
  • The fallback icon is hidden from screen readers.

API Reference

Avatar

A person's picture, initials or a generic user icon.

Avatar props
PropTypeDefault
24 | 32 | 40 | 48 | 64 | 80 | 120

Size in pixels.

40
boolean

Square with rounded corners instead of a circle.

false
boolean

Adds a ring around the avatar.

false
string

One or two letters shown when there is no image.

No default
string

Image URL. Falls back to the initials or icon if it is missing or fails to load.

No default
string

Alternative text for the image. Use the person's name.

""

Also accepts every prop of the Base UI Avatar (opens in a new tab).

AvatarGroup

A row of avatars. Put an Avatar with initials like "+3" last for the remainder.

AvatarGroup props
PropTypeDefault
boolean

Overlap the avatars (Figma: Stacked).

true

Also accepts every prop of the Base UI Avatar (opens in a new tab).

Deviations from DGA

ChangeReason
Avatar: sizes and textOne text size cannot fit avatars from 24 to 120px.

View all 1 deviations for this component

Contrast

12 pairs checked · all pass WCAG 2.1 AAShow 2 states
Variant / stateLightDark
initials / text16.44:1 AAA12.71:1 AAA
icon / icon16.44:1 3:112.71:1 3:1

Text needs 4.5:1, icons and focus rings 3:1. Disabled states are exempt. Full contrast report