# Avatar Displays a user or object avatar, supporting both text-placeholder and image forms. ## Basic Usage

A text avatar renders the first character of its content; with no content at all, it shows a `?` placeholder. ## Sizes

## Image Avatars

## Avatar Groups

Multiple `oas-avatar` elements wrapped in `oas-avatar-group` are laid out left-to-right with overlapping.

When `max` is set, the overflow is hidden and a `+N` count badge is shown at the end. ## Unified Size `size` sets the size of all avatars in the group (px) so it does not need to be set per avatar; combined with `max`, the `+N` count badge adapts its size accordingly.

## Group Spacing The overlap is driven by a CSS variable: `-8px` overlap by default. The `spacing` attribute (px number) accepts positive values (gap between members) and negative values (deeper overlap); you can also override `--oas-avatar-group-overlap` directly. Members get a page-background ring so overlapping avatars never bleed into each other (dark-theme aware).

## Folded Members Popover With `max` set, hover, keyboard-focus, or click the `+N` count button to open a popover listing all folded member avatars; close with `Escape`, an outside click, or moving focus away.

## Badge Overlay `badge` overlays a badge on the avatar's top-right corner (text or boolean); the boolean form (no value) shows a small dot; `badge-dot` forces the dot variant; `badge-color` switches colors; `badge-placement` moves the badge to the bottom-right.

## Load-Failure Fallback When the image fails to load, the avatar automatically falls back to a placeholder: first the `fallback` named-slot content, then the first character of its content, and finally `?`.

## Empty Fallback

## text Attribute The `text` attribute drives the text rendering and is **reactive**: changing `text` at runtime takes effect immediately (attribute change triggers a re-render). Multi-character text renders in full and shrinks to fit the container (floor 10px, see "Long Name Auto-Fit"); a single character, or the fallback to the first character of the light-DOM text content — a one-time snapshot taken at connect time — stays unchanged. Use the `text` attribute for dynamic text.

## Shape `shape` controls the avatar outline: `circle` (default), `square` (right-angle corners), or `round` (small corner radius from the radius token). The image, placeholder, and change-avatar mask all follow the same radius.

## Size Presets Besides numeric px, `size` accepts enum aliases: `small` (24) / `medium` (32) / `large` (40), aligned with the library-wide size scale.

## Long Name Auto-Fit When `text` has multiple characters (organization or team names), it is no longer truncated to the first character: the full text renders and the font size shrinks to fit the container, with a 10px floor for readability.

## Background Color `color` follows the library-wide color protocol: 4 semantic colors (`primary`/`success`/`warning`/`danger`), 11 preset palette names (`blue`, `geekblue`, `volcano`, …), or any CSS color value. The text color is picked automatically (black/white) for contrast. You can also override the CSS variables `--oas-avatar-bg` / `--oas-avatar-on-color` directly.

## Image Fit `fit` maps to the image's `object-fit`; `cover` by default (crop to fill). Use `contain` to show a tall image in full.

## Icon Avatar Place an icon in `slot="icon"` (an `oas-icon` or any svg/content): when an icon is given explicitly, the first character is no longer rendered.

## Fallback Image The `fallback` attribute provides a fallback image URL: when the primary image fails to load, the avatar switches to the fallback image and retries once before entering the text fallback chain. Every failure dispatches an `oas-error` event (`detail.src` is the URL that failed) so hosts can track errors or customize the fallback.

## Change Avatar Trigger Drop any `slot="trigger"` node in to enable the change-avatar entry: hovering or keyboard-focusing the avatar reveals a mask (an empty node shows the built-in camera icon; content becomes the mask content), and clicking dispatches an `oas-trigger` event — the upload flow is up to the host.

Change

## Status Dot Composition Online status and similar scenarios are not built in: compose with `oas-badge` wrapping the avatar (`dot` + semantic `color`), with position and color controlled by the badge side.

## Name Tooltip To show a name or description per avatar, compose with a wrapping `oas-tooltip` (works on hover and keyboard focus).

## Responsive Image Sources (srcset) `srcset` passes through to the inner `img`, letting the browser pick a source by device pixel ratio (e.g. 1x/2x pairs — high-DPI screens get the sharper image automatically); an empty value removes it and falls back to the single `src`.

## API ### oas-avatar #### Attributes | Attribute | Description | Type | Default | | --- | --- | --- | --- | | `alt` | Alternative text for the image | — | — | | `badge` | Badge text overlaid on the avatar's top-right corner; boolean form (no value) shows a dot | `string` | — | | `badge-color` | Badge color: `primary`/`success`/`warning`/`danger` | `string` | `danger` | | `badge-dot` | Small dot badge variant (no text) | `boolean` | — | | `badge-placement` | Badge placement: `top-right` (default) / `bottom-right` | `string` | `top-right` | | `color` | Text avatar background: semantic color / preset name / any color value (contrast text color auto-picked) | `string` | — | | `fallback` | Fallback image URL: used when the main image fails (text/slot chain after that) | `string` | — | | `fit` | Image object-fit (default `cover`) | `string` | — | | `shape` | Shape: `circle` (default) / `square` / `round` (rounded corners) | — | — | | `size` | Size: number in px or enum alias `small`(24) / `medium`(32) / `large`(40) | `string` | `32` | | `src` | Image URL; renders an image avatar when present | `string` | — | | `srcset` | Responsive source descriptors passed through to the inner img (empty removes it) | `string` | — | | `text` | Text content: single char renders the first character; multiple chars render in full with auto-shrinking font | `string` | — | #### Events | Event | Description | | --- | --- | | `oas-error` | Fired when an image fails (once for the main src, once for the fallback), `detail: { src }` | | `oas-trigger` | Change-avatar entry (trigger overlay) clicked; upload interaction is up to the host, `detail: { source: this }` | #### Slots | Name | Description | | --- | --- | | `fallback` | Custom placeholder content when the image fails to load (or the avatar has no content) | | `icon` | Icon avatar (explicit icon content; no first-character truncation) | | `trigger` | Custom content for the change-avatar overlay (shown on hover/focus; built-in camera icon by default) | #### CSS Variables | CSS Variable | Default | | --- | --- | | `--oas-avatar-bg` | `var(--oas-color-primary)` | | `--oas-avatar-on-color` | `var(--oas-color-text-on-primary)` | | `--oas-avatar-size` | `32px` | ### oas-avatar-group #### Attributes | Attribute | Description | Type | Default | | --- | --- | --- | --- | | `max` | Max number of avatars shown; overflow shows a `+N` count badge | `string` | — | | `size` | Unified avatar size (px); the count badge adapts | `string` | — | | `spacing` | Member spacing in px (negative = overlapping; overrides the `--oas-avatar-group-overlap` variable) | `string` | — | #### Slots | Name | Description | | --- | --- | | default | Avatar members (`oas-avatar`) | #### CSS Variables | CSS Variable | Default | | --- | --- | | `--oas-avatar-group-overlap` | `-8px` | | `--oas-avatar-group-ring` | `var(--oas-color-bg)` | > Note: `alt` is read on first render and is not in the observed attribute list; dynamic changes require a manual re-render.