# Badge Group

Join a small badge and a message in one pill, such as a release note or a status line above a heading.

A new feature announcement

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

```tsx
"use client";

import { BadgeGroup } from "@/siteplane/components/badge-group";

export default function Example() {
  return (
    <BadgeGroup addon="New feature">Scheduled reports are here</BadgeGroup>
  );
}
```

## Installation

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

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

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

## Usage

```tsx
import { BadgeGroup } from "@/siteplane/components/badge-group";

<BadgeGroup addon="New feature">Scheduled reports are here</BadgeGroup>;
```

## Composition

```text
BadgeGroup
├── addon
├── message (children)
└── icon
```

A badge group is a [Badge](/docs/components/badge/) that holds a second, smaller Badge, the addon, beside a message. The addon names the kind of news, such as New feature or Warning, and the message says what it is. An arrow follows the message. The group takes the Badge's pill geometry and tints, and the addon lays out its text and an icon as any Badge does.

## Variants

`variant` sets the tint of the group from the Badge's tints: `info`, the default, is the tint of the accent; `secondary` is the neutral fill; `success`, `warning` and `error` tint with a status color; and `slate`, `sky`, `blue`, `indigo`, `purple`, `pink` and `orange` with one of the Badge's [colors](/docs/components/badge/#colors). The addon is a white pill on the tint, in the tint's text color.

Badge groups in five tints

[Complete TSX file](/examples/badge-group/variants.tsx)

```tsx
"use client";

import {
  BadgeGroup,
  type BadgeGroupVariant,
} from "@/siteplane/components/badge-group";

const messages: {
  addon: string;
  message: string;
  variant: BadgeGroupVariant;
}[] = [
  {
    addon: "New feature",
    message: "Scheduled reports are here",
    variant: "info",
  },
  {
    addon: "Update",
    message: "Version 2.4 is available",
    variant: "secondary",
  },
  { addon: "Success", message: "Your domain is verified", variant: "success" },
  {
    addon: "Warning",
    message: "Your trial ends in 3 days",
    variant: "warning",
  },
  { addon: "Error", message: "The last sync failed", variant: "error" },
];

export default function Example() {
  return (
    <div className="flex flex-col items-start gap-4">
      {messages.map(({ addon, message, variant }) => (
        <BadgeGroup addon={addon} key={variant} variant={variant}>
          {message}
        </BadgeGroup>
      ))}
    </div>
  );
}
```

## Modern

`appearance="modern"` draws a white group with a hairline contour, rounded by the provider radius instead of fully. Its addon is a white badge that leads with a dot in the variant's color, the [BadgeDot](/docs/components/badge/#with-status-dot), so `variant` names the color of the dot. The message takes the secondary text color and the arrow the tertiary one.

Modern badge groups with colored dots

[Complete TSX file](/examples/badge-group/modern.tsx)

```tsx
"use client";

import {
  BadgeGroup,
  type BadgeGroupVariant,
} from "@/siteplane/components/badge-group";

const messages: {
  addon: string;
  message: string;
  variant: BadgeGroupVariant;
}[] = [
  {
    addon: "New feature",
    message: "Scheduled reports are here",
    variant: "info",
  },
  {
    addon: "Update",
    message: "Version 2.4 is available",
    variant: "secondary",
  },
  { addon: "Success", message: "Your domain is verified", variant: "success" },
  {
    addon: "Warning",
    message: "Your trial ends in 3 days",
    variant: "warning",
  },
  { addon: "Error", message: "The last sync failed", variant: "error" },
];

export default function Example() {
  return (
    <div className="flex flex-col items-start gap-4">
      {messages.map(({ addon, message, variant }) => (
        <BadgeGroup
          addon={addon}
          appearance="modern"
          key={variant}
          variant={variant}
        >
          {message}
        </BadgeGroup>
      ))}
    </div>
  );
}
```

## Addon at the end

`addonPosition="end"` puts the message first and the addon at the end of the group, with the arrow inside the addon. In the modern appearance, the dot moves to the start of the group, before the message.

Badge groups with the addon after the message

[Complete TSX file](/examples/badge-group/addon-end.tsx)

```tsx
"use client";

import { BadgeGroup } from "@/siteplane/components/badge-group";

export default function Example() {
  return (
    <div className="flex flex-col items-start gap-4">
      <BadgeGroup addon="New feature" addonPosition="end">
        Scheduled reports are here
      </BadgeGroup>
      <BadgeGroup
        addon="Success"
        addonPosition="end"
        appearance="modern"
        variant="success"
      >
        Your domain is verified
      </BadgeGroup>
    </div>
  );
}
```

## Link

Pass `href` to make the group a link to that address: it renders an `<a>`, shows the pointer, a tint of its own text color on hover and a stronger one while it is pressed, the [border flash](/docs/components/button/#border-flash) when a press ends, and the kit's focus ring on keyboard focus, in every appearance and color. For a link component of your router or a button, pass `render` instead, which wins over `href`. Without either, the group is static text and shows no hover.

Badge groups that link to a changelog and an event

[Complete TSX file](/examples/badge-group/link.tsx)

```tsx
"use client";

import { BadgeGroup } from "@/siteplane/components/badge-group";

export default function Example() {
  return (
    <div className="flex flex-col items-start gap-4">
      <BadgeGroup addon="New feature" href="#changelog">
        Read about scheduled reports
      </BadgeGroup>
      <BadgeGroup
        addon="Webinar"
        appearance="modern"
        href="#events"
        variant="purple"
      >
        Join the live product tour
      </BadgeGroup>
    </div>
  );
}
```

## Sizes

`size="md"`, the default, is 30 px high with 12 px type around a 22 px addon, the Badge's `sm`. `size="lg"` is 32 px high with 14 px type around a 24 px addon, the Badge's `md`. The addon stands 4 px inside the group's edge and 8 px from the message.

Badge groups at md and lg

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

```tsx
"use client";

import { BadgeGroup } from "@/siteplane/components/badge-group";

export default function Example() {
  return (
    <div className="flex flex-col items-start gap-4">
      <BadgeGroup addon="New feature" size="md">
        Scheduled reports are here
      </BadgeGroup>
      <BadgeGroup addon="New feature" size="lg">
        Scheduled reports are here
      </BadgeGroup>
    </div>
  );
}
```

## Icon

`icon` replaces the arrow after the message, and `null` leaves it out. The icon is 16 px and stands 4 px after the message; inside an addon at the end it is the addon's 12 px icon. An addon without a message and without an icon makes a group of the addon alone.

A badge group with its own icon and one without

[Complete TSX file](/examples/badge-group/icon.tsx)

```tsx
"use client";

import { SparkleIcon } from "@phosphor-icons/react/dist/ssr";
import { BadgeGroup } from "@/siteplane/components/badge-group";

export default function Example() {
  return (
    <div className="flex flex-col items-start gap-4">
      <BadgeGroup addon="AI" icon={<SparkleIcon aria-hidden="true" />}>
        Summaries now cover every meeting
      </BadgeGroup>
      <BadgeGroup addon="Beta" icon={null} variant="secondary">
        Workflows are in beta
      </BadgeGroup>
    </div>
  );
}
```

## Long messages

The message stays on one line and ends with an ellipsis where the group meets the edge of its space, and its full text is the label's title. The group is as wide as its content and no wider than the space it sits in, so a flex column does not stretch it.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| BadgeGroup.addon | ReactNode | required | The small badge that joins the message, such as New feature or Error. It is a Badge of its own, so text and an icon lay out as in any Badge. |
| BadgeGroup.children | ReactNode | unset | The message, one line that ends with an ellipsis where the group is full. |
| BadgeGroup.variant | secondary \| info \| success \| warning \| error \| slate \| sky \| blue \| indigo \| purple \| pink \| orange | info | The tint of the group, or in the modern appearance the color of the addon's dot. |
| BadgeGroup.appearance | light \| modern | light | light tints the whole group and sets the addon on it as a white pill. modern is a white group with a hairline contour whose addon leads with a dot in the variant's color. |
| BadgeGroup.addonPosition | start \| end | start | start puts the addon before the message and the icon after it. end puts the message first and the addon, with the icon inside it, at the end. |
| BadgeGroup.size | md \| lg | md | md is 30 px high with 12 px type around a 22 px addon, lg 32 px high with 14 px type around a 24 px addon. |
| BadgeGroup.icon | ReactNode | arrow | The icon after the message, or inside the addon at the end. null leaves it out. It is decoration, so give it aria-hidden. |
| BadgeGroup.href | string | unset | Makes the group a link to this address: an a element with the pointer, the hover and pressed tints and the focus ring. render wins over it. |
| BadgeGroup.render | ReactElement \| render function | span | Composes the group onto another element, such as a link component or a button. |
| BadgeGroup.className | string | unset | Classes for the group. |

`BadgeGroupProps` extends the props of [Badge](/docs/components/badge/), except `variant`, `size`, `shape`, `profile`, `light`, `onRemove` and `removeLabel`, which the group sets itself, and accepts a ref. The group renders a span, or an `a` with `href`, with `data-slot="badge-group"`, `data-appearance` and `data-addon-position`, and the addon is a Badge with `data-slot="badge-group-addon"`. The types `BadgeGroupVariant`, `BadgeGroupAppearance`, `BadgeGroupSize` and `BadgeGroupAddonPosition` are exported.

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

## Usage notes

Use a badge group for one short piece of news in a prominent place, such as a release note above a page heading or a status line at the top of a panel. Keep the message to a few words, because it stays on one line. For a label on its own, use [Badge](/docs/components/badge/), and for a message that needs a description or an action, use [Alert](/docs/components/alert/).

Assistive technology reads the addon and the message as one line of text, or as the name of the link. The arrow and the modern dot are decoration and are hidden from it, so the words must carry the meaning; in a link, write the message so that it says where the link goes. A status update is not announced on its own: put feedback that changes while the page is open in a live region.
