Siteplane UI

Badge Group

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

Markdown
New featureScheduled reports are here
"use client";

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

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

Installation

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

Complete the one-time setup first. Registry JSON lists source files and dependencies.

Usage

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

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

Composition

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

A badge group is a 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. The addon is a white pill on the tint, in the tint's text color.

New featureScheduled reports are hereUpdateVersion 2.4 is availableSuccessYour domain is verifiedWarningYour trial ends in 3 daysErrorThe last sync failed
"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, so variant names the color of the dot. The message takes the secondary text color and the arrow the tertiary one.

New featureScheduled reports are hereUpdateVersion 2.4 is availableSuccessYour domain is verifiedWarningYour trial ends in 3 daysErrorThe last sync failed
"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.

Scheduled reports are hereNew featureYour domain is verifiedSuccess
"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>
  );
}

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 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.

"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.

New featureScheduled reports are hereNew featureScheduled reports are here
"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.

AISummaries now cover every meetingBetaWorkflows are in beta
"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

Component properties
PropTypeDefaultDescription
BadgeGroup.addonReactNoderequiredThe 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.childrenReactNodeunsetThe message, one line that ends with an ellipsis where the group is full.
BadgeGroup.variantsecondary | info | success | warning | error | slate | sky | blue | indigo | purple | pink | orangeinfoThe tint of the group, or in the modern appearance the color of the addon's dot.
BadgeGroup.appearancelight | modernlightlight 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.addonPositionstart | endstartstart 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.sizemd | lgmdmd 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.iconReactNodearrowThe icon after the message, or inside the addon at the end. null leaves it out. It is decoration, so give it aria-hidden.
BadgeGroup.hrefstringunsetMakes 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.renderReactElement | render functionspanComposes the group onto another element, such as a link component or a button.
BadgeGroup.classNamestringunsetClasses for the group.

BadgeGroupProps extends the props of 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.

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, and for a message that needs a description or an action, use 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.