Skip to main content

Avatar

Person or entity representation. Image, initials, or icon fallback. Status dot indicator.

Quick start 
import { Avatar } from "mates-ui";

Avatar({ name: "Ada Lovelace", size: "md", status: "online" });

Sizes

import { html, renderApp } from 'mates';
import { Avatar } from 'mates-ui';

const App = () => () => html`
<x-row gap="var(--md-space-4)" align="center">
${Avatar({ name: "Alice Wang", size: "xs" })}
${Avatar({ name: "Bob Smith", size: "sm" })}
${Avatar({ name: "Carol Jones", size: "md" })}
${Avatar({ name: "David Brown", size: "lg" })}
${Avatar({ name: "Eve Johnson", size: "xl" })}
</x-row>
`;

renderApp(App, document.getElementById('app'));

Image

import { html, renderApp } from 'mates';
import { Avatar } from 'mates-ui';

const App = () => () => html`
<x-row gap="var(--md-space-3)" align="center">
${Avatar({ src: "https://i.pravatar.cc/80?img=1", name: "User 1", size: "md" })}
${Avatar({ src: "https://i.pravatar.cc/80?img=5", name: "User 2", size: "md" })}
${Avatar({ src: "https://i.pravatar.cc/80?img=12", name: "User 3", size: "md" })}
${Avatar({ src: "https://i.pravatar.cc/80?img=47", name: "User 4", size: "lg" })}
</x-row>
`;

renderApp(App, document.getElementById('app'));

Status dot

import { html, renderApp } from 'mates';
import { Avatar } from 'mates-ui';

const App = () => () => html`
<x-row gap="var(--md-space-4)" align="center">
${Avatar({ name: "Alice", status: "online", size: "md" })}
${Avatar({ name: "Bob", status: "away", size: "md" })}
${Avatar({ name: "Carol", status: "busy", size: "md" })}
${Avatar({ name: "David", status: "offline", size: "md" })}
${Avatar({ src: "https://i.pravatar.cc/80?img=3", name: "Eve", status: "online", size: "lg" })}
</x-row>
`;

renderApp(App, document.getElementById('app'));

Initials override

import { html, renderApp } from 'mates';
import { Avatar } from 'mates-ui';

const App = () => () => html`
<x-row gap="var(--md-space-3)" align="center">
${Avatar({ name: "Ada Lovelace", size: "lg" })}
${Avatar({ name: "Grace Hopper", size: "lg" })}
${Avatar({ name: "Alan Turing", size: "lg" })}
${Avatar({ initials: "AB", size: "lg" })}
${Avatar({ initials: "XY", size: "lg" })}
${Avatar({ initials: "42", size: "lg" })}
</x-row>
`;

renderApp(App, document.getElementById('app'));

Icon fallback

import { html, renderApp } from 'mates';
import { Avatar } from 'mates-ui';
import { AccountCircleIcon, GroupIcon, PersonIcon, SmartToyIcon, SupportAgentIcon } from 'mates-icons';

const App = () => () => html`
<x-row gap="var(--md-space-3)" align="center">
${Avatar({ icon: PersonIcon(), size: "md" })}
${Avatar({ icon: SmartToyIcon(), size: "md" })}
${Avatar({ icon: SupportAgentIcon(), size: "lg" })}
${Avatar({ icon: GroupIcon(), size: "lg" })}
${Avatar({ icon: AccountCircleIcon(), size: "xl" })}
</x-row>
`;

renderApp(App, document.getElementById('app'));

Avatar

import { Avatar } from "mates-ui";
Prop Type Default Description
alt string — Alt text for the image. Falls back to `name` when not provided.
attr AttrMap — Arbitrary HTML attributes forwarded to the root element.
classes string | string[] — Extra root classes — joined and appended after built-in classes.
data DataAttrMap — Root `data-*` map (`testId` → `data-testid`). `testId` prop / `attr` win over `data`.
icon string — Material Symbol icon name used as the final fallback when neither image nor initials are present. Defaults to "person".
id string — Root `id` shorthand (`attr.id` wins). Form native-control `id` props are unchanged.
initials string — Explicit initials override shown when no image is available.
name string — Full name used to derive two-character initials. Also used as the accessible label when `alt` is absent.
on OnEventMap — DOM event handlers on the root element.
size "xs" | "sm" | "md" | "lg" | "xl" "md" Controls the diameter of the avatar.
src string — URL of the avatar image. Falls back to initials then icon on load error.
status "online" | "away" | "busy" | "offline" — Shows a colored status dot overlaid on the avatar.
style StyleMap — Inline CSS on the root element.
testId string — Overrides the default `data-testid="md-avatar"` for testing.

CSS tokens

Token Role
--md-color-error Status dot color when status is "busy".
--md-color-on-primary-container Default foreground (initials text / icon) color.
--md-color-outline Status dot color when status is "offline".
--md-color-primary-container Default background for the initials/icon state.
--md-color-success Status dot color when status is "online".
--md-color-warning Status dot color when status is "away".

Caveats

  • Image `src` falls back to initials then icon on load error.
  • Initials are auto-derived from `name` — first letter of the first and last word. Supply `initials` to override.
  • Always provide `name` or `attr['aria-label']` for screen readers.