ui/components/overflow

Overflow

Container-aware overflow handling for items (dynamic fitting with indicator) and text (line clamping with auto-tooltip when truncated).

Preview

tsx

1 "use client";2 3 import { Overflow } from "@/components/ui/overflow";4 5 const tags = ["React", "TypeScript", "Tailwind", "Node.js", "Vitest", "Zod", "Prisma"];6 7 // Each chip is passed as its own React child so Overflow measures them individually;8 // a child may be any element or component, as long as one child means one measured item.9 const CHIP_CLASS =10   "inline-flex items-center rounded-sm border border-foreground/30 px-2 py-0.5 font-mono text-xs text-foreground";11 12 export default function OverflowItemsExample() {13   return (14     <div className="flex flex-col gap-4">15       <div className="space-y-1.5">16         <span className="text-xs font-mono text-muted-foreground">17           default indicator — dashed badge shipped by the component18         </span>19         <div className="w-80 border border-dashed border-foreground/20 p-2">20           <Overflow mode="items" className="gap-1.5">21             {tags.map((tag) => (22               <span key={tag} className={CHIP_CLASS}>23                 {tag}24               </span>25             ))}26           </Overflow>27         </div>28       </div>29 30       <div className="space-y-1.5">31         <span className="text-xs font-mono text-muted-foreground">32           custom indicator — solid, tight radius, matches the chips33         </span>34         <div className="w-80 border border-dashed border-foreground/20 p-2">35           <Overflow36             mode="items"37             className="gap-1.5"38             indicator={({ count }) => (39               <span className="inline-flex items-center rounded-sm border border-foreground/30 bg-foreground/10 px-2 py-0.5 font-mono text-xs text-muted-foreground">40                 +{count} more41               </span>42             )}43           >44             {tags.map((tag) => (45               <span key={tag} className={CHIP_CLASS}>46                 {tag}47               </span>48             ))}49           </Overflow>50         </div>51       </div>52     </div>53   );54 }55

Installation

$pnpm exec dgadd add ui/overflow

[Installs to]src/components/ui/overflow[Item]ui/overflow

dgadd ships in @diffgazer/add on npm: pnpm add -D @diffgazer/add puts it on pnpm exec, and npx @diffgazer/add runs it without the install.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS from the installed package.

Usage

tsx

1 "use client";2 3 import { Overflow } from "@/components/ui/overflow";4 5 const tags = ["React", "TypeScript", "Tailwind", "Node.js", "Vitest", "Zod", "Prisma"];6 7 // Each chip is passed as its own React child so Overflow measures them individually;8 // a child may be any element or component, as long as one child means one measured item.9 const CHIP_CLASS =10   "inline-flex items-center rounded-sm border border-foreground/30 px-2 py-0.5 font-mono text-xs text-foreground";11 12 export default function OverflowItemsExample() {13   return (14     <div className="flex flex-col gap-4">15       <div className="space-y-1.5">16         <span className="text-xs font-mono text-muted-foreground">17           default indicator — dashed badge shipped by the component18         </span>19         <div className="w-80 border border-dashed border-foreground/20 p-2">20           <Overflow mode="items" className="gap-1.5">21             {tags.map((tag) => (22               <span key={tag} className={CHIP_CLASS}>23                 {tag}24               </span>25             ))}26           </Overflow>27         </div>28       </div>29 30       <div className="space-y-1.5">31         <span className="text-xs font-mono text-muted-foreground">32           custom indicator — solid, tight radius, matches the chips33         </span>34         <div className="w-80 border border-dashed border-foreground/20 p-2">35           <Overflow36             mode="items"37             className="gap-1.5"38             indicator={({ count }) => (39               <span className="inline-flex items-center rounded-sm border border-foreground/30 bg-foreground/10 px-2 py-0.5 font-mono text-xs text-muted-foreground">40                 +{count} more41               </span>42             )}43           >44             {tags.map((tag) => (45               <span key={tag} className={CHIP_CLASS}>46                 {tag}47               </span>48             ))}49           </Overflow>50         </div>51       </div>52     </div>53   );54 }55

Examples

Avatars

Preview

tsx

