# Avatar Label Group

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

Account with name and email

[Complete TSX file](/examples/avatar-label-group/default.tsx)

```tsx
"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

Complete [one-time setup](/docs/installation/) first.

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

With npm: `npx shadcn@4.18.0 add @siteplane/avatar-label-group`. [Registry JSON](/registry/avatar-label-group.json) lists source files and dependencies.

For this page’s examples, also install:

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/badge
```

## Usage

```tsx
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

```text
AvatarLabelGroup
├── Avatar (the child)
└── caption
    ├── title
    └── subtitle
```

Put the [Avatar](/docs/components/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.

Avatar label groups at sm, md and lg

[Complete TSX file](/examples/avatar-label-group/sizes.tsx)

```tsx
"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](/docs/components/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.

A member who is online and a verified member

[Complete TSX file](/examples/avatar-label-group/marks.tsx)

```tsx
"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](/docs/components/avatar/#scope) 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.

Team members with their roles

[Complete TSX file](/examples/avatar-label-group/list.tsx)

```tsx
"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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| AvatarLabelGroup.size | 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. |
| AvatarLabelGroup.title | 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. |
| AvatarLabelGroup.subtitle | 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. |
| AvatarLabelGroup.children | ReactNode | unset | The Avatar. It takes the group's size and hairline ring unless it names its own size or bordered. |
| AvatarLabelGroup.render | 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. |
| AvatarLabelGroup.className | 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.

[Read the installed source](/source/avatar-label-group).

## 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](/docs/components/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.
