react-responsive-overflow-list

Responsive list for React that shows only items that fit and groups the rest into a customizable overflow element. Recalculates on resize.

🔗 Live demo: https://eliav2.github.io/react-responsive-overflow-list/

Features

• Accurate & responsive: measures real layout after paint (ResizeObserver), not guessed widths
• Two usage modes: children (simple) or items + renderItem (structured)
• Customizable overflow element; ships with a lightweight default
• Multi-row support (via maxRows)
• Handles uneven widths, including a single ultra-wide item
• TypeScript types; zero runtime deps (React as peer)
• SSR-friendly: measurement runs on the client
• No implicit wrappers around your items. (layout behaves as you expect)

Install

npm i react-responsive-overflow-list

shadcn/ui

Install as a styled shadcn component with dropdown menu overflow:

# Radix UI primitives (recommended)
npx shadcn@latest add https://eliav2.github.io/react-responsive-overflow-list/r/styles/radix-vega/overflow-list.json

# Base UI primitives
npx shadcn@latest add https://eliav2.github.io/react-responsive-overflow-list/r/styles/base-vega/overflow-list.json

See shadcn/ui docs for usage.

Usage

In real apps, you’ll typically wrap OverflowList in your own component—design tokens, accessible menus, virtualization, or search. See 'Wrap & extend' below and the demo for a full wrapper example.

Items + renderItem (most common)

Minimal usage with an items array and render function.

import { OverflowList } from "react-responsive-overflow-list";

const items = ["One", "Two", "Three", "Four", "Five"];

export default function Example() {
  return (
    <OverflowList
      items={items}
      renderItem={(item) => <span style={{ padding: 4 }}>{item}</span>}
      style={{ gap: 8 }} // root is display:flex; flex-wrap:wrap
      maxRows={1}
    />
  );
}

Children pattern

Use children instead of items + renderItem.

<OverflowList style={{ gap: 8 }}>
  <button>A</button>
  <button>B</button>
  <button>C</button>
  <button>D</button>
</OverflowList>

Custom overflow element

Provide your own overflow UI (button, menu, details/summary, etc.).

<OverflowList
  items={items}
  renderItem={(item) => <span>{item}</span>}
  renderOverflow={(hidden) => <button>+{hidden.length} more</button>}
/>

Polymorphic root

Render using a different HTML element via as.

<OverflowList as="nav">
  <a href="#home">Home</a>
  <a href="#about">About</a>
  <a href="#contact">Contact</a>
</OverflowList>

Performance control

Trade visual smoothness vs peak performance during rapid resize.

<OverflowList
  items={items}
  renderItem={(item) => <span>{item}</span>}
  flushImmediately={false} // uses rAF; faster under rapid resize, may flicker briefly
/>

See the Flush Immediately example in the live demo.

API (most used)

| Prop | Type | Default | Notes | | ---------------------- | ---------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------- | | items | T[] | — | Use with renderItem. Omit when using children. | | renderItem | (item: T, index: number) => ReactNode | — | How to render each item. | | children | ReactNode | — | Alternative to items + renderItem. | | as | React.ElementType | "div" | Polymorphic root element. | | maxRows | number | 1 | Visible rows before overflow. | | maxVisibleItems | number | 100 | Hard cap on visible items. | | renderOverflow | (hidden: T[]) => ReactNode | default chip | Custom overflow UI. | | renderOverflowItem | (item: T, i: number) => ReactNode | renderItem | For expanded lists/menus. | | renderOverflowProps | Partial<OverflowElementProps<T>> | — | Props for default overflow. | | flushImmediately | boolean | true | true (flushSync, no flicker) vs false (rAF, faster under resize). | | renderItemVisibility | (node: ReactNode, meta: RenderItemVisibilityMeta) => ReactNode | internal | Control visibility of hidden items (defaults to React.Activity if available, otherwise simply return null). |

Styles: Root uses display:flex; flex-wrap:wrap; align-items:center;. Override via style/className.

Default overflow element: A tiny chip that renders +{count} more. Replace via renderOverflow.

Headless hook (useOverflowList)

Same measurement engine, bring your own layout. Use this when the <OverflowList /> render shape doesn't fit — e.g. a filter chip bar with custom slots, a layout that interleaves overflow logic with other elements, or any case where you want full control of the JSX.

Attach containerRef to your wrap container and overflowIndicatorRef to your +N element. Render all items during the "measuring" phase so widths are observable; unmount overflowed items (or use display:none / React.Activity) in the "normal" phase — they must not consume layout space, or the overflow indicator can't fit on the last row.

import { useOverflowList } from "react-responsive-overflow-list";

const items = ["One", "Two", "Three", "Four", "Five", "Six"];

export function CustomChipBar() {
  const { containerRef, overflowIndicatorRef, visibleCount, hiddenCount, phase, showOverflow } =
    useOverflowList<HTMLDivElement, HTMLSpanElement>({ itemCount: items.length, maxRows: 1 });

  return (
    <div ref={containerRef} style={{ display: "flex", flexWrap: "wrap", gap: 8, minWidth: 0 }}>
      {items.map((item, index) => {
        const visible = phase === "measuring" || index < visibleCount;
        if (!visible) return null;
        return <span key={index} style={{ padding: 4 }}>{item}</span>;
      })}
      {showOverflow && <span ref={overflowIndicatorRef}>+{hiddenCount} more</span>}
    </div>
  );
}

Hook options

| Option | Type | Default | Notes | | ------------------ | --------- | ------- | ---------------------------------------------------------- | | itemCount | number | — | Total items the consumer will render. | | maxRows | number | 1 | Visible rows before overflow. | | maxVisibleItems | number | 100 | Hard cap on visible items. | | flushImmediately | boolean | true | true (flushSync, no flicker) vs false (rAF, smoother). |

Hook return

| Property | Type | Notes | | ---------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------- | | containerRef | React.RefObject<T \| null> | Attach to the flex-wrap container. | | overflowIndicatorRef | React.RefObject<T \| null> | Attach to the +N indicator element so its width is measured. | | visibleCount | number | Final count of items that fit (already accounts for the indicator's reserved row). | | hiddenCount | number | itemCount - visibleCount. | | phase | "normal" \| "measuring" \| "measuring-overflow-indicator" | Gate item visibility on this — render all during "measuring". | | showOverflow | boolean | true when the overflow indicator should be rendered. |

Wrap & extend

It’s expected you’ll wrap OverflowList for product needs (design system styling, a11y menus, virtualization, search). for example:

• Radix UI + Virtualization wrapper (search, large datasets, a11y, perf):

  • Demo: see Radix UI + Virtualization in the live site
  • Source
  • Uses @tanstack/react-virtual and the helper createLimitedRangeExtractor(...).

How it works

1. Measure all items and compute how many fit within maxRows.
2. Re-test with the overflow indicator; if it would create a new row, hide one more item.
3. Render the stable “normal” state until container size changes.

flushImmediately=true → immediate, flicker-free (uses flushSync). flushImmediately=false → defer with rAF; smoother under rapid resize, may flicker.

Edge cases handled

• Single wide item exceeding container width
• maxRows / maxVisibleItems respected
• Varying item widths, responsive content
• Multi-row overflow detection

Hidden items & React versions

• In React 19.2+, hidden items use React.Activity so overflowed children stay mounted while toggling visibility.
• In React 16–18, overflowed nodes unmount during measurement; pass renderItemVisibility if you need to keep custom elements or skeletons mounted and control visibility yourself.

Requirements

• React ≥ 16.8 (hooks)
• Modern browsers with ResizeObserver

License

MIT