1 "use client";2 3 import { Avatar } from "@/components/ui/avatar";4 import { Overflow } from "@/components/ui/overflow";5 6 const users = [7   { initials: "FX", name: "Felix" },8   { initials: "AR", name: "Aria" },9   { initials: "DV", name: "Dev" },10   { initials: "KI", name: "Kai" },11   { initials: "NV", name: "Nova" },12   { initials: "ZR", name: "Zara" },13   { initials: "LN", name: "Luna" },14   { initials: "RX", name: "Rex" },15 ];16 17 // Custom count chip: solid border and tight radius, matching the avatar chips.18 // The dashed border is reserved for the component's own default indicator.19 const COUNT_CHIP_CLASS =20   "flex h-6 w-6 shrink-0 items-center justify-center rounded-sm border border-foreground/30 font-mono text-2xs text-muted-foreground";21 22 export default function OverflowAvatarsExample() {23   return (24     <div className="flex flex-col gap-4">25       <div className="space-y-1.5">26         <span className="text-xs font-mono text-muted-foreground">w-32</span>27         <div className="w-32 border border-dashed border-foreground/20 p-2">28           <Overflow29             mode="items"30             indicator={({ count }) => <span className={COUNT_CHIP_CLASS}>+{count}</span>}31           >32             {users.map((u) => (33               <Avatar key={u.initials} alt={u.name} fallback={u.initials} size="sm" />34             ))}35           </Overflow>36         </div>37       </div>38 39       <div className="space-y-1.5">40         <span className="text-xs font-mono text-muted-foreground">w-48</span>41         <div className="w-48 border border-dashed border-foreground/20 p-2">42           <Overflow43             mode="items"44             indicator={({ count }) => <span className={COUNT_CHIP_CLASS}>+{count}</span>}45           >46             {users.map((u) => (47               <Avatar key={u.initials} alt={u.name} fallback={u.initials} size="sm" />48             ))}49           </Overflow>50         </div>51       </div>52     </div>53   );54 }55

Text

Preview

tsx

1 import { Overflow } from "@/components/ui/overflow";2 3 export default function OverflowTextExample() {4   const longText =5     "This is a very long description that demonstrates how the Overflow component handles text truncation with automatic ellipsis and native browser tooltips on hover.";6 7   return (8     <div className="flex flex-col gap-4">9       <div className="space-y-1.5">10         <span className="text-xs font-mono text-muted-foreground">11           lines=1 (truncate) — hover the clipped line for the auto tooltip12         </span>13         <div className="w-64 border border-dashed border-foreground/20 p-2">14           <Overflow mode="text">{longText}</Overflow>15         </div>16       </div>17 18       <div className="space-y-1.5">19         <span className="text-xs font-mono text-muted-foreground">lines=2 (clamp)</span>20         <div className="w-64 border border-dashed border-foreground/20 p-2">21           <Overflow mode="text" lines={2}>22             {longText}23           </Overflow>24         </div>25       </div>26 27       <div className="space-y-1.5">28         <span className="text-xs font-mono text-muted-foreground">lines=3 (clamp)</span>29         <div className="w-64 border border-dashed border-foreground/20 p-2">30           <Overflow mode="text" lines={3}>31             {longText}32           </Overflow>33         </div>34       </div>35     </div>36   );37 }38

API Reference

Overflow

Name	Type	Default	Description
mode	"text" \| "items"	"text"	Selects fitting-items mode when set to items; text clamps string content with optional auto-tooltip, while items measures children and renders an overflow indicator for those that do not fit.
childrenrequired	string (text mode) \| ReactNode (items mode)	—	Items to fit into the available width; string to clamp (text mode) or items to measure (items mode).
lines	number	1	Text mode only. 1 truncates; 2+ uses CSS line-clamp.
tooltip	ReactNode \| boolean	—	Text mode only. true/ReactNode renders a Tooltip when content is actually clipped (auto-derived from children when true). false disables the tooltip.
indicator	ReactNode \| ((props: { count: number }) => ReactNode)	dashed ellipsis badge	Custom indicator shown for items that do not fit. Items mode only; render function or static node shown when items overflow.
getOverflowLabel	(count: number) => string	count => count + " more items"	Items mode only. Localizes the accessible name announced for the overflow indicator.
className	string	—	Merged onto the root. Items mode ships gap-1 between items and indicator; override it here (for example gap-1.5).

Accessibility

Notes

Two Modes

Text mode is the default: CSS truncation with useOverflowDetection hook detecting actual overflow + Tooltip that only appears when content is truly clipped. Items mode requires mode="items" and measures children against container width via ResizeObserver, showing what fits plus an overflow indicator.

Items Mode

Uses a hidden measurement row to calculate widths before paint (no flicker). Default indicator is an ellipsis badge. Customize via the indicator prop — pass a render function ({ count }) => ReactNode or static ReactNode.

Indicator Convention

The built-in indicator is a dashed badge: dashed means 'the library put this here'. Custom indicators are solid so a consumer-authored count reads as content. Keep custom indicators on the tight radius (rounded-sm or none) so they match neighbouring chips.

Text Mode

Set lines={1} for single-line truncate or lines={2+} for multi-line clamping. Tooltip auto-derives content from string children. Set tooltip={false} to disable, or tooltip={<custom>} for custom content.

useOverflowDetection Hook

The overflow detection logic is available as a standalone hook (overflow-detection registry item). Use it independently for custom overflow UIs.

Source

Install via CLI: pnpm exec dgadd add ui/overflow. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Overflow

Installation

Usage

Examples

Avatars

Text

API Reference

Overflow

Accessibility

Notes

Two Modes

Items Mode

Indicator Convention

Text Mode

useOverflowDetection Hook

Source

View component source (39 files)