# OverflowList

Fits as many items as possible in a single row and collapses the rest behind a caller-supplied overflow affordance via `renderOverflow`.

## Examples

### Default

Cap visibility with `maxVisible` and render a `+N` indicator for hidden items.

```tsx
import { OverflowList } from '@var-ui/react';

<OverflowList maxVisible={2} renderOverflow={(hidden) => <span>+{hidden.length}</span>}>
  <OverflowList.Item>Alpha</OverflowList.Item>
  <OverflowList.Item>Beta</OverflowList.Item>
  <OverflowList.Item>Gamma</OverflowList.Item>
</OverflowList>
```

```astro
<!-- No Astro binding yet — use @var-ui/react -->
```

```html
<!-- No HTML demo yet — use @var-ui/react -->
```

### Many items

Omit `maxVisible` so the list measures to fit — with a constrained width and many items, the overflow indicator reports how many are hidden.

```tsx
import { OverflowList } from '@var-ui/react';

<div style={{ width: 220 }}>
  <OverflowList fillParent renderOverflow={(hidden) => <span>+{hidden.length}</span>}>
    <OverflowList.Item>Alpha</OverflowList.Item>
    <OverflowList.Item>Beta</OverflowList.Item>
    {/* …more items… */}
    <OverflowList.Item>Kappa</OverflowList.Item>
  </OverflowList>
</div>
```

```astro
<!-- No Astro binding yet — use @var-ui/react -->
```

```html
<!-- No HTML demo yet — use @var-ui/react -->
```

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| renderOverflow | (hidden: T[] \| ReactElement<any, string \| JSXElementConstructor<any>>[]) => ReactNode | yes |  | Required when overflow can occur — receives the hidden data items or hidden `Item` elements. |
| children | ReactNode | no |  |  |
| className | string \| undefined | no |  |  |
| fillParent | boolean \| undefined | no |  |  |
| gap | number \| OverflowGapToken \| undefined | no |  |  |
| items | T[] \| undefined | no |  |  |
| maxVisible | number \| undefined | no |  | Hard cap applied in addition to measure-to-fit. |
| renderItem | ((item: T, index: number) => ReactNode) \| undefined | no |  |  |

## Accessibility

Compose with `OverflowList.Item` children or an `items` + `renderItem` array. Keep the overflow control keyboard-accessible when it opens a menu (e.g. wrap `renderOverflow` in a button). Hidden items are not in the tab order until revealed.