primitive · avatar

Avatar

A resilient image avatar with a stable accessible name and an authored fallback.

Install with npx @madojs/ui@latest add avatar.

Primitive

Meaningful alternative text belongs to the application.

Missing image data leaves the authored fallback visible.

Mado UI team is already named in visible text.

Composition

Use mado-ui-avatar as an autonomous image/fallback leaf. Give it src and alt, then author short fallback text in the named fallback slot.

element mado-ui-avatar: Shadow-DOM avatar host with one stable accessible surface.
attribute src: Image URL; an empty, failed or stale source keeps the fallback visible.
attribute alt: Accessible name for a meaningful avatar; empty alt makes the surface decorative.
slot fallback: Authored initials or another compact fallback shown until a valid image settles.
part avatar / image / fallback: Styling hooks for the stable surface and its two visual states.
css-property --mado-ui-avatar-size: Sets the logical inline and block size of the avatar.

The host keeps one stable accessible surface while the internal image is hidden from the accessibility tree.
Meaningful avatars require non-empty alt text; decorative avatars use alt="" and expose no duplicate fallback name.

The recipe adds no composite keyboard model; native interactive descendants keep their browser-defined keys and Tab order.

Missing, loading and failed images preserve the authored fallback without changing surrounding layout.

The CLI resolves each registry source path into the configured project target. Links below point to the exact catalog build tag.