Components Avatars

Avatars

Round portrait for a user, partner, or organisation. Image served by the avatar API with a deterministic initials fallback so every avatar always renders — no broken squares, no missing alt text.

<koala-avatar>

Canonical

<koala-avatar size="Medium" user-id="@user.Id" first-name="@user.FirstName" last-name="@user.LastName" avatar-version="@user.AvatarVersion" />

Medium size, deterministic initials fallback. The image is served by /api/avatars/{id} with a deterministic initials fallback so it always renders.

Variants

6 variants

Small

size="Small"

Medium

size="Medium"

Large

size="Large"

Photo

has-avatar="true"

Partner

koala-partner-avatar

Organisation

koala-organisation-avatar

States

3 states

Initials fallback

No uploaded image; deterministic initials

Photo

Avatar API returns the uploaded blob

Empty

No name or email; placeholder initials

Props

7 attributes

Attribute	Values	Notes
size	Small, Medium, Large	Defaults to `Small` (w-7). Medium is w-10, Large is w-20.
user-id	Guid	Selects the avatar endpoint at `/api/avatars/{id}`.
first-name / last-name	string	Used for the initials fallback and the `alt` attribute.
email	string	Fallback display name when first/last are missing.
avatar-version	string	Cache-busting key. Blob name when a real image is stored; initials key otherwise.
has-avatar	bool	Back-compat flag; only influences the cache key now.
href	URL	Wraps the image in an Alpine-AJAX anchor with `x-target.push="main"`.

Do & don't

JD Jane Doe

Do Pair the avatar with the person's name when space allows. The fallback initials encode the same identity, so the two never disagree.

Don't Don't square-corner the user avatar. Round corners signal a person; the squared variant is reserved for partner and organisation crests.

Partner avatar

Square-cornered crest with deterministic initials fallback. Used everywhere a partner is named — sidebar header, switcher menu, quote rows, branch lists.

<koala-partner-avatar>

<koala-partner-avatar size="Medium" partner-id="@partner.Id" name="@partner.Name" avatar-version="@partner.AvatarVersion" />

Attribute	Values	Notes
size	Small, Medium, Large	Same scale as `koala-avatar`.
partner-id	Guid	Selects the partner crest endpoint at `/api/partners/{id}/avatar`.
name	string	Used for the initials fallback and the `alt` attribute.
has-avatar	bool?	Legacy cache-key flag.
avatar-version	string	Cache-busting key. Blob name when an uploaded crest exists.
show-tooltip	bool	When true, hovers show the partner name in a Tippy tooltip.

Organisation avatar

Square-cornered crest for an organisation (conveyancing firm). Same scale and fallback rules as koala-partner-avatar — just a different endpoint and identity field.

<koala-organisation-avatar>

<koala-organisation-avatar size="Medium" organisation-id="@org.Id" name="@org.Name" avatar-version="@org.AvatarVersion" />

Attribute	Values	Notes
size	Small, Medium, Large	Same scale as `koala-avatar`.
organisation-id	Guid	Selects the org crest endpoint at `/api/organisations/{id}/avatar`.
name	string	Used for the initials fallback and the `alt` attribute.
has-avatar	bool?	Legacy cache-key flag.
avatar-version	string	Cache-busting key. Blob name when an uploaded crest exists.

Phase 3 of the design-system audit recommends collapsing user, partner, and organisation avatars into one polymorphic <koala-avatar entity="..."> helper. Until that lands these three remain three helpers with three pages-within-a-page.