Avatar

View source on GitHub
See recent changes on GitHub
Consult PDocs for this component

Avatar is used to represent a user. Every Avatar image has a subtle color wash.

also known as Pinner rep, Persona, User Image, Identifier, Identicon

Figma:
Ready
Responsive:
Ready
Adaptive:
N/A

Props

Component props
Name
Type
Default
name
Required
string
-

The name of the user. This is used for the placeholder treatment if an image is not available.

accessibilityLabel
string
-

String that clients such as VoiceOver will read to describe the element. Will default to name prop if not provided.

color
1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10
-

The background color chosen by the user. A default color will be used if none is selected.

outline
boolean
-

Adds a white border around Avatar so it's visible when displayed on other images.

size
"xs" | "sm" | "md" | "lg" | "xl" | "fit"
-

xs: 24px, sm: 32px, md: 48px, lg: 64px, xl: 120px. If size is fit, Avatar will fill 100% of the parent container width.

src
string
-

The URL of the user's image.

verified
boolean
-

Used to indicate if the user is verified.

Usage guidelines

When to use
  • To reflect a person, company or brand within the product.
When not to use
  • To represent a group of people, companies and/or brands. Use AvatarGroup instead.

Best Practices

Do

Use the default alternative if no image source is available. This will be the first character of the provided name.

Don't

Use alternative graphics or icons

Do

Use round Avatars in the appropriate size for your need. Learn more about avatar sizing.

Don't

Scale or change the shape of Avatar. Instead use the designated Avatar sizes and style.

Do

Use Avatar to represent a person, organization or group ( Avatar Group).

Don't

Use Avatar to represent metaphorical ideas, like a Board. Instead, consider an icon or the appropriate interactive component.

Do

Use the collaborator’s name nearby or in an alternative view if possible.

Don't

Place elements like washes, text or icons over Avatars.

Accessibility

The avatar should have a text equivalent. Use the accessibilityLabel prop to ensure there is a text description for the image. The VoiceOver description will default to the name prop if accessibilityLabel is not provided.

Make sure that the alternative text properly describes the information and function of the avatar image(s). Depending on the situation, it may be helpful to state the collaborator or company name and/or their verification status.

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

Variants

Colors

There are 12 available colors for Avatar.

When to use
  • To reflect a person, company or brand within the product.

Fixed sizes

There are 5 sizes available for Avatar. For certain designs you may need a container-based size. 

import { Avatar, Flex, useDangerouslyInGestaltExperiment } from 'gestalt';

export default function Example() {
  const isInVRExperiment = useDangerouslyInGestaltExperiment({
    webExperimentName: 'web_gestalt_visualRefresh',
    mwebExperimentName: 'web_gestalt_visualRefresh',
  });

  const name = isInVRExperiment ? 'Fatima' : 'Keerthi';
  const src = isInVRExperiment
    ? 'https://i.pinimg.com/originals/bf/bc/27/bfbc27685d81eb9a8f65c201ea661f0e.jpg'
    : 'https://i.ibb.co/ZfCZrY8/keerthi.jpg';

  return (
    <Flex
      alignItems="center"
      gap={4}
      height="100%"
      justifyContent="center"
      width="100%"
      wrap
    >
      <Avatar name={name} size="xs" src={src} />
      <Avatar name={name} size="sm" src={src} />
      <Avatar name={name} size="md" src={src} />
      <Avatar name={name} size="lg" src={src} />
      <Avatar name={name} size="xl" src={src} />
    </Flex>
  );
}

Container-based sizes

Avatars without a size prop will expand to fit the width of their parent container. A common use case is to achieve column-based sizing.

Resize the browser to see these Avatar change to match the width of the Column they have been placed in. 

import { Avatar, Box, Flex } from 'gestalt';

export default function Example() {
  return (
    <Box maxWidth={900} width="100%">
      <Flex>
        <Box width={40}>
          <Avatar name="Keerthi" />
        </Box>
        <Box column={2}>
          <Avatar name="Keethi" />
        </Box>
        <Box column={4}>
          <Avatar name="Keerthi" src="https://i.ibb.co/ZfCZrY8/keerthi.jpg" />
        </Box>
      </Flex>
    </Box>
  );
}

Without an image

If there is no image source provided to the Avatar, the first character of
the name provided will be used as a placeholder. 

import { Avatar, Flex, useDangerouslyInGestaltExperiment } from 'gestalt';

export default function Example() {
  const isInVRExperiment = useDangerouslyInGestaltExperiment({
    webExperimentName: 'web_gestalt_visualRefresh',
    mwebExperimentName: 'web_gestalt_visualRefresh',
  });

  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Avatar
        color={isInVRExperiment ? 1 : undefined}
        name={isInVRExperiment ? 'Rosa' : 'Keerthi'}
        size="lg"
      />
    </Flex>
  );
}

Verified

For users with verified accounts, use the verified prop to add a checkmark. Be sure to update the accessibilityLabel to include this information as well. 

import { Avatar, Flex, useDangerouslyInGestaltExperiment } from 'gestalt';

export default function Example() {
  const isInVRExperiment = useDangerouslyInGestaltExperiment({
    webExperimentName: 'web_gestalt_visualRefresh',
    mwebExperimentName: 'web_gestalt_visualRefresh',
  });

  const name = isInVRExperiment ? 'Sora' : 'Shanice';
  const src = isInVRExperiment
    ? 'https://i.pinimg.com/originals/ab/c5/4a/abc54abd85df131e90ca6b372368b738.jpg'
    : 'https://i.ibb.co/7tGKGvb/shanice.jpg';

  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Avatar
        accessibilityLabel={`${name}, Verified account`}
        name={name}
        size="lg"
        src={src}
        verified
      />
    </Flex>
  );
}

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma for web and mobile web.
Responsive Web
Ready
Component responds to changing viewport sizes in web and mobile web.

Internal documentation

AvatarGroup
AvatarGroup is the ideal component in cases where multiple people/brands need to be displayed.

Edit page on GitHub