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
BD
CR
Group with member count
Class reference
Every value of each modifier, with its HTML ready to copy.
Size
Avatar size: sm, md, lg, or xl.
Shape
Shape: circle (default) or square.
Status indicator
Presence indicator in the corner: online, offline, busy, or away.
Color
tone-brand, tone-info, and tone-success color the initials; gray is the neutral, with no tone.
Color from the name
Without an explicit color, the tone is derived from the name, so the same person always gets the same color.
Group
ts avatar-group overlaps the avatars; with max, the rest collapse into a +K counter (data-avatar-overflow).
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.
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-avatardata-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
alton the<img>. The fallback initials come fromdata-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-contrastbackground and text pair, which meets AA in light and dark mode. You don’t need to decide contrast by hand. - The group’s
+Kcounter (ts avatar-group) isrole="img"with the accessible name “and K more”. The visible “+K” is the image’s content. - The presence indicator (
status-online,status-busy…) isrole="img"with the status in itsaria-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.