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

The props below cover the shape and size of an avatar, and what it shows when there is no picture to display.

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

One avatar, plus a group for stacking several together.

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