Avatar

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

getAvatarColor derives a color from a string, such as a user's email. The same string always returns the same color, on the server and in the browser.

1getAvatarColor(user.email);
2
3// A different seed maps the same email to a different color.
4getAvatarColor(user.email, { seed: workspaceId });
5
6// Pick only from these colors.
7getAvatarColor(user.email, { palette: ['indigo', 'mint', 'sky'] });

AVATAR_COLOR_PALETTE lists every color getAvatarColor can return. Use it to build a palette, for example to leave out 'neutral', which AvatarGroup uses for the overflow count:

1const palette = AVATAR_COLOR_PALETTE.filter(color => color !== 'neutral');
2getAvatarColor(user.email, { palette });

1(function GeneratedColors() {
2  const people = [
3    { name: "Ravi Chopra", initials: "RC" },
4    { name: "Alice", initials: "A" },
5    { name: "Bob", initials: "B" },
6    { name: "amy", initials: "AM" },
7    { name: "may", initials: "MA" },
8  ];
9
10  return (
11    <Flex direction="column" gap={5}>
12      <Flex gap={5} align="end">
13        {people.map(({ name, initials }) => (
14          <Avatar
15            key={name}

API Reference

The avatar, plus a group for stacking several together.

Avatar

Renders an individual avatar with image or initials fallback.

AvatarGroup

Groups multiple avatars with overlap and count indicator.

getAvatarColor

getAvatarColor(str: string, options?: GetAvatarColorOptions) returns one of the colors in AVATAR_COLOR_PALETTE.

getAvatarColor ignores duplicate and unknown colors in palette. If no valid color is left, it uses all of AVATAR_COLOR_PALETTE and logs one warning in development.

Slots

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

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