Skip to main content

Avatar

Avatar is a visual identifier that represents a person or team, such as a profile owner or a project's collaborators.

Import

import { Avatar } from '@vortexlabs/vortex';
import type { AvatarProps } from '@vortexlabs/vortex';

Other links

Storybook
VX
<Avatar
  initials="VX"
  size="lg"
  tone="neutral"
  variant="solid"
  rounded={false}
/>

Features

  • Displays an image, initials, or an icon.
  • Supports different variants.
  • Supports color tones for initials and icons.
  • Pairs avatars with names and supporting text.
  • Displays multiple avatars in overlapping groups.
  • Shows online status; image avatars also support verified badges.
Reference Links
WAI images tutorial

Content

Avatar can render an image, initials, or an icon. Provide alt for image and icon avatars.

VX
import { Avatar } from "@vortexlabs/vortex";
import { Hexagon } from "@vortexlabs/vortex-icons";

const Example = () => {
return (
  <>
    <Avatar src="https://pbs.twimg.com/profile_images/1536360219147907073/RX64EVOE_400x400.jpg" alt="Bonnie Hong" />
    <Avatar initials="VX" tone="primary" />
    <Avatar icon={Hexagon} tone="neutral" alt="Vortex workspace" />
  </>
);
};

export default Example;

Pass initials or icon alongside src as a fallback. When the image fails to load, the avatar shows the fallback instead.

<Avatar src="/missing-avatar.jpg" initials="AL" alt="Ada Lovelace" />
<Avatar src="/missing-avatar.jpg" icon={Hexagon} alt="Vortex workspace" />

Sizes

Avatar is available in six sizes: xs, sm, md, lg, xl, and 2xl. The default size is lg.

VX
VX
VX
VX
VX
VX
<Avatar initials="VX" tone="primary" size="xs" />
<Avatar initials="VX" tone="primary" size="sm" />
<Avatar initials="VX" tone="primary" size="md" />
<Avatar initials="VX" tone="primary" size="lg" />
<Avatar initials="VX" tone="primary" size="xl" />
<Avatar initials="VX" tone="primary" size="2xl" />

Avatar can adapt its size responsively according to the breakpoint.

<Avatar
  src="https://pbs.twimg.com/profile_images/1936983814116638720/G3kbEPZY_400x400.jpg"
  alt="Ugi Stelmokaitis"
  size={{ xs: "sm", sm: "2xl" }}
/>

Shape

Avatar is square by default. Use rounded to render a circular avatar.

VX
VX
<Avatar src="https://pbs.twimg.com/profile_images/1936983814116638720/G3kbEPZY_400x400.jpg" alt="Ugi Stelmokaitis" />
<Avatar rounded src="https://pbs.twimg.com/profile_images/1936983814116638720/G3kbEPZY_400x400.jpg" alt="Ugi Stelmokaitis" />
<Avatar initials="VX" tone="neutral" />
<Avatar rounded initials="VX" tone="neutral" />

Variants

Avatar has two visual styles: solid and subtle. The default variant is solid.

VX
VX
<Avatar initials="VX" tone="primary" variant="solid" />
<Avatar initials="VX" tone="primary" variant="subtle" />

Tone

Use tone to set the color for initials and icon avatars. The default tone is neutral.

VX
VX
VX
VX
VX
VX
VX
VX
VX
VX
VX
VX
<Avatar initials="VX" tone="neutral" />
<Avatar initials="VX" tone="primary" />
<Avatar initials="VX" tone="info" />
<Avatar initials="VX" tone="success" />
<Avatar initials="VX" tone="warning" />
<Avatar initials="VX" tone="critical" />

<Avatar initials="VX" tone="neutral" variant="subtle" />
<Avatar initials="VX" tone="primary" variant="subtle" />
<Avatar initials="VX" tone="info" variant="subtle" />
<Avatar initials="VX" tone="success" variant="subtle" />
<Avatar initials="VX" tone="warning" variant="subtle" />
<Avatar initials="VX" tone="critical" variant="subtle" />

Online Indicator

Use onlineIndicator to show presence on an avatar. The indicator is visual only, so include the status in alt. Initials avatars with an indicator require alt.

<Avatar src="https://pbs.twimg.com/profile_images/1936983814116638720/G3kbEPZY_400x400.jpg" alt="Ugi Stelmokaitis, online" onlineIndicator />
<Avatar rounded src="https://pbs.twimg.com/profile_images/1936983814116638720/G3kbEPZY_400x400.jpg" alt="Ugi Stelmokaitis, online" onlineIndicator />

Verified

Use verified to show a verified badge on image avatars. Include the status in alt.

