Avatar

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

• Show a user image, with initials or an SVG as the fallback when the image is missing or fails. Set the alt text or Root name so a nearby name isn't announced twice. Status is a decorative badge, separate from the image. Expose the actual status through Root's aria-description or adjacent text.
• For things without a picture, such as projects, sessions or hosts, set category={categoryFor(name)}: the same name always gets the same of twelve category hues, as a tint behind initials in ink.
• Status.tone colors the marker as StatusBadge's tones do, and live pulses it while work runs, such as a session working now. Reduced motion keeps it still. Say the state in text too, such as a StatusBadge beside the name. Where there is no avatar, such as beside a group's count, StatusDot is the same dot on its own.

• Don't make the Avatar span itself an account menu. Wrap it in a named button or Popover.Trigger instead.
• Don't pick a category hue by hand or by state. categoryFor keeps one name on one hue across screens; state belongs to Status and StatusBadge.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

Avatar.Root → Image + Fallback(initials or default SVG) + optional Status

Keyboard and accessibility

A static Avatar isn't in the Tab order. Inside a button, the button provides focus and behavior.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { Avatar, categoryFor } from '@surflane/ui'

<Avatar.Root role='img' aria-label='Preview user' size='default'>
  <Avatar.Image src='/profile.png' alt='' />
  <Avatar.Fallback aria-hidden='true'>CG</Avatar.Fallback>
</Avatar.Root>

// A project's mark: its hue from its name, and a pulse while it works.
<Avatar.Root category={categoryFor('platform-api')} aria-hidden='true'>
  <Avatar.Fallback>PA</Avatar.Fallback>
  <Avatar.Status tone='progress' live />
</Avatar.Root>

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens