# useOverflowItems

> A React overflow menu hook (Priority+) that shows what fits in a row and moves the rest into a More menu.

- Type: React hook (Hooks & Utilities)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.1.0
- Install: `npx wingo-ui@latest add use-overflow-items`
- Docs: https://wingo-ui.com/components/use-overflow-items

## Interaction

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.

## Installation

```bash
npx wingo-ui@latest add use-overflow-items
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/use-overflow-items` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `hooks/use-overflow-items.ts`

## Usage

```tsx
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

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` |  | useOverflowItems(options): how many items the row renders. Every item gets getItemProps(index) spread on its outermost element. |
| `collapseOrder?` | `"end" \| "start" \| "middle" \| readonly number[]` | `"end"` | 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. |
| `pinned?` | `readonly number[]` |  | Indexes that never fold: the primary action, the current page of a breadcrumb. |
| `minVisible?` | `number` | `0` | Never fold below this many visible items, even if they overflow. |
| `reserve?` | `number` | `0` | Pixels of the row kept free for something you do not measure (a title that must keep its space). |
| `gap?` | `number` |  | Pixels between items. Default: read from the row's computed column-gap, so gap-2 just works. |
| `disabled?` | `boolean` | `false` | Show every item and stop measuring, e.g. below a breakpoint where CSS already switched to another layout. |
| `moreAlwaysVisible?` | `boolean` | `false` | Keep 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 (type)

The options object: count, collapseOrder, pinned, minVisible, gap, reserve, disabled and moreAlwaysVisible.

### OverflowItemProps (type)

What getItemProps and getMoreProps return: a ref, data attributes, inert, aria-hidden and the hiding style.

### UseOverflowItemsResult (type)

The 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.

## See also

- [Toolbar](https://wingo-ui.com/components/toolbar) ([Markdown](https://wingo-ui.com/components/toolbar.md))
- [Breadcrumb](https://wingo-ui.com/components/breadcrumb) ([Markdown](https://wingo-ui.com/components/breadcrumb.md))
- [Dropdown Menu](https://wingo-ui.com/components/dropdown-menu) ([Markdown](https://wingo-ui.com/components/dropdown-menu.md))
- [useScrollEdges](https://wingo-ui.com/components/use-scroll-edges) ([Markdown](https://wingo-ui.com/components/use-scroll-edges.md))
- [useMediaQuery](https://wingo-ui.com/components/use-media-query) ([Markdown](https://wingo-ui.com/components/use-media-query.md))

---

Canonical: https://wingo-ui.com/components/use-overflow-items
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt