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>

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

Examples

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

The Avatar component supports 13 different sizes to accommodate various layout requirements and design needs.

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>

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