Badge Overflow

Installation

pnpm dlx shadcn@latest add @diceui/badge-overflow
 

Layout

import { Badge } from "@/components/ui/badge";
import { BadgeOverflow } from "@/components/ui/badge-overflow";
 
<BadgeOverflow renderBadge={(_, label) => <Badge>{label}</Badge>} />

Usage

With Primitive Arrays

When using primitive arrays (strings, numbers), the getBadgeLabel prop is optional. The component will automatically use the item itself as the label.

<BadgeOverflow
  items={["React", "TypeScript", "Next.js"]}
  renderBadge={(item, label) => <Badge>{label}</Badge>}
/>

With Object Arrays

When using object arrays, the getBadgeLabel prop is required to extract the label from each item.

<BadgeOverflow
  items={[
    { id: 1, name: "React" },
    { id: 2, name: "TypeScript" },
  ]}
  getBadgeLabel={(item) => item.name}
  renderBadge={(item, label) => <Badge>{label}</Badge>}
/>

Examples

Multi-line Overflow

Display badges across multiple lines using the lineCount prop.

Interactive Tags

Interactive demo showing how to add and remove tags with overflow handling.

API Reference

BadgeOverflow

The component that measures available space and displays badges with overflow indicators.

Features

Automatic Width Measurement

The component automatically measures badge widths using DOM measurement and caches results for performance. This ensures accurate overflow calculations without manual configuration.

Computed Container Styles

The component automatically extracts container padding, gap, badge height, and overflow badge width from computed styles. This means it adapts seamlessly to your CSS without requiring manual prop configuration.

Multi-line Support

Control how many lines of badges to display using the lineCount prop. The component will intelligently wrap badges across lines while respecting the overflow constraints.

Custom Rendering

Use renderBadge and renderOverflow props to fully customize how badges and overflow indicators are rendered, allowing complete control over styling and behavior.

Performance Optimization

The component renders all badges invisibly to measure their actual widths, then uses those measurements to determine which badges fit within the specified line count. ResizeObserver efficiently responds to container size changes.

Notes

• The component measures actual rendered badges to calculate widths accurately (including icons, custom styling, etc.)
• Container styles (padding, gap, badge height, overflow width) are automatically computed from CSS
• Measurements update automatically when items change or container is resized
• Container must have a defined width for overflow calculations to work