Library · Foundations

Avatar

Display user images, initials, or placeholder icons with optional title/subtitle labels. Supports multiple sizes (sm/md/lg), shapes (round/square), and semantic types (default/info/success/warning/error).

Figma: Primitives / Avatar ↗

Default

---
import Avatar from "../components/primitives/avatar/Avatar.astro";
---
<Avatar
  img="https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=200&q=60"
  title="Sarah Chen"
  subtitle="Product Designer"
  label="Sarah Chen, Product Designer"
/>
<Avatar initials="DJ" title="David Jeffrey" label="David Jeffrey" type="default" />
<Avatar initials="AB" size="lg" type="info" label="Alex Brown" />

Group

---
import Avatar from "../components/primitives/avatar/Avatar.astro";
import AvatarGroup from "../components/primitives/avatar/AvatarGroup.astro";
---
<AvatarGroup display="condensed">
  <Avatar initials="DJ" type="default" label="David Jeffrey" />
  <Avatar initials="SC" type="success" label="Sarah Chen" />
  <Avatar initials="AB" type="warning" label="Alex Brown" />
</AvatarGroup>

Props

Name	Type	Required	Description
`class`	`string`	—	Additional classes to apply to the Avatar
`img`	`string`	—	Image source URL for the avatar
`initials`	`string`	—	Initials to display when no image is available
`type`	`'default' \| 'info' \| 'success' \| 'warning' \| 'error'`	—	Type of the avatar (affects color scheme) (default: "default")
`shape`	`'round' \| 'square'`	—	Shape of the avatar (default: "round")
`size`	`'sm' \| 'md' \| 'lg' \| string`	—	Size of the avatar (default: "md")
`[key: string]`	`string \| number \| boolean \| undefined`	—	HTML attributes to spread on the avatar
`Group: class`	`string`	—	Additional classes to apply to the AvatarGroup
`Group: display`	`'condensed' \| 'grid'`	—	Display mode for the avatar group (default: "condensed")
`Group: gridItemsSize`	`string`	—	Size of the grid items (used for grid display mode) (default: "200px")
`Group: gridGap`	`string`	—	Gap between grid items (used for grid display mode) (default: "1rem")
`Group: overlapAmount`	`string`	—	Overlap amount for condensed mode (negative margin) (default: "-1rem")
`Group: [key: string]`	`unknown`	—	HTML attributes to spread on the avatar group
`title`	`string`	—	Primary text to display next to the avatar (e.g., name)
`subtitle`	`string`	—	Secondary text to display next to the avatar (e.g., role)
`label`	`string`	—	Accessible label for screen readers — REQUIRED when no title is provided (title and label are enforced as an either/or union)

Example with all props

<Avatar
  class="team-avatar"
  img="/images/sarah.jpg"
  initials="SC"
  type="success"
  shape="square"
  size="lg"
  title="Sarah Chen"
  subtitle="Product Designer"
  label="Sarah Chen, Product Designer"
/>

<AvatarGroup
  class="team-avatars"
  display="grid"
  gridItemsSize="180px"
  gridGap="0.75rem"
  overlapAmount="-0.75rem"
>
  <Avatar initials="DJ" label="David Jeffrey" />
  <Avatar initials="SC" label="Sarah Chen" />
</AvatarGroup>