Avatar Label Group
Show a person, a team or an account as an avatar with a title and a subtitle beside it.
Mara Ellis
mara@example.com
Installation
pnpm dlx shadcn@4.18.0 add @siteplane/avatar-label-groupComplete the one-time setup first. Registry JSON lists source files and dependencies.
For this page’s examples, also install:
pnpm dlx shadcn@4.18.0 add @siteplane/badgeUsage
import {
Avatar,
AvatarFallback,
AvatarImage,
} from "@/siteplane/components/avatar";
import { AvatarLabelGroup } from "@/siteplane/components/avatar-label-group";
<AvatarLabelGroup size="md" subtitle="mara@example.com" title="Mara Ellis">
<Avatar aria-hidden="true">
<AvatarImage src="/avatars/mara-ellis.png" alt="" />
<AvatarFallback>ME</AvatarFallback>
</Avatar>
</AvatarLabelGroup>;Composition
AvatarLabelGroup
├── Avatar (the child)
└── caption
├── title
└── subtitlePut the Avatar in the group as its child, with its image, its fallback and any mark it needs. title and subtitle become the group's caption beside it. The group gives the Avatar its size and its hairline ring, so the Avatar passes neither, and the title and the subtitle take the kit's text roles: the title the label weight in the primary text color, the subtitle the body weight in the tertiary color. The avatar and the text stand 8 px apart, and the text is centered on the avatar.
Sizes
size sets the avatar and its text together. sm, the default, is a 32 px avatar beside a 14 px title on a 20 px line and a 12 px subtitle on an 18 px line. md is a 40 px avatar with a 14 px title and subtitle on 20 px lines, and lg a 48 px avatar with a 16 px title and subtitle on 24 px lines. The avatar's initials, its placeholder icon, its presence dot and its corner marks step with the size.
Mara Ellis
mara@example.com
Mara Ellis
mara@example.com
Mara Ellis
mara@example.com
Presence and corner marks
The Avatar keeps its own marks in the group: a presence dot from status, and an AvatarBadge with a verified or a count Badge. They take the group's size like the avatar. A company logo in an AvatarBadge takes the size and the surface ring of a corner mark, not the group's hairline ring, because a mark leaves the group's scope.
Ben Carter
ben@example.com
Sofia Nguyen
sofia@example.com
Ring and size of the avatar
The group draws the Avatar's hairline ring, as bordered does on its own, with a small gap between the ring and the image. What the Avatar names itself wins: bordered={false} on the Avatar leaves the ring out, and a size on the Avatar gives it another size than the group's text. The group hands both through AvatarScope, which the Avatar page describes.
In a list
The group fills the row it stands in and never pushes past it, so an action or a badge after it keeps its place at the end. The title wraps where its line is full. The subtitle stays on one line and ends with an ellipsis where the group is full; given as text, it carries its full text as its title, as the long email address of the last member shows.
Mara Ellis
mara@example.com
Jonas Weber
jonas@example.com
Lea Hoffmann
lea.hoffmann.design@example.com
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
Avatar | sm | md | lg | sm | The avatar and its text: sm is a 32 px avatar with a 14 px title and a 12 px subtitle, md a 40 px avatar with 14 px text, lg a 48 px avatar with 16 px text. |
Avatar | ReactNode | unset | The main line beside the avatar, such as a person's name or an account. It wraps where its line is full. Without it, no title element renders. |
Avatar | ReactNode | unset | The line under the title, such as an email address or a role. It stays on one line and ends with an ellipsis; text carries its full text as its title. Without it, no subtitle element renders. |
Avatar | ReactNode | unset | The Avatar. It takes the group's size and hairline ring unless it names its own size or bordered. |
Avatar | ReactElement | render function | figure | Composes the group onto another element. Any element other than a figure holds the caption and the lines as spans, so render={<span />} fits the group into a button. |
Avatar | string | unset | Classes for the group. |
AvatarLabelGroupProps extends the props of a figure, except title, which is the caption line here, and accepts a ref. The group renders a figure with data-slot="avatar-label-group" and data-size, and a figcaption with data-slot="avatar-label-group-caption" that holds the title and the subtitle as paragraphs, avatar-label-group-title and avatar-label-group-subtitle. Rendered as any other element through render, such as a span, the group holds the caption and the lines as spans with the same slots, and lays them out alike. Without a title and a subtitle, no caption renders. The type AvatarLabelGroupSize is exported.
Usage notes
Use the group wherever a row stands for one person, team or account: the name cell of a table, a member list, an account card or the header of an account menu. For several people at once, use Avatar Group.
The group is a figure, and its title and subtitle are its caption, so assistive technology reads the name and the line under it. When the title names the person, hide the Avatar from assistive technology with aria-hidden on it, as the examples do, so the name is not read twice. A presence dot and a corner mark stand beside the Avatar and keep their accessible names; give a mark one, such as visually hidden text in its Badge.
The figure and the paragraphs of its caption are flow content, so the default group stands where a paragraph can stand, such as a table cell, a list item or a card. Inside a button, which takes only phrasing content, render it as a span with render={<span />}: its caption and lines are spans then. The group owns no interaction: to make a row a button, put the group inside it as a span; to make it a link, wrap the row or put a link in its title.