Badge Group
A cluster of badges with built-in overflow. Cap how many show inline and the rest fold into a +N chip that reveals the full list in a tooltip, so a long set of tags never blows out its row.
Installation#
Usage#
Wrap your Badge children in BadgeGroup and set max. The group owns only the layout and the overflow affordance: the badges stay plain Badges, styled however you like. The reveal rides the shared Tooltip.
The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.
Have a license? Unlock it here
Anatomy#
import { BadgeGroup } from "@/components/ui/badge-group"
import { Badge } from "@/components/ui/badge"
<BadgeGroup>
<Badge />
</BadgeGroup>Overflow#
max caps the badges shown inline; everything past it collapses into a single +N chip. Hover or focus the chip to reveal the whole list in a tooltip. Omit max to show every badge. On touch, tap the chip.
Fit to width#
Set max="fit" when the room, not a count, should decide: the group shows as many badges as fit its width on one line and folds the rest into the +N chip, recounting as it resizes. The group takes its width from its container, so give it one (a card footer, a table cell, a flex-1 slot).
Wrap#
A group wraps by default, so a row narrower than its badges, on a phone or in a tight column, flows onto more lines instead of being cut. Constrain the width and the badges wrap to fit. Pass wrap={false} to hold one line, or max="fit" to hold it and fold what does not fit.
Overflow chip#
The +N chip defaults to a small outline badge. Match it to the badges it stands in for with overflowVariant and overflowSize, and give it the badges' shape with overflowAppearance.
Motion#
When the count changes, the group moves instead of jumping. A badge that stops fitting closes its slot and the next one slides over; the +N number rolls to the new count. It all holds still under reduced motion. The demo at the top of this page resizes on a loop to show it.
Interactive overflow#
When the badges carry links or a dismiss button, pass interactive so the tooltip stays open while the pointer moves into it, so you can click the contents. Here each tag is dismissible; remove a few and the +N recounts.
Custom overflow#
Take over the tooltip body with renderOverflow, which receives the full list and the hidden slice. Return any node: a titled section, a grid, a different layout for just the hidden badges.
API reference#
BadgeGroup
A <div> that lays out its Badge children and folds the overflow into a +N chip whose tooltip lists them all. Forwards all native <div> props; accepts className, merged last.
| Prop | Type | Default | Description |
|---|---|---|---|
| max | number | "fit" | - | Caps the badges shown inline; the rest collapse into the chip. "fit" shows as many as fit the group's width on one line. Omit to show every badge. |
| wrap | boolean | true | Wraps onto several lines when the row is too narrow. false holds one line. |
| overflowVariant | BadgeProps["variant"] | "outline" | The Badge variant of the +N chip. |
| overflowSize | "sm" | "md" | "lg" | "sm" | The size of the chip. Match it to the badges it stands in for. |
| overflowAppearance | "soft" | "surface" | "solid" | "modern" | "soft" | The Badge appearance of the chip, so it takes the badges' shape. Its count rolls when it changes. |
| overflowLabel | string | "{n} more" | The accessible label of the chip. |
| interactive | boolean | false | Keeps the tooltip open while hovered, for badges with links or a remove button. |
| renderOverflow | (items: React.ReactNode[], hidden: React.ReactNode[]) => React.ReactNode | - | Your own tooltip body, given the full list and the hidden slice. Defaults to the whole list, stacked. |