All components (204)

Avatar

Surfaces · Avatar · .amset-avatar

What it is and when to use it

A person's face, or their initials. If there is no photo, if it fails to load, or while it is arriving, the initials are shown: never a blank gap or a broken icon. When the photo loads, it fades in on top.

When to use it

Next to whoever writes, signs or has something assigned. If the name is already written next to it, use decorative, so it is not read twice.
The initials come out on their own: the first of the first name and the first of the last surname, skipping particles ("María de la Fuente" is MF). If the name has no letters, the person icon is shown. content puts something else in its place (an icon).
Without tone (default), a stable color is derived from the name: the same name always gets the same color. tone fixes it with any of the eight common tones.
variant: soft (light background of the tone, default) or solid (strong fill with white initials). shape: circle (default) or square.
state draws the presence dot: inline (online), away, busy or offline (a hollow ring, not a gray dot).
onError reports the photo's address if it cannot be loaded.

When not to

Several people together: AvatarGroup, which stacks them with a "+N" that says who is missing.
The photo of a product or an attachment: Thumbnail.

Keyboard: it is neither focusable nor interactive.

Accessibility: it is an image (role="img") with the name as alternative text. With state, the status goes in the name ("Marta Ruiz (busy)"), not only in the color of the dot. The photo has alt="", because the container already provides the name. decorative removes it from the accessibility tree (aria-hidden).

Fine-tuning: CSS variables --amset-avatar-*: -size (the side: 24, 30, 36, 48 or 64 px depending on size, from xs to xl), -text (the font size of the initials), -radius (that of the square) and -ring, the color of the border that separates it from what is behind it (the status dot and the neighbors in a group): change it if the avatar sits on something that is not the surface. The tone colors go in --amset-avatar-tone, -tone-soft, -tone-solid and -tone-ink.

What it looks like

Ada LovelaceBilling · online

Grace HopperWarehouse · away

Alan TuringSupport · busy

<Avatar name="Ada Lovelace" size="xs" />
<Avatar name="Grace Hopper" size="sm" tone="success" />
<Avatar name="Support team" shape="square" size="lg" />

<ItemGroup label="Who is on the team" separated>
  <Item
    title="Ada Lovelace"
    description="Billing · online"
    media={<Avatar name="Ada Lovelace" size="sm" state="online" />}
    mediaKind="avatar"
  />
</ItemGroup>

Props

Import it with import { Avatar } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`name`required	`string`	The initials and the alternative text come from here. Required.
`className`	`string`	Merged with the library classes; it does not replace them.
`content`	`ReactNode`	Instead of the initials: an icon, an emoji, a custom letter.
`decorative`	`boolean`	For when the name is already written next to it: the avatar stops being announced so the same thing is not read twice.
`onError`	`(src: string) => void`	Notifies that the photo in `src` has not loaded, with its address. The avatar already falls back to initials on its own: this is for whoever wants to retry with another address or keep a record. A new photo tries again.
`shape`	`AvatarShape`	—
`size`	`"sm" \| "md" \| "lg" \| "xs" \| "xl"`	From 24 to 64 px: `xs`, `sm`, `md` (36, default), `lg` and `xl`.
`src`	`string`	—
`state`	`AvatarStatus`	Presence dot in the corner. It carries its text, not only the color.
`tone`	`"neutral" \| "accent" \| "secondary" \| "tertiary" \| "info" \| "success" \| "warning" \| "error"`	Without a tone, a stable color is derived from the name (`tonoDeNombre`).
`variant`	`AvatarVariant`	—

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

CSS variables

These CSS variables are how you adapt it. Declare them on the component's selector, not on :root: the stylesheet redeclares them in the rule itself, and a declaration on the same element always wins.

Variable	Default
`--amset-avatar-tone`	`var(--amset-ink)`
`--amset-avatar-tone-soft`	`var(--amset-divider)`
`--amset-avatar-tone-solid`	`var(--amset-ink)`
`--amset-avatar-tone-ink`	`var(--amset-surface)`
`--amset-avatar-size`	`2.25rem`
`--amset-avatar-text`	`var(--amset-text-base)`
`--amset-avatar-radius`	`var(--amset-radius)`
`--amset-avatar-ring`	`var(--amset-surface)`
`--amset-avatar-background`	`var(--amset-avatar-tone-soft)`
`--amset-avatar-ink`	`var(--amset-avatar-tone)`

How to change it

.amset-avatar {
  --amset-avatar-tone: ...;
  --amset-avatar-tone-soft: ...;
}

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: