Avatar & Badge API

Full surface of oge-avatar, oge-avatar-group and oge-badge, and their config providers.

Properties Events Types

OgeAvatar

oge-avatar

Properties 11

Name	Type	Default	Description
`name`	`string \| undefined`	—	Person or entity name — the accessible name and the initials source (first letter of the first and last word, upper-cased in the locale).
`src`	`string \| undefined`	—	Image URL. A failed load falls back to the initials, then the icon; a new `src` gets a fresh attempt.
`initials`	`string \| undefined`	—	Explicit initials, overriding the ones derived from `name`.
`icon`	`string \| undefined`	`person glyph`	SVG path data (`d`, 24×24 viewBox) of the last fallback; `OGE_AVATAR_ICON_PATH` by default.
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`config → group → 'md'`	Size preset — 24 / 32 / 40 / 48 / 64 px.
`shape`	`'circle' \| 'rounded' \| 'square'`	`config → group → 'circle'`	Outline; `rounded` uses `--oge-radius-lg`.
`status`	`'online' \| 'away' \| 'busy' \| 'offline' \| undefined`	—	Presence dot (`aria-hidden`) — the presence label joins the accessible name through the `withStatus` message. Offline is a hollow ring, so the state never rides on colour alone.
`decorative`	`boolean`	`false`	The name is already visible beside it: the host becomes `aria-hidden` with no role, so it is not read twice.
`ariaLabel`	`string \| undefined`	—	Accessible name override; otherwise `name`, else the catalog’s `avatar` (the host is `role="img"`).
`imageLoading`	`'lazy' \| 'eager'`	`'lazy'`	Native `loading` of the image.
`locale`	`string \| undefined`	—	BCP 47 locale of the initials casing; `undefined` = config `locale` → `LOCALE_ID`.

Events 2

Name	Type	Description
`imageLoaded`	`OgeAvatarImageLoadedEvent`	The image at `src` loaded.
`imageFailed`	`OgeAvatarImageFailedEvent`	The image at `src` failed; the avatar now shows its initials or icon.

Types 5

Name	Type	Description
`OgeAvatarSize`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	Size vocabulary.
`OgeAvatarShape`	`'circle' \| 'rounded' \| 'square'`	Shape vocabulary.
`OgeAvatarStatus`	`'online' \| 'away' \| 'busy' \| 'offline'`	Presence vocabulary.
`OgeAvatarImageLoadedEvent`	`{ src: string; event: Event }`	Payload of `imageLoaded`.
`OgeAvatarImageFailedEvent`	`{ src: string; event: Event }`	Payload of `imageFailed`.

OgeAvatarGroup

oge-avatar-group

Properties 8

Name	Type	Default	Description
`items`	`readonly OgeAvatarItem[]`	`[]`	Data-driven avatars, rendered before any projected `<oge-avatar>` children.
`max`	`number \| undefined`	—	Rendered circles including the "+N" one (minimum 2), so the row never grows past it; `undefined` renders all.
`total`	`number \| undefined`	—	Full population of a partially loaded list — the members not in the list count into "+N".
`size`	`OgeAvatarSize \| undefined`	`config → 'md'`	Size of every avatar in the group (a child’s own `size` wins).
`shape`	`OgeAvatarShape \| undefined`	`config → 'circle'`	Shape of every avatar in the group (a child’s own `shape` wins).
`overlap`	`boolean`	`true`	Stack the avatars with a ring in the page surface; `false` spaces them.
`ariaLabel`	`string \| undefined`	—	Accessible name; the host becomes `role="group"` once it has one. The surplus avatar is a `role="img"` named by the `overflow` message ("4 more").
`locale`	`string \| undefined`	—	BCP 47 locale of the "+N" digits and its plural label; `undefined` = config → `LOCALE_ID`.

Types 1

Name	Type	Description
`OgeAvatarItem`	`{ key?; name?; src?; initials?; status?; icon? }`	One avatar of the data-driven `items`.

OgeBadge

oge-badge

Properties 12

