v0.1.0
Esc

    ↑ ↓ to move, Enter to open

    Avatar

    A circular image, or initials on a tray fill, that stands for a person or organisation. AvatarGroup stacks several with an overflow count.

    StableSource

    Import

    tsx
    import { Avatar, AvatarGroup, getInitials } from "@merid/react";

    Examples

    Sizes

    xs 24px, sm 32px, md 40px (default), lg 48px, xl 64px.

    Image and fallback

    Pass src for a photo. When it is missing or fails to load, the avatar falls back to initials derived from name — the first letter of the first and last word. initials overrides them (at most two characters are shown).

    Group

    max limits the visible avatars; the rest collapse into a “+N” chip. Set the group's size to match its avatars so the chip lines up.

    API reference

    Avatar

    Renders a span; the ref and other span attributes are forwarded.

    PropTypeDefaultDescription
    nameRequiredstring–Person or entity name. The accessible name and the source of initials.
    srcstring–Image URL. Falls back to initials when missing or when loading fails.
    size"xs" | "sm" | "md" | "lg" | "xl""md"Diameter: 24, 32, 40, 48 or 64px.
    initialsstring–Overrides the derived initials (max 2 characters shown).

    AvatarGroup

    Renders a div with role="group".

    PropTypeDefaultDescription
    labelstring–Accessible name of the group, e.g. "Project members". Required unless you pass `aria-label` or `aria-labelledby`; a development warning is logged otherwise.
    maxnumber–Maximum avatars shown; the rest collapse into a +N chip.
    size"xs" | "sm" | "md" | "lg" | "xl""md"Size of the overflow chip; match the avatars' size.
    childrenReactNode–Avatar elements.

    getInitials

    getInitials(name: string): string returns up to two upper-case initials — getInitials("Ada Lovelace") is "AL", getInitials("Linus") is "L".

    Styling

    HookValues
    .mrd-avatarRoot circle
    .mrd-avatar__imageThe <img>
    .mrd-avatar__fallbackInitials
    .mrd-avatar-group, .mrd-avatar-group__overflowGroup row and +N chip
    data-sizexs · sm · md · lg · xl
    data-statusimage · fallback

    Component variable: --mrd-avatar-size, set per size.

    Accessibility

    • Each avatar is role="img" named by name; the inner image has alt="" and the initials are hidden, so the name is read once.
    • The overflow chip is announced as “N more”.
    • The group has role="group"; name it with label (“Project members”) so the list has context.
    • When an avatar sits next to the person's visible name, the name is read twice; pass aria-hidden on the avatar in that case.

    Guidelines

    Do

    Always pass the real name, even with an image — it is the fallback and the accessible name.

    Avoid

    Pass a placeholder name like “User” or leave initials to guess from an email address.

    • Badge — status next to an avatar.
    • Skeleton — circle placeholder while a profile loads.