Siteplane UI

Avatar Label Group

Show a person, a team or an account as an avatar with a title and a subtitle beside it.

Markdown

Mara Ellis

mara@example.com

"use client";

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@/siteplane/components/avatar";
import { AvatarLabelGroup } from "@/siteplane/components/avatar-label-group";

export default function Example() {
  return (
    <div className="w-full max-w-sm">
      <AvatarLabelGroup
        size="md"
        subtitle="mara@example.com"
        title="Mara Ellis"
      >
        <Avatar aria-hidden="true">
          <AvatarImage alt="" src="https://ui.siteplane.io/avatars/mara.webp" />
          <AvatarFallback>ME</AvatarFallback>
        </Avatar>
      </AvatarLabelGroup>
    </div>
  );
}

Installation

pnpm dlx shadcn@4.18.0 add @siteplane/avatar-label-group

Complete 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/badge

Usage

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
    └── subtitle

Put 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

"use client";

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@/siteplane/components/avatar";
import { AvatarLabelGroup } from "@/siteplane/components/avatar-label-group";

const sizes = ["sm", "md", "lg"] as const;

export default function Example() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      {sizes.map((size) => (
        <AvatarLabelGroup
          key={size}
          size={size}
          subtitle="mara@example.com"
          title="Mara Ellis"
        >
          <Avatar aria-hidden="true">
            <AvatarImage
              alt=""
              src="https://ui.siteplane.io/avatars/mara.webp"
            />
            <AvatarFallback>ME</AvatarFallback>
          </Avatar>
        </AvatarLabelGroup>
      ))}
    </div>
  );
}

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

Verified

Sofia Nguyen

sofia@example.com

"use client";

import { CheckIcon } from "@phosphor-icons/react/dist/ssr";
import {
  Avatar,
  AvatarBadge,
  AvatarFallback,
  AvatarImage,
} from "@/siteplane/components/avatar";
import { AvatarLabelGroup } from "@/siteplane/components/avatar-label-group";
import { Badge } from "@/siteplane/components/badge";

export default function Example() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <AvatarLabelGroup size="md" subtitle="ben@example.com" title="Ben Carter">
        <Avatar aria-hidden="true" status="online">
          <AvatarImage alt="" src="https://ui.siteplane.io/avatars/ben.webp" />
          <AvatarFallback>BC</AvatarFallback>
        </Avatar>
      </AvatarLabelGroup>
      <AvatarLabelGroup
        size="md"
        subtitle="sofia@example.com"
        title="Sofia Nguyen"
      >
        <Avatar aria-hidden="true">
          <AvatarImage
            alt=""
            src="https://ui.siteplane.io/avatars/sofia.webp"
          />
          <AvatarFallback>SN</AvatarFallback>
          <AvatarBadge>
            <Badge profile="verified">
              <CheckIcon aria-hidden="true" />
              <span className="sr-only">Verified</span>
            </Badge>
          </AvatarBadge>
        </Avatar>
      </AvatarLabelGroup>
    </div>
  );
}

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

    Owner
  • Jonas Weber

    jonas@example.com

    Admin
  • Lea Hoffmann

    lea.hoffmann.design@example.com

    Member
"use client";

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@/siteplane/components/avatar";
import { AvatarLabelGroup } from "@/siteplane/components/avatar-label-group";
import { Badge } from "@/siteplane/components/badge";

const members = [
  {
    email: "mara@example.com",
    image: "https://ui.siteplane.io/avatars/mara.webp",
    initials: "ME",
    name: "Mara Ellis",
    role: "Owner",
  },
  {
    email: "jonas@example.com",
    image: "https://ui.siteplane.io/avatars/jonas.webp",
    initials: "JW",
    name: "Jonas Weber",
    role: "Admin",
  },
  {
    email: "lea.hoffmann.design@example.com",
    image: "https://ui.siteplane.io/avatars/lea.webp",
    initials: "LH",
    name: "Lea Hoffmann",
    role: "Member",
  },
];

export default function Example() {
  return (
    <ul
      aria-label="Team members"
      className="flex w-full max-w-md flex-col gap-4"
    >
      {members.map((member) => (
        <li className="flex items-center gap-3" key={member.email}>
          <AvatarLabelGroup
            size="md"
            subtitle={member.email}
            title={member.name}
          >
            <Avatar aria-hidden="true">
              <AvatarImage alt="" src={member.image} />
              <AvatarFallback>{member.initials}</AvatarFallback>
            </Avatar>
          </AvatarLabelGroup>
          <Badge variant="secondary">{member.role}</Badge>
        </li>
      ))}
    </ul>
  );
}

API reference

Component properties
PropTypeDefaultDescription
AvatarLabelGroup.sizesm | md | lgsmThe 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.
AvatarLabelGroup.titleReactNodeunsetThe 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.
AvatarLabelGroup.subtitleReactNodeunsetThe 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.
AvatarLabelGroup.childrenReactNodeunsetThe Avatar. It takes the group's size and hairline ring unless it names its own size or bordered.
AvatarLabelGroup.renderReactElement | render functionfigureComposes 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.
AvatarLabelGroup.classNamestringunsetClasses 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.

Read the installed source.

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.