Components · Identity
Avatar
Person or entity image with an initials and icon fallback, presence status and stacked groups.
Sizes and fallback
import { Avatar } from '@rookcom/monarch-react';
<Avatar name="Ada Lovelace" size="xs" />
<Avatar name="Grace Hopper" size="sm" />
<Avatar name="Katherine Johnson" />
<Avatar name="Margaret Hamilton" size="lg" shape="square" />
<Avatar name="Rook" size="xl" />Usage examples
Status, numeric size and token palette
import { Avatar } from '@rookcom/monarch-react';
<Avatar name="Ada Lovelace" status="online" />
<Avatar name="Grace Hopper" status="away" size={28} />
<Avatar name="Katherine Johnson" status="busy" palette="tokens" />
<Avatar name="Margaret Hamilton" status="offline" palette="tokens" seed="user_4" />
<Avatar name="Northfield Labs" shape="square" fallback="icon" size="lg" />Group with overflow
import { Avatar, AvatarGroup } from '@rookcom/monarch-react';
<AvatarGroup label="Assignees" max={3}>
<Avatar name="Ada Lovelace" />
<Avatar name="Grace Hopper" />
<Avatar name="Katherine Johnson" />
<Avatar name="Margaret Hamilton" />
<Avatar name="Hedy Lamarr" />
</AvatarGroup>Purpose
A person or entity image, falling back to initials on a colour stable per seed, then to an icon. AvatarGroup stacks several with a “+N” overflow.
Use when
- Identifying a person, workspace, organisation or brand next to their content.
- Showing several assignees or participants in little space (AvatarGroup).
Avoid when
- A decorative icon: use the icon directly.
- A selectable list of people: use a picker (assignee-picker, entity-picker).
Design principles
- The same name always gets the same fallback colour, everywhere.
- Fallback colours keep AA contrast for every hue in light and dark themes (tested).
- Set
decorativewhen the name is already visible next to the avatar. - Circles are people; squares are workspaces, organisations and brands.
- Presence is never colour alone: the status is part of the accessible name.
API reference
import { Avatar, AvatarGroup, avatarPaletteIndex, initials } from '@rookcom/monarch-react';| Export | Kind | Rendering | Root class |
|---|---|---|---|
Avatar | component | client | .mn-color-data- |
AvatarGroup | component | client | .mn-color-data- |
avatarPaletteIndex | utility | client | – |
initials | utility | client | – |
initials(name) is exported: first and last word initials, upper-cased, "?" for an empty name.
avatarPaletteIndex(seed) returns the data token (1–5) a seed maps to with palette="tokens", for matching colours elsewhere.
Avatar and AvatarGroup forward their refs to the root <span> and <div>.
Generated from the TypeScript declarations of packages/react/src/components/identity/avatar.
Properties
Avatar
A person or entity image with a fallback chain: image, then initials on a colour stable per seed, then an icon.
| Prop | Type | Description |
|---|---|---|
name required | string | Person or entity name. Used for the image alt text and the initials fallback. |
className | string | |
decorative | boolean | Set when a visible name sits next to the avatar, so screen readers do not hear the name twice. |
fallback | "icon" | "initials" | What to show when there is no image: `initials` (default), or `icon` for entities such as an organisation without a logo. Initials also fall back to the icon when the name has no letters. |
icon | ReactNode | Icon for the `icon` fallback. Default: a neutral person glyph. Decorative. |
id | string | |
palette | "hue" | "tokens" | Fallback colour source. `hue` (default) derives a soft colour from the seed; `tokens` picks one of the five `--mn-color-data-*` tokens, so the colour follows the theme and contrast mode. |
seed | string | Hashed to pick the fallback colour. Default `name`. Pass a stable id so a renamed person keeps their colour. |
shape | "circle" | "square" | `circle` for people; `square` for workspaces, organisations and brands. |
size | number | AvatarSize | A preset, or a number in CSS pixels (e.g. `28`) for sizes between the presets. |
src | string | null | |
status | AvatarStatus | Presence dot. Its text alternative is added to the accessible name. |
statusLabel | string | Text alternative for `status`, e.g. a translated "Online". Default: the English status name. |
AvatarGroup
Overlapping stack of avatars with a "+N" overflow tile. Each avatar keeps its own name, so the group reads as a list of people.
| Prop | Type | Description |
|---|---|---|
children required | ReactNode | `Avatar` elements. |
label required | string | Names the group for assistive technology, e.g. "Assignees". |
className | string | |
id | string | |
max | number | Show at most this many avatars, then a "+N" tile. Default: show all. |
overflowLabel | ((hidden: number) => string) | Text alternative for the "+N" tile. Default `(n) => \`${n} more\``. |
shape | "circle" | "square" | Applied to every avatar that does not set its own shape. |
size | number | AvatarSize | Applied to every avatar that does not set its own size. |
Variants
| Prop | Values | Description |
|---|---|---|
size | 'xs''sm''md''lg''xl' | 1.25–3.5rem. Default md (2rem). Exposed as data-size. A number is a size in CSS pixels (data-size="custom", --mn-avatar-size). |
shape | 'circle''square' | Default circle; square for organisations and brands. Exposed as data-shape. |
palette | 'hue''tokens' | hue (default) derives a soft colour from the seed; tokens uses one of the five --mn-color-data-* tokens (data-palette). |
status | 'online''away''busy''offline' | Presence dot at the bottom end edge (data-status). |
fallback | 'initials''icon' | What shows without an image. icon suits organisations without a logo. |
States
| State | Exposed as | Behaviour |
|---|---|---|
| Image | – | Shows src when given and it loads. |
| Initials fallback | – | Shows initials when there is no src or the image fails to load. A new src is tried again. |
| Icon fallback | – | Shows icon (default a person glyph) with fallback="icon" or when the name has no letters or digits. |
| Status | data-status | Online, away, busy (filled dot) or offline (ring). |
| Overflow | – | AvatarGroup shows max avatars and a “+N” tile; it never shows “+1”, it shows that avatar instead. |
Interaction behaviour
- None. If the image errors, the avatar switches to initials (or the icon).
- AvatarGroup applies its
sizeandshapeto children that do not set their own.
Keyboard support
Not interactive, so there is no keyboard behaviour.
Accessibility
- Role
- img (or aria-hidden when decorative); AvatarGroup is a labelled group
- Accessible name
namebecomesaria-label, plus the status: “Ada Lovelace (Online)”. AvatarGroup requireslabel.
- The inner image has empty alt and the initials are
aria-hidden, so the name is announced once. decorativehides the avatar, its status included, when the name is printed beside it.- The “+N” tile is an image named by
overflowLabel(default “N more”). - Avatars are not focusable; when an avatar alone identifies a person (board cards), keep it labelled (not
decorative) and, for sighted users, add a Tooltip on the focusable card or link around it.
Responsive behaviour
- Fixed size per
size; no breakpoints. AvatarGroup overlaps by a quarter of the avatar size and does not wrap.
Theme support
- Fallback colours are derived from a per-seed hue (
--mn-avatar-hue) with separate light and dark lightness values. palette="tokens"tints the surface with a data token and mixes it into the default text colour (AA in light and dark, tested); in more-contrast mode the text is the default text colour.- Status dots use the success, warning and danger solid tokens with a surface-coloured ring.
Do and don't
Do
- Always pass the real
name; it drives the label and initials. - Pass a stable
seed(a user id) so the colour survives a rename. - Translate
statusLabelandoverflowLabelwith the rest of the interface.
Don't
- Do not leave
decorativeoff when the name is printed beside the avatar. - Do not use status colours for anything other than presence.
Related components
- MemberRow: Planned row with avatar, name and role.
- AssigneePicker: Planned picker showing avatars.
- Tooltip: Names an avatar shown without its name.
Dependencies
| Kind | Depends on |
|---|---|
| npm packages | react |
| Monarch components | None |
Testing coverage
- Computes initials.
- Falls back to initials when the image fails.
- Fallback colours keep AA contrast for every hue.
- Decorative avatars are aria-hidden.
- Default markup is unchanged from 0.3.
- Numeric size, seed colour, token palette mapping and its AA contrast.
- Fallback chain image → initials → icon, and retry on a new
src. - Status is added to the accessible name, with a custom label.
- AvatarGroup: labelled group,
maxwith “+N”, no “+1”, size inheritance, custom overflow label, no tab stop.
| Check | Covered |
|---|---|
| Axe in jsdom | Yes |
| Server rendering | Yes |
| Browser suites | Visual baselines: /__gallery |
Tests: packages/react/src/components/identity/avatar