Name	Type	Default	Description
`value`	`number \| string \| null \| undefined`	`null`	A count (digits in the locale), a short text shown verbatim, or `null` — no badge.
`max`	`number \| undefined`	`config → 99`	Counts above it show the `overflow` pattern ("99+").
`dot`	`boolean`	`false`	A small dot instead of a value; described by the `dot` message.
`showZero`	`boolean`	`false`	Show a `0` count — hidden by default, "nothing new" needs no badge.
`invisible`	`boolean`	`false`	Force-hide the badge, e.g. while a count loads.
`severity`	`'danger' \| 'accent' \| 'success' \| 'warning' \| 'neutral' \| undefined`	`config → 'danger'`	Colour; `danger` paints the `--oge-badge-bg` / `--oge-badge-color` tokens.
`size`	`'sm' \| 'md'`	`'md'`	Size preset of the count badge (the dot has one size).
`position`	`'top-end' \| 'top-start' \| 'bottom-end' \| 'bottom-start' \| undefined`	`config → 'top-end'`	Corner of the wrapped content — logical, so RTL mirrors it.
`overlap`	`'rectangle' \| 'circle'`	`'rectangle'`	`circle` pulls the badge onto the outline of a round host (an avatar) instead of its bounding box.
`description`	`string \| undefined`	—	Accessible text override. The default reads the catalog: "5 new items", "More than 99 new items", "New" for a dot, a text value itself. An overlay badge points the wrapped control’s `aria-describedby` at it; a standalone one renders it visually hidden.
`announce`	`boolean`	`false`	Speak later changes of the description through a polite live region. The initial value is never announced.
`locale`	`string \| undefined`	—	BCP 47 locale of the digits and the plural description; `undefined` = config → `LOCALE_ID`.

Types 5

Name	Type	Description
`OgeBadgeValue`	`number \| string \| null \| undefined`	What a badge shows.
`OgeBadgeSeverity`	`'danger' \| 'accent' \| 'success' \| 'warning' \| 'neutral'`	Colour vocabulary.
`OgeBadgePosition`	`'top-end' \| 'top-start' \| 'bottom-end' \| 'bottom-start'`	Logical corner vocabulary.
`OgeBadgeOverlap`	`'rectangle' \| 'circle'`	Shape of the wrapped content.
`OgeBadgeSize`	`'sm' \| 'md'`	Size vocabulary.

Configuration

Properties 6

provideOgeAvatarConfig()

Name	Type	Description
`messages`	`OgeAvatarMessages`	Every user-facing string: `avatar` (fallback name, "Avatar"), `withStatus` ("{name} ({status})"), the presence labels `online` / `away` / `busy` / `offline`, and `overflow` — the ICU plural naming the surplus avatar ("{count, plural, one {# more} other {# more}}").
`size / shape`	`—`	Defaults for the matching inputs of the avatar and the group.
`locale`	`string \| undefined`	Default locale of the initials casing and the "+N" digits (`provideOgeLocale()` sets it from the pack).

provideOgeBadgeConfig()

Name	Type	Description
`messages`	`OgeBadgeMessages`	Every user-facing string: `count` (ICU plural, "5 new items"), `overflow` ("{max}+"), `overflowCount` ("More than 99 new items") and `dot` ("New").
`max / severity / position`	`—`	Defaults for the matching inputs.
`locale`	`string \| undefined`	Default locale of the digits and the plural description.

Types 6

Name	Type	Description
`OgeAvatarConfig / OgeAvatarConfigInput`	`interface`	Resolved config and its partial input (`messages` merged one level deep).
`OgeAvatarMessages`	`interface`	The avatar catalog (`layout.avatar` in the locale packs).
`OgeBadgeConfig / OgeBadgeConfigInput`	`interface`	Resolved config and its partial input.
`OgeBadgeMessages`	`interface`	The badge catalog (`layout.badge` in the locale packs).
`OGE_AVATAR_CONFIG / OGE_BADGE_CONFIG`	`InjectionToken`	The DI tokens the providers write.
`OGE_DEFAULT_AVATAR_CONFIG / OGE_DEFAULT_AVATAR_MESSAGES / OGE_DEFAULT_BADGE_CONFIG / OGE_DEFAULT_BADGE_MESSAGES`	`const`	The English defaults (from `@oge-ui/behavior`).