Avatar·component·@astryxdesign/core

Avatar

Displays a user avatar with image, initials fallback, and optional status indicator.

Open in Playground @astryxdesign/core/Avatar

Showcases and examples

8 documented examples

Avatar

Avatars at every size with an image, initials fallback, and a status dot. A quick visual reference for choosing the right size.

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · avatar-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {Avatar, AvatarStatusDot} from '@astryxdesign/core/Avatar';
import {Stack} from '@astryxdesign/core/Layout';

export default function AvatarShowcase() {
  return (
    <Stack direction="horizontal" gap={4} vAlign="center">
      <Avatar
        src="/template-assets/DATA-Ana-Thomas.png"
        name="Ana Thomas"
        size="xl"
        status={<AvatarStatusDot variant="success" label="Online" />}
      />
      <Avatar
        src="/template-assets/DATA-Drew-Young.png"
        name="Drew Young"
        size="xl"
      />
      <Avatar
        src="/template-assets/DATA-Jihoo-Song.png"
        name="Jihoo Song"
        size="xl"
      />
      <Avatar
        src="/template-assets/DATA-Nam-Tran.png"
        name="Nam Tran"
        size="xl"
        status={<AvatarStatusDot variant="error" label="Busy" />}
      />
    </Stack>
  );
}

Usage

Avatar represents a person or team with a profile photo, initials, or a default icon. Use it in comment headers, contact lists, chat messages, user cards, and anywhere you need to identify someone visually.

Always pass a name so the avatar can show initials if the photo fails to load, and so screen readers can announce who it represents.
Pick a size that matches the context: xsm or sm for inline mentions, md or lg for lists and cards, xl for profile headers.
Add a status dot when knowing someone's availability matters, like in chat or team views.
When wrapping an Avatar in your own Tooltip or HoverCard, set tooltip={false} so the built-in name tooltip does not overlap yours.
Give every interactive avatar (href or onClick) a name or alt. It is the control's accessible name, and it warns in development when it is missing.
Rely on a status label to name an interactive avatar. "Online" says nothing about where the link goes.
Use Avatar for logos, product images, or anything that isn't a person or team. Use an image or icon instead.
Use xstyle or className to override shape. Use the shape prop instead so themes can control it globally.

Typed props

Prop	Type and behavior
`src`	`string` Primary image source URL.
`fallbackSrc`	`string` Fallback image when primary fails.
`name`	`string` User name for initials and alt text.
`alt`	`string` Alt text (falls back to name).
`size`	`'xsm' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number` · default 'md' Avatar size. Use a named size ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or a numeric pixel value. Avatar shares Icon's abbreviated scale, but its tiers are larger because avatars align with media rather than glyphs. Inside an AvatarGroup the group's size wins and this prop is ignored.
`shape`	`'circle' \| 'rounded' \| 'square'` · default 'circle' Shape variant of the avatar. 'circle' (default) stays fully round. 'rounded' uses the element radius token so it matches UI corner rounding and can be set globally via theme. 'square' has no radius. Status dot positioning adapts automatically: 4-o'clock on circle, bottom-right corner on rounded/square.
`status`	`ReactNode` Corner content for status indicators. AvatarStatusDot reports its `label` to the avatar, which composes it into the accessible name (e.g. "Jane Doe, Online") so screen readers announce the status. Reporting goes through context, so it still works when the dot sits inside a wrapper component of your own. Slot: AvatarStatusDot
`tooltip`	`string \| boolean` · default true Tooltip shown on hover and keyboard focus. Omitted or true shows the avatar's name; a string shows that text instead; false shows no tooltip. Not auto-disabled when wrapped in your own Tooltip/HoverCard. Set tooltip={false} if you supply your own overlay. No tooltip is shown when tooltip is true/omitted and there is no name.
`href`	`string` When set, the avatar renders as an interactive link (`<a>` or a custom link component) pointing here. This follows the same element-swap rule as Button. Requires a meaningful accessible name via `alt` or `name`: an interactive avatar without one warns in development. Inside an AvatarGroup, interactive avatars share a single Tab stop and are reached with arrow keys.
`as`	`ElementType` Custom link component used when `href` is set (e.g. `next/link`). Overrides the provider-level LinkProvider default. Only applies with `href`.
`target`	`string` Link target attribute. Only applies with `href`.
`rel`	`string` Link rel attribute. Only applies with `href`.
`onClick`	`(e: MouseEvent) => void` Click handler. When set without `href`, the avatar renders as a focusable `<button type="button">`. Requires a meaningful accessible name via `alt` or `name`: an interactive avatar without one warns in development.

Anatomy

Photo · optional

The profile image, loaded from the src URL. Shown when available.

Initials · optional

The first letter, digit or emoji of the first and last words of the name; punctuation is skipped. Shown when no photo is available. A name with no letters, digits or emoji shows the default icon instead.

Default icon · optional

A generic person silhouette. Shown when there is no photo or name.

Status dot · optional

A small indicator in the bottom-right corner showing availability (online, away, busy). Each variant pairs colour with a distinct shape so status does not rely on colour alone.

Theming

Targets

astryx-avatar

Visual props: size, shape

astryx-avatar-fallback

Visual props: size

astryx-avatar-status-dot

Visual props: variant

astryx-avatar-status-dot-glyph

Visual props: shape

Variables

--_avatar-group-overlap · private

Negative inline offset applied to every avatar stacked in an AvatarGroup; the group pads its start edge by the same amount so the first avatar stays inside it. Set from the group size; a more negative value tightens the stack.

Default: set at runtime from the group avatar size (px)

--_avatar-radius · private

Border radius of the avatar wrapper, content, focus ring, and the AvatarGroupOverflow "+N" chip. Set per shape variant by shapeStyles.

Default: var(--radius-full)

Derived properties

borderRadius

Uses --_avatar-radius.