ui/hooks/overflow-items

Overflow Items

hookoverflowresize-observeritems

Measures how many items fit in a container and tracks the overflow count. Uses ResizeObserver for automatic recalculation. Single ref — no hidden measurement rows needed.

tsx

1 const tags = ["React", "TypeScript", "Next.js", "Tailwind", "Vite"];2 3 const { ref, visibleCount, overflowCount } =4   useOverflowItems({ itemCount: tags.length });5 6 return (7   <div ref={ref} className="relative flex items-center gap-2 overflow-clip">8     {tags.map((tag, i) => (9       <div key={i} className={cn("shrink-0", i >= visibleCount && "invisible absolute pointer-events-none")}>10         <span>{tag}</span>11       </div>12     ))}13     <div className={cn("shrink-0", overflowCount === 0 && "invisible absolute pointer-events-none")}>14       <span>+{Math.max(overflowCount, 1)}</span>15     </div>16   </div>17 );

Installation

$pnpm exec dgadd add ui/overflow-items

[Installs to]src/hooks/use-overflow-items.ts[Item]ui/overflow-items

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Parameters

Name	Type	Default	Description
itemCountrequired	number	—	Number of items to lay out. The hook uses this to drive measurement and re-observe on count changes.
onVisibleCountChange	(count: number) => void	—	Called when the visible count changes. Useful for syncing external state without subscribing to the returned visibleCount in a separate effect.

Returns

{ ref: RefCallback<HTMLDivElement>; visibleCount: number; overflowCount: number }A callback ref to attach to the container and reactive counts.

Name	Type	Default	Description
refrequired	RefCallback<HTMLDivElement>	—	Attach to the container element. Conditional mounts and replacement containers are remeasured and observed through the callback lifecycle.
visibleCountrequired	number	—	Number of items that fit within the container width. Use this to hide overflow items via CSS (invisible absolute pointer-events-none).
overflowCountrequired	number	—	Number of items that do not fit (itemCount − visibleCount). Show the overflow indicator when this is greater than zero.

Examples

Basic Overflow Badge

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { useOverflowItems } from "@/hooks/use-overflow-items";5 import { cn } from "@/lib/utils";6 7 const TAGS = ["React", "TypeScript", "Next.js", "Tailwind", "Vite", "Vitest", "Zustand", "Prisma"];8 9 const TAG_COLORS = [10   "text-info-text border-info-border",11   "text-success-text border-success-border",12   "text-warning-text border-warning-border",13   "text-error-text border-error-border",14 ];15 16 function Tag({ label, index }: { label: string; index: number }) {17   return (18     <span19       className={cn(20         "inline-flex shrink-0 items-center border px-1.5 py-0.5 font-mono text-[11px]",21         TAG_COLORS[index % TAG_COLORS.length],22       )}23     >24       {label}25     </span>26   );27 }28 29 function OverflowBadge({ count }: { count: number }) {30   return (31     <span className="inline-flex shrink-0 items-center border border-dashed border-foreground/30 px-1.5 py-0.5 font-mono text-2xs text-muted-foreground">32       +{count}33     </span>34   );35 }36 37 export default function OverflowItemsBasicExample() {38   const [width, setWidth] = useState(300);39 40   const { ref, visibleCount, overflowCount } = useOverflowItems({ itemCount: TAGS.length });41 42   return (43     <div className="flex flex-col gap-4">44       <div className="flex items-center gap-2">45         <label htmlFor="oi-width-range" className="font-mono text-xs text-muted-foreground">46           width:47         </label>48         <input49           id="oi-width-range"50           type="range"51           min={120}52           max={500}53           value={width}54           onChange={(e) => setWidth(Number(e.target.value))}55           className="w-32"56         />57         <span className="font-mono text-xs">{width}px</span>58       </div>59 60       <div61         ref={ref}62         style={{ width }}63         className="relative flex items-center gap-2 overflow-clip border border-dashed border-foreground/20 p-2"64       >65         {TAGS.map((tag, i) => (66           <div67             key={tag}68             className={cn(69               "shrink-0",70               i >= visibleCount && "invisible absolute pointer-events-none",71             )}72           >73             <Tag label={tag} index={i} />74           </div>75         ))}76         <div77           className={cn(78             "shrink-0",79             overflowCount === 0 && "invisible absolute pointer-events-none",80           )}81         >82           <OverflowBadge count={Math.max(overflowCount, 1)} />83         </div>84       </div>85 86       <div className="flex gap-4 font-mono text-xs text-muted-foreground">87         <span>88           visible: <span className="text-success-text">{visibleCount}</span>89         </span>90         <span>91           overflow:{" "}92           <span className={overflowCount > 0 ? "text-error-text" : "text-muted-foreground"}>93             {overflowCount}94           </span>95         </span>96         <span>total: {TAGS.length}</span>97       </div>98     </div>99   );100 }101

Notes

Container Contract

The container's children must follow this order: [item0, item1, ..., itemN-1, indicator]. The first itemCount children are measured as items. The child at index itemCount is measured as the overflow indicator. The container must use CSS gap (e.g. Tailwind gap-* or gap-x-*) — the hook reads the resolved column-gap via getComputedStyle, since it measures a single horizontal row.

Hiding Overflow Items

Items where index >= visibleCount should get 'invisible absolute pointer-events-none' classes. This keeps them in the DOM for measurement while hiding them visually. The indicator should always be rendered (hidden when overflowCount === 0) so the hook can measure its width for space reservation.

No Visual Flash

The hook uses useLayoutEffect which fires before the browser paints. On the first render all items are visible in the flex flow, measured synchronously, then visibleCount is set — triggering a re-render before paint. The user never sees the intermediate state.

Source

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