Skip to content
BigBang

Popular

    ↑↓Navigate↵OpenEscClose
    TR

    Components

    Avatar

    Identifies a person or company with a picture, or with initials when there is none, and an optional status dot.

    Storybook
    Storybook
    Source
    Source

    When to use

    Section titled “When to use”

    Avatar identifies a person or a company in a small space: a list row, a comment, a user menu, team members. Without a picture the initials do the same job, so rows keep their alignment.

    When not to use

    Section titled “When not to use”
    • For a product or content image: Avatar is for identity; use img for photos and product images.
    • For an icon: use Icon for a symbol that explains an action or a type.
    • To carry a status alone: the status dot is a hint; write an important status as text with a Badge.
    • For a clickable profile: Avatar is not interactive; put it inside a link or a button.

    Anatomy

    Section titled “Anatomy”
    1. Root: a 24-64 px box; a circle for a person, a radius-md square for a company. It carries role="img" and the name.
    2. Image (Avatar.Image): appears within 110 ms once loaded; its alt is empty.
    3. Fallback (Avatar.Fallback): the initials while the image loads or if it never does; an icon without a name.
    4. Status (Avatar.Status): a dot at the bottom inline end with a 2 px surface ring.
    5. Group (Avatar.Group): overlapping avatars and a “+N” count.

    Behaviour

    Section titled “Behaviour”
    • The fallback shows while the image loads. Use delay to hold it back and avoid a flash of initials on a fast connection.
    • When the image has loaded it replaces the fallback and fades in by opacity. If it fails, the fallback stays.
    • The initials are the first letter of the first two words, at most 2 characters, upper-cased for the Provider language.
    • An Avatar takes no focus and has no interaction.
    • In a group, avatars beyond max are counted as “+N”.

    Guidelines

    Section titled “Guidelines”

    Make the avatar decorative when the name is beside it

    Section titled “Make the avatar decorative when the name is beside it”

    When the name is printed next to the avatar, set decorative; a screen reader does not read the name twice.

    User 1
    DoThe name is printed; the avatar is marked decorative.
    U1User 1
    Don'tThe name is printed and also read from the avatar.

    Give the real name

    Section titled “Give the real name”

    name should always be the full name of the person or company.

    U2
    DoA full name: correct initials and a meaningful name.
    U
    Don'tA generic name: the initials and the screen reader output mean nothing.

    One size in one place

    Section titled “One size in one place”

    Avatars in one list share a size.

    U1U2
    DoThe same size in every row.
    U1U2
    Don'tMixed sizes break the alignment.

    Content

    Section titled “Content”
    • Pass the full name of the person or company as name: “User 1”, “Sample Ltd”.
    • Do not write alternative text for the picture; Avatar leaves alt empty and puts the name on the root.
    • Make the group aria-label a short name for the team: “Team”.
    Section titled “Related components”
    • Badge: writes the status as text.
    • Icon: for a type or action symbol, not an identity.
    • ListItem: a list row with an Avatar at the start.