Identifies a person, organization, or workspace with an image, initials, or an icon
Installation
-
Install the package
terminal npm install @hashintel/ds-components -
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
onClickorhrefwhen 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 byalt. - 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.
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.
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
altas 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 byalt; the inner image is decorative (emptyalt), so screen readers announce the name exactly once. - With
onClickorhrefit renders a native<button>or<a>, also named byalt, with a visible focus ring.
What you must do
altis the entire accessible name — make it identify the subject, and, for interactive avatars, where pressing leads.- Keep a meaningful
alton 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, passaria-hiddeninstead of emptyingalt.
API reference
| Prop | Type | Description |
|---|---|---|
| alt | string | Accessible description of the image, e.g. "Firstname Lastname", "Organization", "Shortname (online)". |
| placeholder | { initials: string; } | { icon: "function" | "filter" | "at" | "circle" | "square" | "error" | "warning" | "arrowDown" | "arrowLeft" | "arrowRight" | "arrowTrendDown" | "arrowTrendUp" | ... 128 more ... | "zoomOut"; } | { ...; } | Content shown when no image is loaded or defined: initials (truncated to two characters), a named icon, or custom content. |
| src | string | Image source URL |
| 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?