<Avatar src="https://pbs.twimg.com/profile_images/1936983814116638720/G3kbEPZY_400x400.jpg" alt="Ugi Stelmokaitis, verified" verified />
<Avatar rounded src="https://pbs.twimg.com/profile_images/1936983814116638720/G3kbEPZY_400x400.jpg" alt="Ugi Stelmokaitis, verified" verified />

Composition

Use Avatar.Root to pair an avatar with a name, and Avatar.Group to show several people together. Inside either one, use Avatar.Item instead of Avatar; rendering a part outside its parent throws an error.

Avatar.Root

Use Avatar.Root to show a name and supporting text next to an avatar. Set size on the root to size the avatar and text together, from xs to xl.

To stack the text below the avatar, set direction="column" on the root and align="center" on Avatar.Content.

Avatar.Title already names the person, so the item needs no alt and is hidden from assistive technology. If the item shows a status, add it to alt or Avatar.HelperText.

Bonnie Hong

Principal Product Designer

Ugi Stelmokaitis

Design Engineer

<Avatar.Root size="lg">
  <Avatar.Item src="https://pbs.twimg.com/profile_images/1536360219147907073/RX64EVOE_400x400.jpg" />
  <Avatar.Content>
      <Avatar.Title>Bonnie Hong</Avatar.Title>
      <Avatar.HelperText>Principal Product Designer</Avatar.HelperText>
  </Avatar.Content>
</Avatar.Root>

<Avatar.Root size="md" direction="column">
  <Avatar.Item rounded initials="US" tone="primary" />
  <Avatar.Content align="center">
      <Avatar.Title>Ugi Stelmokaitis</Avatar.Title>
      <Avatar.HelperText>Design Engineer</Avatar.HelperText>
  </Avatar.Content>
</Avatar.Root>

Avatar.Group

Use Avatar.Group to show people as an overlapping list, such as reviewers. Name the list with ariaLabel, and give each image, icon, and online item an alt, since no names are shown.

  • AL
import { Avatar } from "@vortexlabs/vortex";
import { Hexagon } from "@vortexlabs/vortex-icons";

const Example = () => {
return (
  <Avatar.Group ariaLabel="Reviewers" rounded>
    <Avatar.Item src="https://pbs.twimg.com/profile_images/1536360219147907073/RX64EVOE_400x400.jpg" alt="Bonnie Hong, online" onlineIndicator />
    <Avatar.Item src="https://pbs.twimg.com/profile_images/1936983814116638720/G3kbEPZY_400x400.jpg" alt="Ugi Stelmokaitis" />
    <Avatar.Item initials="AL" tone="primary" variant="subtle" />
    <Avatar.Item icon={Hexagon} tone="neutral" alt="Vortex workspace" />
  </Avatar.Group>
);
};

export default Example;

Limit

Use limit to set how many avatars are shown. The remaining avatars are replaced by a +N avatar with the hidden count.

  • AL
  • +2
<Avatar.Group ariaLabel="Project members" limit={3}>
  <Avatar.Item src="https://pbs.twimg.com/profile_images/1536360219147907073/RX64EVOE_400x400.jpg" alt="Bonnie Hong" />
  <Avatar.Item src="https://pbs.twimg.com/profile_images/1936983814116638720/G3kbEPZY_400x400.jpg" alt="Ugi Stelmokaitis" />
  <Avatar.Item initials="AL" tone="primary" />
  <Avatar.Item initials="GH" tone="success" />
  <Avatar.Item initials="MK" tone="warning" />
</Avatar.Group>

Group Sizes

Avatar Group is available in three sizes: xs, sm, and md. The default size is md. size and rounded apply to every avatar in the group; an item's own rounded takes precedence. These examples use the items from Limit.

  • AL
  • +2
  • AL
  • +2
  • AL
  • +2
<Avatar.Group ariaLabel="Project members" size="xs" limit={3} rounded>…</Avatar.Group>
<Avatar.Group ariaLabel="Project members" size="sm" limit={3} rounded>…</Avatar.Group>
<Avatar.Group ariaLabel="Project members" size="md" limit={3} rounded>…</Avatar.Group>

Accessibility

Description
Provide alt for image and icon avatars. Include any status shown by onlineIndicator or verified, such as "Ada Lovelace, online".
Use alt="" when a visible name is next to the avatar; the avatar is then hidden from assistive technology. Avatar.Item inside Avatar.Root is hidden by default.
Provide alt when an initials avatar has onlineIndicator; otherwise, its initials are read as text and alt is not supported.
Provide ariaLabel to name the Avatar.Group list. The +N avatar is read as its text, so hidden names are not announced.