OverflowList
A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.
Installation
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
Requires React 19+, base CSS and a Theme provider. See Setup.
Overflow List
A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.
| Prop | Type | Default | Description |
|---|---|---|---|
| children * | ReactNode | Items to render. Each child should be a single element. | |
| overflowRenderer | (overflowItems: OverflowItem[]) => ReactNode | Render function for the overflow indicator. Receives the list of hidden items (each with child and index). Only called when items are overflowing. | |
| onOverflowChange | (overflowItems: OverflowItem[]) => void | Called whenever the collapsed set changes: with the collapsed items once something collapses, and with an empty array once the row widens back out. Membership and order changes report even when the count stays the same; unrelated re-renders and callback identity changes do not. Silent while nothing overflows, including on mount. Use stable React keys for dynamic items. | |
| gap | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 2 | Gap between items as a spacing token step (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10). |
| minVisibleItems | number | 0 | Minimum number of items to always show, even when overflowing. |
| maxVisibleItems | number | undefined (no cap) | Maximum number of items to ever show, even when they all fit. The ceiling partner to minVisibleItems; extra items collapse into the overflow indicator. If less than minVisibleItems, the floor wins. |
| maxRows | number | undefined (single line) | Wrap items across up to this many rows before collapsing the rest into the overflow indicator. A number, not a boolean. Leave undefined (or set 1) for single-line behavior. Assumes uniform row height. |
| collapseFrom | 'start' | 'end' | 'end' | Which end to collapse items from when overflow occurs. |
| behavior | 'observeSelf' | 'observeParent' | 'observeSelf' | Controls which element is measured for available width. 'observeSelf' uses the container's own width. 'observeParent' observes the parent element, useful when the list should stay content-sized while still detecting available space. |
| xstyle | StyleXStyles | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object. |
Usage guidance
- Provide a meaningful overflowRenderer: a "+N more" badge, a dropdown, or a count indicator.
- When the row already has its own menu, use onOverflowChange to feed the collapsed items into it instead of adding a second anchor with overflowRenderer.
- Set minVisibleItems to keep key items visible, and maxVisibleItems to cap the row at a fixed count regardless of available width.
- Use maxRows to let items wrap onto a bounded number of rows (e.g. a two-row tag cloud) before collapsing the rest into the indicator.
- Avoid: Use OverflowList for a vertical stack; horizontal multi-row wrap is supported via maxRows, but items still flow left-to-right, not top-to-bottom.
Theming API
{
"targets": [
{
"className": "astryx-overflow-list"
}
]
}
Anatomy
- List: Visible horizontal list container for the currently shown content.
- Items: Caller-supplied items selected for visible display by the current width and count limits.
- Overflow indicator: Optional caller-rendered indicator for items collapsed by width or count limits.
Examples
- Overflow List: A list of buttons that collapses overflowing items into a +N indicator.
- OverflowList — Capped Toolbar: maxVisibleItems caps the row at three actions even when more would fit; the rest move to a dropdown
- OverflowList — Collapse From Start: Overflow list that hides items from the start, keeping the latest visible
- OverflowList — Multi-row Tags: Tags wrap onto up to two rows with maxRows, then collapse the rest into a count badge
- OverflowList — Badge Tags: Resizable row of badges that collapses into a count badge on overflow
- OverflowList — Dropdown Actions: Action toolbar that collapses overflow buttons into a dropdown menu