Avatar

Available from version 0.7.0

An avatar is a graphical representation of a user's identity.

Basics

import { Avatar } from 'tailwind-joy/components';

By default, the Avatar component displays a generic Person Icon. You can replace this icon with a text string or an image.

JG

import { Avatar, Box } from 'tailwind-joy/components';

export function AvatarBasics() {
  return (
    <Box className="flex gap-4">
      <Avatar />
      <Avatar>JG</Avatar>
      <Avatar alt="Remy Sharp" src="/img/avatar/1.jpg" />
    </Box>
  );
}

Text avatar

Wrap the Avatar component around a string to display text. Note that the Avatar is designed to comfortably fit two letters at most - for instance, a user's initials:

RE

import { Avatar } from 'tailwind-joy/components';

export function AvatarTextAvatar() {
  return <Avatar>RE</Avatar>;
}

Image avatar

Insert images into the Avatar by defining a path inside the src prop, just like you would with an HTML <img> element. Make sure to write a meaningful description for the alt prop.

import { Avatar, Box } from 'tailwind-joy/components';

export function AvatarImageAvatar() {
  return (
    <Box className="flex gap-4">
      <Avatar alt="Remy Sharp" src="/img/avatar/1.jpg" />
      <Avatar alt="Cindy Baker" src="/img/avatar/2.jpg" />
      <Avatar alt="Travis Howard" src="/img/avatar/3.jpg" />
    </Box>
  );
}

Image fallbacks

If an error occurs while loading the Avatar's image, it will fall back to the following alternatives (in this order):

1. The provided child string
2. The first letter of the alt text
3. The default generic icon

import { Avatar, Box } from 'tailwind-joy/components';

export function AvatarImageFallbacks() {
  return (
    <Box className="flex gap-4">
      <Avatar alt="Remy Sharp" src="/broken-image.jpg">
        BT
      </Avatar>
      <Avatar alt="Remy Sharp" src="/broken-image.jpg" />
      <Avatar src="/broken-image.jpg" />
    </Box>
  );
}

Customization

Variants

The Avatar component supports four variants: solid, soft (default), outlined, and plain.

import { Avatar, Box } from 'tailwind-joy/components';

export function AvatarVariants() {
  return (
    <Box className="flex gap-4">
      <Avatar variant="solid" />
      <Avatar variant="soft" />
      <Avatar variant="outlined" />
      <Avatar variant="plain" />
    </Box>
  );
}

Sizes

The Avatar component supports three sizes: sm, md (default), and lg.

import { Avatar, Box } from 'tailwind-joy/components';

export function AvatarSizes() {
  return (
    <Box className="flex items-center gap-4">
      <Avatar size="sm" />
      <Avatar size="md" />
      <Avatar size="lg" />
    </Box>
  );
}

Colors

The Avatar component supports five colors: primary, neutral (default), danger, success, and warning.

import { Avatar, Box } from 'tailwind-joy/components';

export function AvatarColors() {
  return (
    <Box className="flex items-center gap-4">
      <Avatar color="primary" />
      <Avatar color="neutral" />
      <Avatar color="danger" />
      <Avatar color="success" />
      <Avatar color="warning" />
    </Box>
  );
}

Usage with Avatar Group

Use the Avatar Group component to group multiple Avatars together.

import { AvatarGroup } from 'tailwind-joy/components';

Quantity within a group

The Avatar Group does not provide built-in props to control the maximum or the total number of Avatars within a group. This is intentionally left open-ended to give you broader options for customization.

The demo below shows an example of an Avatar Group that maxes out at five; all Avatars beyond the first four are lumped together in the fifth Avatar, which displays the total number hidden:

+2

import { Avatar, AvatarGroup } from 'tailwind-joy/components';

const avatars = [
  {
    alt: 'Remy Sharp',
    src: '/img/avatar/1.jpg',
  },
  {
    alt: 'Cindy Baker',
    src: '/img/avatar/2.jpg',
  },
  {
    alt: 'Travis Howard',
    src: '/img/avatar/3.jpg',
  },
  {
    alt: 'Agnes Walker',
    src: '/img/avatar/4.jpg',
  },
];
const surplus = 2;

export function AvatarGroupQuantityWithinAGroup() {
  return (
    <AvatarGroup>
      {avatars.map((avatar) => (
        <Avatar key={avatar.alt} {...avatar} />
      ))}
      {surplus && <Avatar>+{surplus}</Avatar>}
    </AvatarGroup>
  );
}

Consistent appearance

The Avatar component exposes meaningful CSS variables to communicate with Avatar Group. You can apply those variables to other non-Avatar components to mimic the Avatar's appearance inside of a group. This customization technique makes your interface more resilient to changes, as any style changes applied to the Avatar will also be applied to the other components in the group.

Here is an example using an Icon Button with its styles defined by the Avatar's CSS variables:

import { MdMoreVert } from 'react-icons/md';
import { Avatar, AvatarGroup, IconButton } from 'tailwind-joy/components';
import { iconClass } from 'tailwind-joy/utils';

export function AvatarGroupConsistentAppearance() {
  return (
    <AvatarGroup>
      <Avatar alt="Remy Sharp" src="/img/avatar/1.jpg" />
      <Avatar alt="Cindy Baker" src="/img/avatar/2.jpg" />
      <Avatar alt="Travis Howard" src="/img/avatar/3.jpg" />
      <IconButton
        color="neutral"
        variant="soft"
        onClick={() => alert('You clicked!')}
        className="ms-[var(--Avatar-marginInlineStart)] rounded-[50%] [box-shadow:var(--Avatar-ring)]"
      >
        <MdMoreVert className={iconClass()} />
      </IconButton>
    </AvatarGroup>
  );
}

info

iconClass() is an adapter function provided by Tailwind-Joy.

Overlapping order

By default, the first Avatar in the group sits behind the second, which sits behind the third, and so on. You can reverse the overlapping order by reversing the order of the Avatars and using the CSS flexDirection: row-reverse property in the Avatar Group:

+3

import { Avatar, AvatarGroup } from 'tailwind-joy/components';

export function AvatarGroupOverlappingOrder() {
  return (
    <AvatarGroup className="flex-row-reverse">
      <Avatar>+3</Avatar>
      <Avatar alt="Travis Howard" src="/img/avatar/3.jpg" />
      <Avatar alt="Cindy Baker" src="/img/avatar/2.jpg" />
      <Avatar alt="Remy Sharp" src="/img/avatar/1.jpg" />
    </AvatarGroup>
  );
}

Vertical stacking

To render the Avatar Group vertically, add the CSS writing-mode: vertical-rl property and rotate the interior element (if one is present) by -90 degrees.

+3

import { Avatar, AvatarGroup } from 'tailwind-joy/components';

export function AvatarGroupVerticalStacking() {
  return (
    <AvatarGroup className="[writing-mode:vertical-rl]">
      <Avatar alt="Remy Sharp" src="/img/avatar/1.jpg" />
      <Avatar alt="Cindy Baker" src="/img/avatar/2.jpg" />
      <Avatar alt="Travis Howard" src="/img/avatar/3.jpg" />
      <Avatar className="-rotate-90">+3</Avatar>
    </AvatarGroup>
  );
}

Anatomy

The Avatar component is composed of a root <div> that may wrap around an <svg>, an <img>, or a string:

<div class="tj-avatar-root ...">
  <!-- Avatar contents -->
</div>

API

See the documentation below for a complete reference to all of the props available to the components mentioned here.

• <Avatar />
• <AvatarGroup />
• <Box />
• <IconButton />