Avatar
A portrait slot with a graceful fallback for missing or broken images.
Basic
Tag the root with data-stisla-avatar and the behavior layer preloads the source via new Image(), revealing the real <img> only on a confirmed load and flipping data-status through loading → loaded / error. The fallback paints underneath the whole time. For a known-good static image with no JS, set data-status="loaded" on the root directly. Drop text directly into .avatar for the no-image case: a plain neutral tile with the content centered. The default shape is a rounded square.
Image with fallback
Add a .avatar__image and a .avatar__fallback inside .avatar, and tag the root with data-stisla-avatar. The JS preloads the source and only reveals the real <img> after a confirmed load. The fallback paints underneath the whole time, so a slow network shows a styled tile instead of a broken-image icon.
Broken source
If the image fails (404, CORS, blocked domain) the root flips to data-status="error" and the fallback stays visible. The broken <img> never paints because the reveal CSS only fires on data-status="loaded".
Circle
Add .avatar--circle for a circle. Default is rounded square to match the Stisla surface vocabulary.
Sizes
Four sizes: .avatar--sm, default, .avatar--lg, and .avatar--xl. Each retunes --avatar-size and --avatar-font-size off the spacing scale.
Indicator
Pin a .avatar__indicator child to a corner for a status dot, unread count, or verified mark. Default position is bottom-end; add .avatar__indicator--top for top-end. Default tone is success; override --avatar-indicator-bg for any intent.
Loading state
While the source is in flight, the root carries data-status="loading"; the fallback paints until the load completes. Set data-stisla-avatar-delay to hold that state for a fixed time (here 1.5 s) for FOUC tuning or tests.
Events
stisla:avatar:changed fires on the avatar root whenever its load status flips. The detail.status field carries the new value ("loading", "loaded", or "error"). Use it to log image failures, swap to a different source on error, or sequence the next step in a load orchestration.
Customization
These variables retune the avatar root and the indicator. Override on the element, a parent scope, or :root. For the stacked-cluster variant, see Avatar group.
| Variable | Use |
|---|---|
--avatar-size | Square side length; size modifiers retune this |
--avatar-radius | Corner radius; .avatar--circle flips it to a full circle |
--avatar-bg | Tile background, the canvas the fallback paints over |
--avatar-color | Fallback text color |
--avatar-font-size | Fallback font size (icons scale to 1em) |
--avatar-font-weight | Fallback font weight |
--avatar-ring-width | Outline width; .avatar-group raises this so stacked members separate |
--avatar-ring-color | Outline color; the group publishes this |
Indicator variables, defined on .avatar__indicator:
| Variable | Use |
|---|---|
--avatar-indicator-size | Pip diameter; size modifiers retune this |
--avatar-indicator-bg | Pip fill; override for danger / info / muted |
--avatar-indicator-color | Pip text/icon color |
--avatar-indicator-font-size | Digit / icon size inside the pip |
--avatar-indicator-ring-width | Ring punching the pip out of the avatar surface |
--avatar-indicator-ring-color | Ring color; matches the page background |