Koala UI

Badge Group

Pro

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.

ReactTypeScriptDesign Systems+4

Installation#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Activate your Pro license (once per machine)npx koalaui-cli@latest login <key># Add this component (its dependencies come along)npx koalaui-cli@latest add badge-group

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.

skills.tsxTSX
import { BadgeGroup } from "@/components/ui/badge-group"import { Badge } from "@/components/ui/badge"export function Skills({ skills }: { skills: string[] }) {  return (    <BadgeGroup max={3}>      {skills.map((skill) => (        <Badge key={skill} variant="secondary" size="sm">          {skill}        </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.

max 2
ReactTypeScript+5
max 4
ReactTypeScriptDesign SystemsNode+3
no max
ReactTypeScriptDesign SystemsNodeGraphQLInfraMotion

Wrap#

Without a cap, set wrap to let a long set flow onto multiple lines instead of staying on one. Constrain the width and the badges wrap to fit.

React TypeScript Design Systems Node GraphQL Infra Motion

Overflow chip#

The +N chip defaults to a small outline badge. Match it to the badges it stands in for with overflowVariant and overflowSize.

ReactTypeScript+5
React TypeScript+5

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.

ReactTypeScriptDesign Systems+4

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.

ReactTypeScriptDesign Systems+4

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.

PropTypeDefaultDescription
maxnumber-Caps the badges shown inline; the rest collapse into the chip. Omit to show every badge.
wrapbooleanfalseWraps onto several lines instead of holding one.
overflowVariantBadgeProps["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.
overflowLabelstring"{n} more"The accessible label of the chip.
interactivebooleanfalseKeeps 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.

FAQ#

Use BadgeGroup when a tag set can overflow its row and you want a clean cap: set `max` and the extras fold into a single `+N` chip that reveals the full list on hover or focus. If you just want a plain row that never overflows, a flex container of `Badge`s is enough.