useOverflowItems React hook in TypeScript
v1.1.0Updated in 1.12.0
A React overflow menu hook (Priority+) that shows what fits in a row and moves the rest into a More menu.
Drag the corner of the panel to make it narrower or wider: actions that no longer fit fold into the More button one by one, and come back as soon as there is room. The breadcrumb collapses from the middle, keeping the first page and the current one. Open More to reach the hidden actions with the keyboard or a tap.
useOverflowItems is a Pro React hook in the React hooks and utilities category, written in TypeScript for React 19. It installs as source with npx wingo-ui@latest add use-overflow-items.
Add to a project
Requirements: React 19, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup
npx wingo-ui@latest add use-overflow-itemsuseOverflowItems is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans
Usage
Import useOverflowItems from @/hooks/use-overflow-items.
import { MoreHorizontal } from "lucide-react"
import { Button } from "@/components/ui/button"
import { useOverflowItems } from "@/hooks/use-overflow-items"
const ACTIONS = ["Edit", "Duplicate", "Download PDF", "Send by email", "Archive"]
export function InvoiceActions() {
const { containerRef, getItemProps, getMoreProps, hiddenIndexes } = useOverflowItems({ count: ACTIONS.length })
return (
<div ref={containerRef} className="relative flex min-w-0 items-center gap-2 overflow-hidden">
{ACTIONS.map((label, i) => (
<Button key={label} variant="outline" size="sm" className="shrink-0" {...getItemProps(i)}>
{label}
</Button>
))}
<Button variant="ghost" size="icon-sm" aria-label={`${hiddenIndexes.length} more actions`} {...getMoreProps()}>
<MoreHorizontal />
</Button>
</div>
)
}API
count*numberuseOverflowItems(options): how many items the row renders. Every item gets getItemProps(index) spread on its outermost element.
collapseOrderdefault"end""end" | "start" | "middle" | readonly number[]Which items fold first. end: the last one (actions, tabs). start: the first one. middle: from the second item on, keeping the first and last (breadcrumbs). Or explicit indexes, first to fold first.
pinnedreadonly number[]Indexes that never fold: the primary action, the current page of a breadcrumb.
minVisibledefault0numberNever fold below this many visible items, even if they overflow.
reservedefault0numberPixels of the row kept free for something you do not measure (a title that must keep its space).
gapnumberPixels between items. Default: read from the row's computed column-gap, so gap-2 just works.
disableddefaultfalsebooleanShow every item and stop measuring, e.g. below a breakpoint where CSS already switched to another layout.
moreAlwaysVisibledefaultfalsebooleanKeep the More trigger on screen even when every item fits, for rows where some entries always live in the menu. getMoreProps() stays visible and its width is always kept free.
returns{ containerRef; getItemProps(index); getMoreProps(); isHidden(index); hiddenIndexes: number[]; overflowing: boolean; measured: boolean }containerRef goes on the row (its content width is the budget). Spread getItemProps(i) on each item and getMoreProps() on the More trigger: a folded item stays mounted but invisible, out of the flow, inert and aria-hidden, so it is measured all the time and returns the moment there is room. Render hiddenIndexes in the overflow menu. Items should be shrink-0 and whitespace-nowrap. measured is false on the server and before the first measurement: keep the row overflow-hidden until then.
Parts
OverflowCollapseOrder
type"end" | "start" | "middle" | readonly number[]: which items fold first; an array lists indexes in folding order.
UseOverflowItemsOptions
typeThe options object: count, collapseOrder, pinned, minVisible, gap, reserve, disabled and moreAlwaysVisible.
OverflowItemProps
typeWhat getItemProps and getMoreProps return: a ref, data attributes, inert, aria-hidden and the hiding style.
UseOverflowItemsResult
typeThe return value: containerRef, getItemProps, getMoreProps, isHidden, hiddenIndexes, overflowing and measured.
Examples
Collapse from the start
collapseOrder="start" keeps the last actions, so Archive and Delete stay in reach.
Keep at least two
minVisible 2 never folds the first two actions, even when they barely fit.
Breadcrumb that folds the middle
collapseOrder="middle" with the current page pinned, like a file path in a narrow column.
Dependencies
No dependencies beyond React.
Files
- hooks/use-overflow-items.ts
FAQ
Is the useOverflowItems hook free?
The preview, props and docs are free; copying the source needs a Pro plan. See plans.
How do I install useOverflowItems?
Run npx wingo-ui@latest add use-overflow-items. With shadcn, add the @wingo-ui registry with your API key, then run npx shadcn@latest add @wingo-ui/use-overflow-items.