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.

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Get the code

Have a license? Unlock it here

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.