Avatar
Displays a user or object avatar, supporting both text-placeholder and image forms.
Basic Usage
Text avatars
A text avatar renders the first character of its content; with no content at all, it shows a ? placeholder.
Sizes
Size variants
Image Avatars
Image avatars
Avatar Groups
Avatar group
Multiple oas-avatar elements wrapped in oas-avatar-group are laid out left-to-right with overlapping.
Max display count
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.
Unified size size
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).
Group spacing
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.
Folded members popover
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.
Text badges
Dot badges
Placement and image avatars
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 ?.
Fallback to first character
Custom fallback slot
Empty Fallback
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.
text attribute drives rendering
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.
Shape variants
Size Presets
Besides numeric px, size accepts enum aliases: small (24) / medium (32) / large (40), aligned with the library-wide size scale.
Size presets (enum aliases)
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.
Long name auto-fit
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.
Background color
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.
Image fit
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.
Icon avatars
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.
Fallback image
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 avatar trigger
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.
Status dot composition (wrapped in oas-badge)
Name Tooltip
To show a name or description per avatar, compose with a wrapping oas-tooltip (works on hover and keyboard focus).
Name tooltip (oas-tooltip composition)
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.
srcset 1x / 2x sources
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:
altis read on first render and is not in the observed attribute list; dynamic changes require a manual re-render.