Avatar

An image element with a fallback for representing the user.

Anatomy

Import and assemble the component:

1import { Avatar, AvatarGroup, getAvatarColor } from '@raystack/apsara'
2

3<Avatar />
4

5<AvatarGroup>
6  <Avatar />
7  <Avatar />
8</AvatarGroup>

Usage

Variant

Choose between soft and solid variants to control the visual weight and emphasis of the avatar in your interface.

1<Flex gap={5} align="end">
2  <Avatar size={6} variant="soft" fallback="RC" />
3  <Avatar size={6} variant="solid" fallback="RC" />
4</Flex>

Size

size is a number in pixels rather than a named scale, so an avatar can match whatever line height or row it sits in.

1<Flex gap={9} direction="column">
2  <Flex gap={3} align="end">
3    <Avatar size={1} fallback="RC" />
4    <Avatar size={2} fallback="RC" />
5    <Avatar size={3} fallback="RC" />
6    <Avatar size={4} fallback="RC" />
7    <Avatar size={5} fallback="RC" />
8    <Avatar size={6} fallback="RC" />
9    <Avatar size={7} fallback="RC" />
10    <Avatar size={8} fallback="RC" />
11    <Avatar size={9} fallback="RC" />
12  </Flex>
13  <Flex gap={3}>
14    <Avatar size={10} fallback="RC" />
15    <Avatar size={11} fallback="RC" />

Color

Avatar comes with a range of predefined colors including both base and extended color options to match your design system.

1<Flex gap={5}>
2  <Avatar size={6} color="indigo" fallback="RC" />
3  <Avatar size={6} color="orange" fallback="RC" />
4  <Avatar size={6} color="mint" fallback="RC" />
5  <Avatar size={6} color="neutral" fallback="RC" />
6</Flex>

Radius

Choose between small and full border radius styles to match your design preferences.

1<Flex gap={5} align="end">
2  <Avatar size={6} radius="full" fallback="RC" />
3  <Avatar size={6} radius="small" fallback="RC" />
4</Flex>

With Image

Avatar can display user images with graceful fallback to initials when images fail to load or aren't available.

1<Flex gap={5} align="end">
2  <Avatar
3    size={6}
4    radius="full"
5    fallback="RC"
6    src="https://images.unsplash.com/photo-1511485977113-f34c92461ad9?ixlib=rb-1.2.1&w=128&h=128&dpr=2&q=80"
7  />
8  <Avatar
9    size={8}
10    radius="small"
11    fallback="RC"
12    src="https://images.unsplash.com/photo-1511485977113-f34c92461ad9?ixlib=rb-1.2.1&w=128&h=128&dpr=2&q=80"
13  />
14</Flex>

With generated colors

use getAvatarColor utility to generate colors based on a string.

1<Flex gap={5} align="end">
2  <Avatar size={6} color={getAvatarColor("abcde")} fallback="RC" />
3</Flex>

API Reference

Avatar

Renders an individual avatar with image or initials fallback.

Prop

Type

AvatarGroup

Groups multiple avatars with overlap and count indicator.

Prop

Type

Slots

Every rendered part carries a stable data-slot attribute for styling and testing:

SlotElement
avatarThe root element that wraps the image and fallback
avatar-imageThe <img> element (when the image loads)
avatar-fallbackThe fallback shown before the image loads or on error
avatar-groupThe root <div> of an AvatarGroup
avatar-group-itemWrapper around each avatar in the group, including the overflow avatar

Accessibility

  • Uses alt text for avatar images to support screen readers
  • Provides aria-label fallback when no image is available
  • AvatarGroup announces the count of items to assistive technologies