On this page

Data & status

Avatar released

The picture beside a name, with initials and then a silhouette standing in when there is no picture.

Import@pacit/components/avatar
Selectorpct-avatar

No APG pattern applies, and none is invented — the reasoning is under Accessibility ↓

import { Component } from '@angular/core';
import { PctAvatar } from '@pacit/components/avatar';

/** A name becomes initials; a portrait takes over when you hand one in via `src`. */
@Component({
  selector: 'demo-avatar',
  imports: [PctAvatar],
  styles:
    ':host { display: flex; flex-wrap: wrap; gap: 12px; align-items: center; }',
  template: `
    <pct-avatar name="Ada Lovelace" size="sm" />
    <pct-avatar name="Grace Hopper" />
    <pct-avatar name="Margaret Hamilton" size="lg" />
  `,
})
export class AvatarDemo {}

avatar.demo.ts — the same file runs here and is highlighted under Code

Start here

Usage

One import per component, and the shortest possible use — the package itself is installed once, on the start page.

Import this component

import { PctAvatar } from '@pacit/components/avatar';

Exported	What it is
`PctAvatar`component`pct-avatar`	An avatar: the picture beside a name — and never the name itself.

<pct-avatar name="Ada Lovelace" />

Examples

Every state, running

Each example is the component itself, not a screenshot. Open the code under any of them.

Sizes, and what fills them

A name becomes initials; a src becomes the picture; neither becomes a silhouette. The three sizes ride the library's own axis, so an avatar beside a field lines up.

API

What it reads, and what it writes back

Read from the source at build time — the types, the defaults and the lines of documentation are the library's own.

An avatar: the picture beside a name — and never the name itself.

Inputs

Name	Type	What it does
`name`default `''`	`string`	The name the initials are taken from. It is a SOURCE FOR A DRAWING, not an accessible name — the host is hidden, and the name a user hears belongs to the text or the control beside the picture (0052).
`src`default `''`	`string`	The picture's URL. Empty means none — the initials (or the silhouette) stand instead.
`size`default `config.defaultSize`	`PctSize`	Size on the shared control axis; from the global configuration by default.

Outputs

None of its own. The native events — (click), (focus), the form's submit — are the platform's, and two-way models above carry the rest.

What it writes on the element

The hooks a stylesheet or a test can hold. Stable by contract — the parts inventory gate fails the build when one disappears.

Attribute	Bound to	Note
`class`	`pct-avatar`
`aria-hidden`	`true`	Decoration beside the meaning, like the icon it may fall back to drawing. Nothing below it can take focus and the one image is `alt=""`, so hiding the subtree costs a reader nothing and saves them hearing a name twice (`req-a11y-built-in`, 0052).
`data-pct-size`	`size()`

Styling

Parts to select, tokens to override

Two ways in, both stable. No class names to depend on.

Parts

In a test, PctAvatarHarness from @pacit/components/testing reads a part by the name below and a state by its attribute — the harness gate holds the names to the package.

Part	Selector	What it is
`image`	`[data-pct-part="image"]`	the picture, when a source is given
`initials`	`[data-pct-part="initials"]`	the letters drawn from the name
`silhouette`	`[data-pct-part="silhouette"]`	the placeholder when there is neither

Tokens

Every value the component reads, with the light and the dark default. Override a token at any scope and it cascades like any custom property.

Token	Styles
`--pct-avatar-bg{pct.surface-100}`#f1f5f9 · #1e293b	Background of the avatar.
`--pct-avatar-border{pct.border}`#e2e8f0 · #334155	Edge colour of the avatar.
`--pct-avatar-fg{pct.text}`#0f172a · #ffffff	Text colour of the initials.
`--pct-avatar-font-size{pct.font.size.md}`14px	Font size of the avatar.
`--pct-avatar-font-size-lg{pct.font.size.lg}`16px	Font size of the avatar at size lg.
`--pct-avatar-font-size-sm{pct.font.size.sm}`13px	Font size of the avatar at size sm.
`--pct-avatar-icon-fg{pct.text-muted}`#334155 · #e2e8f0	Text colour of the icon.
`--pct-avatar-radius`999px	Corner radius of the avatar.
`--pct-avatar-size{pct.control.height.md}`36px	Size of the avatar.
`--pct-avatar-size-lg{pct.control.height.lg}`44px	Size of the avatar at size lg.
`--pct-avatar-size-sm{pct.control.height.sm}`28px	Size of the avatar at size sm.

Theming

A brand override in a few declarations. Scope it to a theme attribute, a page or one container — the component never notices.

[data-theme='brand'] {
  --pct-avatar-bg: #0f766e;
  --pct-avatar-fg: #ffffff;
  --pct-avatar-border: #0f766e;
}

Accessibility

Measured, not assumed

Pattern: none — an avatar is decoration, all the way down (0052). The host is aria-hidden="true" outright — the third component after pct-icon and pct-skeleton — because where an avatar stands the name is already text a reader says, and a second announcement is noise. Named in the class JSDoc.

Keyboard

key	effect	test

Empty by design: nothing here can be landed on at all. The subtree is hidden from the accessibility tree, so anything focusable in it would be axe's aria-hidden-focus — apps/sandbox-e2e/src/avatar.spec.ts asks every element in the component to focus itself and counts zero, in three engines, and tools/check-aria.mjs point 8 refuses the general case at build time (req-api-platform).

Evidence

What the repository holds for this component

Read at build time from the tracked snapshots, not typed here.

87.5%mutation score28 of 32 mutants killed

8 × 3e2e cases × enginesplus the shared audits: axe, forced colors, preferences, size, hydration

3colour pairs measuredlight and dark, at every token build

2visual baselinesChromium, the sandbox's own pictures

6elements in the preview0 listeners · 1 render to settle · 2959 µs in jsdom, held exactly but for the clock

Why it is built this way

What the component owns is the fallback chain — image, initials, silhouette, exactly one standing — and initials that are graphemes: the platform's segmenter, because charAt cuts an emoji family or a flag into a broken surrogate half. Both were measured in three engines before anything was written.

Known limitations

It never speaks, and cannot be made to. There is no alt input on purpose — the name belongs to the text or the control beside the picture. A page with truly bare avatars names the control that holds them.
No status dot. Presence is a fact with its own text; a coloured dot as its only channel fails forced colours and screen readers at once. Where status exists it is the page's sentence.
No group/stack. Overflow counts, overlap order and one label for many are a different component's questions; refusing them keeps this one a leaf.
No loading state. The box is token-sized either way, so nothing moves when the image lands; the initials already stand where the picture is late, and they are a better placeholder for a face than motion is.
The initials follow words, not scripts' name orders. First grapheme of first and last whitespace-separated word — a CJK full name written without spaces yields one grapheme, which is also what those scripts' own conventions draw.

pacit

Usage

Every state, running

Sizes, and what fills them

What it reads, and what it writes back

Inputs

Outputs

What it writes on the element

Parts to select, tokens to override

Parts

Tokens

Theming

Measured, not assumed

Keyboard

What is measured, and what is not yet

What the repository holds for this component

Why it is built this way

Known limitations