Avatar
A photo (alt empty: the name sits beside it) or initials. Decorative either way.
import { Avatar } from '@ergasti/bricks';Examples
Initials and sizes
With no picture an avatar draws the name's initials on a tone chosen by seed, so the same person keeps the same colour.
Code
import { Avatar } from '@ergasti/bricks';
function Sizes() {
return (
<div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
<Avatar name="Laila Saeed" seed={0} size="sm" />
<Avatar name="Karim Hosny" seed={1} />
<Avatar name="Salma Hosny" seed={2} size="lg" />
<Avatar name="سارة علي" seed={3} size="lg" />
</div>
);
}Pictures
src replaces the initials; if the picture fails to load the initials come back.
Code
import { Avatar } from '@ergasti/bricks';
import { blocksData } from './sample-data';
function Pictures() {
return (
<div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
<Avatar name="Laila Saeed" seed={0} size="lg" src={blocksData.photo(0)} />
<Avatar name="Broken link" seed={1} size="lg" src="data:image/png;base64,AAAA" />
</div>
);
}Avatar stack
Overlapping avatars with a "+N" count past max; total counts people beyond the faces you have (5 sent, 12 in the group: "+8"); more={false} draws the faces only, where a count is said nearby.
Code
import { AvatarStack } from '@ergasti/bricks';
import { blocksData } from './sample-data';
function Stack() {
const people = ['Laila Saeed', 'Karim Hosny', 'Salma Hosny', 'Mariam Adel', 'Youssef Saeed', 'Hana Hosny', 'Ali Hosny'].map((name, id) => ({ id, name, avatarUrl: blocksData.photo(id) }));
return (
<div style={{ display: 'grid', gap: 12 }}>
<AvatarStack people={people} />
<AvatarStack people={people} max={3} />
<AvatarStack people={people.slice(0, 5)} total={12} />
<AvatarStack people={people} max={3} more={false} />
</div>
);
}Props
Prop
Type
Design guidance
How the BRICKS design system uses Avatar. Written in docs/content/components/Avatar.md; the props above are read from the code, which wins where the two disagree.
A round person avatar showing a photo or, when there is none, the name's initials on a colour picked from a stable seed; use it beside a person's name in cells, cards and menus.
Avatar is the mock's .av: a circle with Jakarta 800 initials on one of five pastel tone pairs (raspberry, lime, butter, sky, lilac). The same seed (usually the row id) always gets the same pair, so a creator keeps their colour across the dashboard. A photo covers the initials when it loads and falls back to them when it fails. It is always decorative: the name next to it is the accessible text.
Anatomy
- Circle (
span.kit-av,aria-hidden): background and ink from the tone pair. - Initials: first letter of the first and last word, upper-cased; Arabic initials joined by a zero-width non-joiner so they never fuse.
- Photo (
img.kit-av-img, optional):alt="", lazy,object-fit: cover, absolutely over the initials.
Variants
size | Look | When |
|---|---|---|
'sm' | 30px, 11px initials | Dense rows, menus |
'md' (default) | 38px, 13px | Table cells (PersonCell, CreatorCell) |
'lg' | 62px, 19px, 4px card-coloured ring | Creator cards, drawer heads |
Tone pair by seed % 5: 0 --rasp-50/--rasp-d, 1 --lime-50/--olive, 2 --butter/--butter-ink, 3 --sky/--sky-ink, 4 --lilac/--lilac-ink. Inside an AvatarStack it draws at 34px with a 2px ring.
States
| State | Trigger | Look |
|---|---|---|
| Initials | no src | Letters on the tone |
| Photo | src loads | Photo fills the circle |
| Broken photo | src fails (onError) | Falls back to initials for that src; a new src is tried again |
| Single word name | "Nour" | One initial |
| Empty name | "" | Coloured circle only |
Types
Helper exported alongside: initials(name).
Usage
<Avatar name="Laila Saeed" seed={1042} />In a table cell with the name beside it (what PersonCell does for you):
const creator = { id: 1042, name: 'Laila Saeed', handle: 'laila.saeed', avatarUrl: null };
<span style={{ display: 'flex', gap: 10, alignItems: 'center' }}>
<Avatar name={creator.name} seed={creator.id} src={creator.avatarUrl} />
<span><b>{creator.name}</b><br /><span className="kit-sub">@{creator.handle}</span></span>
</span>A creator card head:
<Avatar name="سارة علي" seed={2} size="lg" src="https://cdn.example.com/creators/2.jpg" />Where it appears
- Brand › Creators › My creators table and Find creators cards (via
CreatorCell/FindCreatorCard). - Brand › Home › Top creators this month; Brand › Motivation › leaderboards.
- PR Portal › Creators table, Approvals queue, Audit log, Tiers moves, creator drawer head.
- Sidebar user block. Screens: Creators, Home, PR · Creators, PR · Approvals.
Guidelines
Do
- Pass the person's id as
seedso the colour never changes between screens. - Always render the name as text next to it.
- Use
size="lg"only in card or drawer heads.
Don't
- Don't use it for brands (use
BrandAvatar) or products (useProductThumb). - Don't pass a random or index seed in sortable lists: the colours would shuffle.
RTL and Arabic
- Arabic initials are taken from the Arabic letters and separated by a zero-width non-joiner (U+200C).
- Nothing to mirror.
Tokens
--rasp-50, --rasp-d, --lime-50, --olive, --butter, --butter-ink, --sky, --sky-ink, --lilac, --lilac-ink (tone pairs), --card (lg ring), --font-family-display.
Accessibility
aria-hiddenandalt="": the adjacent name is the accessible text, so a screen reader never hears the name twice.- Initials meet contrast on each tone pair (ink on 50-tint).
- Not focusable.
Found in the source
- ARIA attributes set:
aria-hidden.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
AvatarStack: several overlapping avatars with "+N".PersonCell/CreatorCell: avatar + name + handle for tables.BrandAvatar: the square brand logo tile in the PR Portal.
See also: Button · ButtonLink · CouponChip
Source
src/kit/primitives/Avatar.tsx (line 34) on GitHub.