Avatar

Display user profile image, initials or fallback icon

Polymorphic

Polymorphic component

Source

LLM docs

Docs

PackageIcon

Usage

import { Avatar } from '@mantine/core';
import { StarIcon } from '@phosphor-icons/react';

function Demo() {
  return (
    <>
      {/* With image */}
      <Avatar src="avatar.png" alt="it's me" />

      {/* Default placeholder */}
      <Avatar radius="xl" />

      {/* Letters with xl radius */}
      <Avatar color="cyan" radius="xl">MK</Avatar>

      {/* Custom placeholder icon */}
      <Avatar color="blue" radius="sm">
        <StarIcon size={20} />
      </Avatar>
    </>
  );
}

To display initials instead of the default placeholder, set the name prop to the name of the person, for example, name="John Doe". If the name is set, you can use color="initials" to generate a color based on the name:

import { Avatar, Group } from '@mantine/core';

const names = [
  'John Doe',
  'Jane Mol',
  'Alex Lump',
  'Sarah Condor',
  'Mike Johnson',
  'Kate Kok',
  'Tom Smith',
];

function Demo() {
  const avatars = names.map((name) => <Avatar key={name} name={name} color="initials" />);
  return <Group>{avatars}</Group>;
}

Allowed initials colors

By default, all colors from the default theme are allowed for initials. You can restrict them by providing the allowedInitialsColors prop with an array of colors. Note that the default colors array does not include custom colors defined in the theme – you need to provide them manually if needed.

import { Avatar, Group } from '@mantine/core';

const names = [
  'John Doe',
  'Jane Mol',
  'Alex Lump',
  'Sarah Condor',
  'Mike Johnson',
  'Kate Kok',
  'Tom Smith',
];

function Demo() {
  const avatars = names.map((name) => (
    <Avatar key={name} name={name} color="initials" allowedInitialsColors={['blue', 'red']} />
  ));
  return <Group>{avatars}</Group>;
}

Placeholder

If the image cannot be loaded or is not provided, Avatar will display a placeholder instead. By default, the placeholder is an icon, but it can be changed to any React node:

import { Avatar } from '@mantine/core';
import { StarIcon } from '@phosphor-icons/react';

function Demo() {
  return (
    <>
      {/* Default placeholder */}
      <Avatar src={null} alt="no image here" />

      {/* Default placeholder with custom color */}
      <Avatar src={null} alt="no image here" color="indigo" />

      {/* Placeholder with initials */}
      <Avatar src={null} alt="Vitaly Rtishchev" color="red">VR</Avatar>

      {/* Placeholder with custom icon */}
      <Avatar color="blue" radius="xl">
        <StarIcon size={20} />
      </Avatar>
    </>
  );
}

Variants

Variant

Radius

Size

Color

Src

import { Avatar } from '@mantine/core';

function Demo() {
  return <Avatar variant="filled" radius="sm" src="" />;
}

Avatar.Group

The Avatar.Group component combines multiple avatars into a stack:

import { Avatar } from '@mantine/core';

function Demo() {
  return (
    <Avatar.Group>
      <Avatar src="image.png" />
      <Avatar src="image.png" />
      <Avatar src="image.png" />
      <Avatar>+5</Avatar>
    </Avatar.Group>
  );
}

Note that you must not wrap child Avatar components with any additional elements, but you can wrap Avatar with components that do not render any HTML elements in the current tree, for example Tooltip.

import { Avatar } from '@mantine/core';

// Will not work correctly
function Demo() {
  return (
    <Avatar.Group spacing="sm">
      <div>
        <Avatar src="image.png" radius="xl" />
      </div>
      <Avatar src="image.png" radius="xl" />
      <Avatar src="image.png" radius="xl" />
      <Avatar radius="xl">+5</Avatar>
    </Avatar.Group>
  );
}

Example of usage with Tooltip:

import { Avatar, Tooltip } from '@mantine/core';

function Demo() {
  return (
    <Tooltip.Group openDelay={300} closeDelay={100}>
      <Avatar.Group spacing="sm">
        <Tooltip label="Salazar Troop" withArrow>
          <Avatar src="image.png" radius="xl" />
        </Tooltip>
        <Tooltip label="Bandit Crimes" withArrow>
          <Avatar src="image.png" radius="xl" />
        </Tooltip>
        <Tooltip label="Jane Rata" withArrow>
          <Avatar src="image.png" radius="xl" />
        </Tooltip>
        <Tooltip
          withArrow
          label={
            <>
              <div>John Outcast</div>
              <div>Levi Capitan</div>
            </>
          }
        >
          <Avatar radius="xl">+2</Avatar>
        </Tooltip>
      </Avatar.Group>
    </Tooltip.Group>
  );
}

Polymorphic component

Avatar is a polymorphic component – its default root element is div, but it can be changed to any other element or component with the component prop:

import { Avatar } from '@mantine/core';

function Demo() {
  return <Avatar component="button" />;
}

You can also use components in the component prop, for example, Next.js Link:

import Link from 'next/link';
import { Avatar } from '@mantine/core';

function Demo() {
  return <Avatar component={Link} href="/" />;
}

Polymorphic components with TypeScript
Note that polymorphic component prop types are different from regular components – they do not extend HTML element props of the default element. For example, AvatarProps does not extend React.ComponentProps'<'div'>' although div is the default element.
If you want to create a wrapper for a polymorphic component that is not polymorphic (does not support the component prop), then your component props interface should extend HTML element props, for example:
import type { AvatarProps, ElementProps } from '@mantine/core';

interface MyAvatarProps extends AvatarProps,
  ElementProps<'button', keyof AvatarProps> {}
If you want your component to remain polymorphic after wrapping, use the polymorphic function described in this guide.

Example of using Avatar as a link:

import { Avatar } from '@mantine/core';

function Demo() {
  return (
    <Avatar
      component="a"
      href="https://github.com/rtivital"
      target="_blank"
      src="avatar.png"
      alt="it's me"
    />
  );
}

Accessibility

Avatar renders an <img /> HTML element. Set the alt prop to describe the image – it is also used as the title attribute for the avatar placeholder when the image cannot be loaded.

import { Avatar } from '@mantine/core';

function Demo() {
  // ❌ No alt for image
  return <Avatar src="./image.png" />;

  // ✅ alt is set
  return <Avatar src="./image.png" alt="Rob Johnson" />;

  // ✅ title is not required, but still recommended
  return <Avatar>RJ</Avatar>;

  // ✅ title is set on placeholder
  return <Avatar alt="Rob Johnson">RJ</Avatar>;
}

Accordion

BackgroundImage