Skip to main content
Skip to Content

Identifies a person, organization, or workspace with an image, initials, or an icon

Installation

  1. Install the package

    terminal
    npm install @hashintel/ds-components
  2. Import the component

    app.tsx
    import { Avatar } from "@hashintel/ds-components";
    
    export const TeammateAvatar = () => (
      <Avatar
        alt="Chris Feijoo"
        src="https://avatars.githubusercontent.com/u/2991143?v=4"
        placeholder={{ initials: "CF" }}
      />
    );

When to use

  • Do: Use Avatar to show who something belongs to: a comment's author, an entity's last editor, the members of a web.
  • Do: Use shape="square" for non-person subjects — organizations, webs, services — and the default circle for people.
  • Do: Use onClick or href when pressing the avatar opens the profile or workspace it names.

When not to use

  • Don't: Don't use Avatar for content or decorative imagery — use a plain <img>; an Avatar always announces itself as an image named by alt.
  • Don't: Don't overlap avatars by hand to show a set of people — use AvatarGroup, which handles stacking, hover, and the "+N" overflow badge.
  • Don't: Don't use Avatar as a tile for pictograms that don't identify anyone — use Icon.

Examples

Basic

alt names the subject and becomes the accessible name; placeholder is required because it shows while the image loads and whenever src is missing or fails.

Placeholders

Pick the placeholder that best identifies the subject: initials for anyone with a name, icon where there is no particular person, and custom for an arbitrary node such as an emoji. Initials are capped at two characters and uppercased.

Image fallback

A failed image falls back to the placeholder — there is no broken-image state. Assigning a new src retries, even for a URL that failed before.

Sizes

Five fixed sizes run from xxs to lg; md is the default. Use xxs–sm in dense chrome such as table rows and comment threads, and lg for profile headers.

Custom size

size="custom" hands the scale to a --avatar-size you set via className — the box, border width, corner radius, and placeholder type all derive from that one variable.

styles.ts
import { css } from "@hashintel/ds-helpers/css";

import { Avatar } from "@hashintel/ds-components";

const profileHeroSize = css({ "--avatar-size": "96px" });

export const ProfileHero = () => (
  <Avatar
    size="custom"
    className={profileHeroSize}
    alt="Chris Feijoo"
    placeholder={{ initials: "CF" }}
  />
);

Shapes

Use circle (the default) for people and square for everything else — organizations, webs, services. The square's corner radius scales with the avatar's size.

Tones

Tone only styles the placeholder — once an image loads, every tone shows the same neutral fill and border.

With tooltip

Wrap the avatar in a Tooltip to reveal the name on hover and focus when no visible label sits beside it. The tooltip also makes a static avatar keyboard-focusable, so the name isn't hover-only.

app.tsx
import { Avatar, Tooltip } from "@hashintel/ds-components";

export const AssigneeAvatar = () => (
  <Tooltip content="Chris Feijoo">
    <Avatar size="sm" alt="Chris Feijoo" placeholder={{ initials: "CF" }} />
  </Tooltip>
);

Behavior

  • The image loads hidden behind the placeholder and only appears once complete — there is never an empty box, and already-cached images show immediately.
  • Images draw on a white backing, so transparent logos don't pick up the tone fill; they can't be dragged and send no referrer.
  • Initials longer than two characters are truncated, and all initials render uppercase.

Content

  • Write alt as the subject's name as it appears elsewhere in the product: "Chris Feijoo", "HASH". Append state only when the avatar shows it: "Chris Feijoo (online)".
  • Give people two initials (first and last name) and organizations or webs their first letter.

Accessibility

What Avatar provides

  • A static avatar renders role="img" named by alt; the inner image is decorative (empty alt), so screen readers announce the name exactly once.
  • With onClick or href it renders a native <button> or <a>, also named by alt, with a visible focus ring.

What you must do

  • alt is the entire accessible name — make it identify the subject, and, for interactive avatars, where pressing leads.
  • Keep a meaningful alt on interactive avatars even when the name is shown beside them — the adjacent text isn't associated with the button or link. For a non-interactive avatar that's redundant with an adjacent name, pass aria-hidden instead of emptying alt.

API reference

PropTypeDescription
alt
string
placeholder
{ initials: string; } |⁠ { icon: "function" |⁠ "filter" |⁠ "at" |⁠ "circle" |⁠ "square" |⁠ "error" |⁠ "warning" |⁠ "arrowDown" |⁠ "arrowLeft" |⁠ "arrowRight" |⁠ "arrowTrendDown" |⁠ "arrowTrendUp" |⁠ ... 128 more ... |⁠ "zoomOut"; } |⁠ { ...; }
src
string
size
"xxs" |⁠ "xs" |⁠ "sm" |⁠ "md" |⁠ "lg" |⁠ "custom"
default: "md"
shape
"circle" |⁠ "square"
default: "circle"
tone
"neutral" |⁠ "brand"
default: "neutral"
onClick
MouseEventHandler<Element>
href
string
target
"_blank"

Was this page helpful?

On this page