# OverflowList

- Page: https://jiguang132.com/resources/astryx/docs/overflow-list
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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

```bash
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](/resources/astryx/docs/getting-started).

## 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

```json
{
  "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

---

Index of all JGuang resources: https://jiguang132.com/llms.txt