Skip to content

Avatar

Represents a user or entity with an image, or with initials derived from the name as a fallback (if the image fails, Core writes them in). Without an explicit tone, it derives a stable one from the name (tone-*). It has a status indicator (status-online) and stacking with ts avatar-group, which collapses the rest into a counter (data-avatar-overflow, “+5”).

Content · TaishoDS Core, in plain HTML.

Examples

One working example per case. Each example is the HTML of its preview—copy it as is, and with Core’s CSS and JS loaded, it looks and works the same.

With image, initials, and status

Ana Torres BD CR
html

Group with member count

AT BD CR +5
html

Class reference

Every value of each modifier, with its HTML ready to copy.

Size

Avatar size: sm, md, lg, or xl.

AT AT AT AT
html

Shape

Shape: circle (default) or square.

BD BD
html

Status indicator

Presence indicator in the corner: online, offline, busy, or away.

CR CR CR CR
html

Color

tone-brand, tone-info, and tone-success color the initials; gray is the neutral, with no tone.

AT AT AT AT
html

Color from the name

Without an explicit color, the tone is derived from the name, so the same person always gets the same color.

AT BD CR DS EV
html

Group

ts avatar-group overlaps the avatars; with max, the rest collapse into a +K counter (data-avatar-overflow).

AT BD CR DS EV
AT BD CR +2
AT BD CR +9
html

When to use

  • Identifying a person in a list, a comment, or an account bar.
  • Showing at a glance who’s involved in something (ts avatar-group).
  • You want a decent fallback when there’s no photo.

When not to use

  • It’s a status or a category, not a person → badge.
  • It’s a content image that needs to be seen clearly → an image with aspect-ratio.

Do

  • Always set data-ts-name. It’s where the initials and the alt text come from.
  • Show the name next to the avatar when identity really matters.

Don’t

  • Don’t use the status indicator (status-*) as the only indicator. Color alone doesn’t communicate.
  • Don’t stack twenty avatars. Show a few and let the rest become a counter.
  • Don’t force a tone (tone-*) for decoration. The one derived from the name already makes each person recognizable.

Related

BadgeCard

TaishoDS Core

Needs Core’s JS, which hooks in through data-ts-* attributes.

If the image doesn’t load, the avatar falls back to initials, and Core handles that.

Core hooks into it through these attributes. They go in the markup, and there’s nothing to initialize.

  • data-ts-avatar
  • data-ts-name

What it does: If the image fails, Core removes it from the DOM, writes the initials, and keeps the person’s name on the container (role="img" and aria-label). It also covers images that failed before Core ran. On init it checks the <img> elements that already finished loading with no natural width, so it doesn’t depend on load order. The initials' tone (tone-*) and the group’s +K counter are static markup. The CSS paints them, and no JavaScript is needed.

From the CDN, without a build, load taisho.avatar.css along with taisho.base.css. That file is all you need.

For how Core works in general, see Behavior.

Accessibility

  • Always set alt on the <img>. The fallback initials come from data-ts-name.
  • If the image doesn’t load, it’s replaced with the name’s initials, even if the error happens before Core initializes.
  • The colored initials are derived from name, using each tone’s -600 / -600-contrast background and text pair, which meets AA in light and dark mode. You don’t need to decide contrast by hand.
  • The group’s +K counter (ts avatar-group) is role="img" with the accessible name “and K more”. The visible “+K” is the image’s content.
  • The presence indicator (status-online, status-busy…) is role="img" with the status in its aria-label (“Online”). If the status is essential information, also pair it with visible text in context.

Verification

What was actually tested. Anything that wasn’t tested says so—we’d rather say “not verified” than claim too much.

  • axe WCAG 2.2 A + AA in a real browser, in light and dark mode, before every release.
  • keyboard Adds no keys of its own—it uses the browser’s native behavior.
  • screen reader Not verified with a screen reader. Test it in your own combination of components, not just here, where each one appears alone and on its happy path.