ui/hooks/overflow-detection

Overflow Detection

hookoverflowresize-observerdetection

Detects whether an element's content overflows its container using ResizeObserver. Returns a ref to attach and a reactive boolean — no polling, no manual recalculation.

tsx

1 const { ref, isOverflowing } = useOverflowDetection("horizontal");2 3 return (4   <div ref={ref} className="truncate">5     {text}6     {isOverflowing && <span>…</span>}7   </div>8 );

Installation

$pnpm exec dgadd add ui/overflow-detection

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

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.

Parameters

Name	Type	Default	Description
direction	"horizontal" \| "vertical" \| "both"	—	Which axis to check for overflow. "horizontal" compares scrollWidth > clientWidth, "vertical" compares scrollHeight > clientHeight, "both" checks either. Defaults to "horizontal".

Returns

{ ref: RefCallback<T>; isOverflowing: boolean }A callback ref to attach to the observed element, and a boolean that updates reactively when overflow state changes.

Name	Type	Default	Description
refrequired	RefCallback<T>	—	Attach to the element whose overflow you want to detect. Conditional mounts and replacement nodes are observed when the callback receives them. The element must have constrained dimensions (width/height).
isOverflowingrequired	boolean	—	True when content exceeds container bounds in the specified direction.

Examples

Basic Detection

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { useOverflowDetection } from "@/hooks/use-overflow-detection";5 6 export default function OverflowDetectionBasicExample() {7   const [width, setWidth] = useState(200);8   const { ref, isOverflowing } = useOverflowDetection<HTMLDivElement>();9 10   const text = "This text will overflow when the container is too narrow to fit it all.";11 12   return (13     <div className="flex flex-col gap-4">14       <div className="flex items-center gap-2">15         <label htmlFor="od-width-range" className="font-mono text-xs text-muted-foreground">16           width:17         </label>18         <input19           id="od-width-range"20           type="range"21           min={80}22           max={400}23           value={width}24           onChange={(e) => setWidth(Number(e.target.value))}25           className="w-32"26         />27         <span className="font-mono text-xs">{width}px</span>28       </div>29 30       <div style={{ width }} className="border border-dashed border-foreground/20 p-2">31         <div ref={ref} className="truncate font-mono text-sm">32           {text}33         </div>34       </div>35 36       <span className="font-mono text-xs">37         isOverflowing:{" "}38         <span className={isOverflowing ? "text-error-text" : "text-success-text"}>39           {String(isOverflowing)}40         </span>41       </span>42     </div>43   );44 }45

Notes

Common Use Cases

Conditionally showing tooltips on truncated text, toggling expand/collapse buttons, applying visual indicators when content is clipped.

Requirement

The ref'd element must have constrained dimensions. For horizontal detection, the element needs a width constraint (e.g. truncate, max-w-*, fixed width). For vertical, it needs a height constraint.

Source

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