Avatar · LoamUI

Import

import { Avatar, AvatarGroup } from "@loamui/core";

Usage

Every example has a CSStab. That’s the real, complete stylesheet for the component: plain, static CSS, with nothing running in the browser.

Image

Pass a src to render a cover-fit image.

Initials

With no image, initials are derived from name. There is no color prop: the initials background answers the surrounding --loam-context region (a style query is answered by ancestors, never by the declaring element itself), exactly like Badge. Wrap a single avatar in a one-element span, or let it inherit from a larger region. See the Contextualism guide.

JDAOSR

Group

AvatarGroup overlaps children with a surface-colored ring.

JDSRAO+5

Guidance

When to use it

To identify a person next to something they did: a comment, an assignee, a row in a member list.
With AvatarGroup, to show a set of participants compactly where listing every name would not fit.

When not to

For arbitrary images. The image is cover-cropped into a fixed square or circle, which is right for faces and wrong for logos, screenshots or product photos; use a plain <img>.
As a click target. Avatar renders a <span>; if it should open a profile, wrap it in a real link or button rather than adding onClick to it.

Accessibility

With src, a real <img> is rendered and its alt falls back to name: pass the name and the image announces the person.
Without an image, the root becomes role="img" with aria-label from name (or alt): screen readers hear the full name (“Jane Doe”), never the raw initials (“JD”).
A bare <Avatar /> with no name from any source is treated as decorative automatically (aria-hidden, no role). An identifying avatar must be given a name, an alt, or an aria-label.
When the name is visibly printed next to the avatar, pass aria-hidden so assistive tech does not read the same name twice.
The fallback glyph is aria-hidden and focusable="false": it is decoration; identity always comes from the name/alt wiring above.

How it works

The name is the API

Pass the person's full name and everything derives from it: the initials (first and last word, uppercased), the image alt when you give a src, and the aria-label when you do not. One prop keeps what sighted users see and what screen readers hear describing the same person.

Identifying or decorative: decide which

An avatar identifies when it is the only place the person appears; it decorates when their name is printed right beside it. A decorative avatar should be aria-hidden so the name is not announced twice; an identifying one must have a name (or alt), never neither.

Props

Status is not a prop: it comes from the surrounding --loam-context region. See the Contextualism guide.

Prop	Type	Default	Description
`src`	`string`	—	Image source. When set, renders an <img>.
`alt`	`string`	—	Alt text for the image (falls back to name).
`name`	`string`	—	Person's name; used for initials and as image alt.
`children`	`ReactNode`	—	Custom content; overrides the derived image/initials/glyph.
`...others`	`SpanHTMLAttributes`	—	All native <span> props are forwarded.

Parts

`AvatarGroup`

Overlaps a row of avatars with a surface-coloured ring; all native <div> props are forwarded.