> For AI agents: the complete documentation index is available at https://wallarm.github.io/design-system/llms.txt, the full documentation bundle is available at https://wallarm.github.io/design-system/llms-full.txt.

# OverflowList

Lays a set of items out in one row and folds whatever will not fit into an overflow control — reach for `OverflowTooltip` instead when the thing overrunning is a single run of text rather than a set. By default the overflow is a `+N more` chip opening a popover of every item; compose it yourself from the `OverflowListMore` parts (`Trigger`, `Content`, `Header`, `Items`, `Count`), or pass any `overflowRenderer(hiddenItems, { allItems, visibleItems })` of your own. It re-measures whenever the container changes width.

[Source](https://github.com/wallarm/design-system/tree/main/packages/design-system/src/components/OverflowList) · [Storybook](https://wallarm.github.io/design-system/storybook/?path=/docs/data-display-overflowlist--overview)

```tsx
import { OverflowList } from '@wallarm-org/design-system/OverflowList';
import { Tag } from '@wallarm-org/design-system/Tag';

export const Basic = () => (
  <div className='w-640'>
    <OverflowList
      className='gap-4'
      items={TAGS}
      itemRenderer={item => <Tag key={item}>{item}</Tag>}
    />
  </div>
);
```

## Usage

```tsx
import { OverflowList } from '@wallarm-org/design-system/OverflowList';
import { Tag } from '@wallarm-org/design-system/Tag';
```

## Examples

### Collapsed

The same nine in 200px: two survive and the `+N` takes the rest, which is the whole job.

```tsx
import { OverflowList } from '@wallarm-org/design-system/OverflowList';
import { Tag } from '@wallarm-org/design-system/Tag';

export const Collapsed = () => (
  <div className='w-200'>
    <OverflowList
      className='gap-4'
      items={TAGS}
      itemRenderer={item => <Tag key={item}>{item}</Tag>}
    />
  </div>
);
```

### Collapse from start

`collapseFrom='start'` hides the beginning and keeps the end in view — for a path or a
history where the most recent items are the ones that matter.

```tsx
import { OverflowList } from '@wallarm-org/design-system/OverflowList';
import { Tag } from '@wallarm-org/design-system/Tag';

export const CollapseFromStart = () => (
  <div className='w-240'>
    <OverflowList
      className='gap-4'
      collapseFrom='start'
      items={TAGS}
      itemRenderer={item => <Tag key={item}>{item}</Tag>}
    />
  </div>
);
```

### Min visible items

`minVisibleItems` puts a floor under the measurement: however tight the column gets,
that many items stay and the rest go to the `+N` rather than the row emptying out.

```tsx
import { OverflowList } from '@wallarm-org/design-system/OverflowList';
import { Tag } from '@wallarm-org/design-system/Tag';

export const MinVisibleItems = () => (
  <div className='w-160 overflow-hidden rounded-2 border border-border-primary p-12'>
    <OverflowList
      className='gap-4'
      minVisibleItems={1}
      items={TAGS}
      itemRenderer={item => <Tag key={item}>{item}</Tag>}
    />
  </div>
);
```

### Resizable container

Drag the box's right edge: the split is re-measured as the width changes rather than at
breakpoints, which is what makes it safe inside a resizable panel.

```tsx
import { OverflowList } from '@wallarm-org/design-system/OverflowList';
import { Tag } from '@wallarm-org/design-system/Tag';

export const ResizableContainer = () => (
  <div
    data-testid='resizable-wrapper'
    className='overflow-hidden rounded-2 border border-border-primary p-12'
    style={{ width: 500, minWidth: 80, maxWidth: 800, resize: 'horizontal' }}
  >
    <OverflowList
      className='gap-4'
      data-testid='tags'
      items={TAGS}
      itemRenderer={item => <Tag key={item}>{item}</Tag>}
    />
  </div>
);
```

### With header

The full composition: a header counting every item over the popover list, built from
`OverflowListMoreHeader` and `OverflowListMoreCount` in plain JSX. Items already in the
row are listed first and faded.

```tsx
import { OverflowList, OverflowListMore, OverflowListMoreContent, OverflowListMoreCount, OverflowListMoreHeader, OverflowListMoreItems, OverflowListMoreTrigger } from '@wallarm-org/design-system/OverflowList';
import { Tag } from '@wallarm-org/design-system/Tag';

export const WithHeader = () => (
  <div className='w-120'>
    <OverflowList
      className='gap-4'
      data-testid='attacks'
      items={ATTACK_TYPES}
      itemRenderer={item => <Tag key={item}>{item}</Tag>}
      overflowRenderer={() => (
        <OverflowListMore>
          <OverflowListMoreTrigger />
          <OverflowListMoreContent>
            <OverflowListMoreHeader>
              <OverflowListMoreCount of='total' /> attack types
            </OverflowListMoreHeader>
            <OverflowListMoreItems />
          </OverflowListMoreContent>
        </OverflowListMore>
      )}
    />
  </div>
);
```

### Hidden only

`show='hidden'` lists only what the row folded away — the pattern for editable
contexts such as a multi-select input, where the visible chips are right there.

```tsx
import { OverflowList, OverflowListMore, OverflowListMoreContent, OverflowListMoreCount, OverflowListMoreItems, OverflowListMoreTrigger } from '@wallarm-org/design-system/OverflowList';
import { Tag } from '@wallarm-org/design-system/Tag';

export const HiddenOnly = () => (
  <div className='w-120'>
    <OverflowList
      className='gap-4'
      data-testid='attacks'
      items={ATTACK_TYPES}
      itemRenderer={item => <Tag key={item}>{item}</Tag>}
      overflowRenderer={() => (
        <OverflowListMore>
          <OverflowListMoreTrigger>
            +<OverflowListMoreCount />
          </OverflowListMoreTrigger>
          <OverflowListMoreContent>
            <OverflowListMoreItems show='hidden' />
          </OverflowListMoreContent>
        </OverflowListMore>
      )}
    />
  </div>
);
```

### Cover placement

`placement='cover'` opens the popover over the row itself, from its left edge.

```tsx
import { OverflowList, OverflowListMore } from '@wallarm-org/design-system/OverflowList';
import { Tag } from '@wallarm-org/design-system/Tag';

export const CoverPlacement = () => (
  <div className='w-120'>
    <OverflowList
      className='gap-4'
      data-testid='attacks'
      items={ATTACK_TYPES}
      itemRenderer={item => <Tag key={item}>{item}</Tag>}
      overflowRenderer={() => <OverflowListMore placement='cover' />}
    />
  </div>
);
```

### Pluralized header

When the header needs the number as a value — pluralization, i18n — read it with
`useOverflowListMore()` inside your own component instead of `OverflowListMoreCount`.

```tsx
import { OverflowList, OverflowListMore, OverflowListMoreContent, OverflowListMoreItems, OverflowListMoreTrigger } from '@wallarm-org/design-system/OverflowList';
import { Tag } from '@wallarm-org/design-system/Tag';

export const PluralizedHeader = () => (
  <div className='w-120'>
    <OverflowList
      className='gap-4'
      items={ATTACK_TYPES}
      itemRenderer={item => <Tag key={item}>{item}</Tag>}
      overflowRenderer={() => (
        <OverflowListMore>
          <OverflowListMoreTrigger />
          <OverflowListMoreContent>
            <PluralHeader />
            <OverflowListMoreItems />
          </OverflowListMoreContent>
        </OverflowListMore>
      )}
    />
  </div>
);
```

### Custom renderer

`overflowRenderer` is just a function of the hidden items — anything goes, no popover
required.

```tsx
import { OverflowList } from '@wallarm-org/design-system/OverflowList';
import { Tag } from '@wallarm-org/design-system/Tag';

export const CustomRenderer = () => (
  <div className='w-120'>
    <OverflowList
      className='gap-4'
      items={ATTACK_TYPES}
      itemRenderer={item => <Tag key={item}>{item}</Tag>}
      overflowRenderer={hidden => <Tag>and {hidden.length} others</Tag>}
    />
  </div>
);
```

## Props

| Prop                 | Type                                                 | Default | Description                                                                                                                                                                                                    |
| -------------------- | ---------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| items \*             | `T[]`                                                |         | Measurements are cached by array identity — keep it referentially stable.                                                                                                                                      |
| itemRenderer \*      | `(item: T, index: number) => ReactNode`              |         |                                                                                                                                                                                                                |
| overflowRenderer     | `OverflowListRenderer<T> \| undefined`               |         | Renders the overflow indicator. Also called once in the hidden measurement layer with every item hidden, so it must be pure. Compose it from the `OverflowListMore` parts; defaults to `<OverflowListMore />`. |
| minVisibleItems      | `number \| undefined`                                |         | Keep at least this many items visible however narrow the row gets.                                                                                                                                             |
| onOverflow           | `((hiddenItems: T[]) => void) \| undefined`          |         |                                                                                                                                                                                                                |
| collapseFrom         | `CollapseDirection \| undefined`                     |         |                                                                                                                                                                                                                |
| alwaysRenderOverflow | `boolean \| undefined`                               |         | Call `overflowRenderer` even when nothing is hidden. `OverflowListMore` itself renders nothing at zero hidden items.                                                                                           |
| defaultChecked       | `boolean \| undefined`                               |         |                                                                                                                                                                                                                |
| defaultValue         | `string \| number \| readonly string[] \| undefined` |         |                                                                                                                                                                                                                |
| autoFocus            | `boolean \| undefined`                               |         |                                                                                                                                                                                                                |
| id                   | `string \| undefined`                                |         |                                                                                                                                                                                                                |
| tabIndex             | `number \| undefined`                                |         |                                                                                                                                                                                                                |
| title                | `string \| undefined`                                |         |                                                                                                                                                                                                                |
| rel                  | `string \| undefined`                                |         |                                                                                                                                                                                                                |
| onChange             | `ChangeEventHandler<T, Element> \| undefined`        |         |                                                                                                                                                                                                                |
| data-testid          | `string \| undefined`                                |         |                                                                                                                                                                                                                |

### OverflowListMore

| Prop         | Type                                     | Default   | Description                                                                                                             |
| ------------ | ---------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- |
| placement    | `"trigger" \| "cover" \| undefined`      | `trigger` | `trigger` — the popover opens below the "+N" chip. `cover` — the popover opens over the row, from the list's left edge. |
| open         | `boolean \| undefined`                   |           |                                                                                                                         |
| onOpenChange | `((open: boolean) => void) \| undefined` |           |                                                                                                                         |
| data-testid  | `string \| undefined`                    |           |                                                                                                                         |

### OverflowListMoreContent

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| title          | `string \| undefined`                                |         |             |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |
| data-testid    | `string \| undefined`                                |         |             |
| minWidth       | `PopoverSizeDimension \| undefined`                  |         |             |
| maxWidth       | `PopoverSizeDimension \| undefined`                  | `360px` |             |
| minHeight      | `PopoverSizeDimension \| undefined`                  | `auto`  |             |
| maxHeight      | `PopoverSizeDimension \| undefined`                  |         |             |

### OverflowListMoreCount

| Prop           | Type                                                 | Default  | Description                                                      |
| -------------- | ---------------------------------------------------- | -------- | ---------------------------------------------------------------- |
| of             | `"hidden" \| "total" \| undefined`                   | `hidden` | `hidden` — items folded into the overflow; `total` — every item. |
| title          | `string \| undefined`                                |          |                                                                  |
| defaultChecked | `boolean \| undefined`                               |          |                                                                  |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |          |                                                                  |
| autoFocus      | `boolean \| undefined`                               |          |                                                                  |
| id             | `string \| undefined`                                |          |                                                                  |
| tabIndex       | `number \| undefined`                                |          |                                                                  |
| rel            | `string \| undefined`                                |          |                                                                  |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |          |                                                                  |
| data-testid    | `string \| undefined`                                |          |                                                                  |

### OverflowListMoreHeader

| Prop           | Type                                                                              | Default | Description |
| -------------- | --------------------------------------------------------------------------------- | ------- | ----------- |
| title          | `string \| undefined`                                                             |         |             |
| defaultChecked | `boolean \| undefined`                                                            |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined`                              |         |             |
| autoFocus      | `boolean \| undefined`                                                            |         |             |
| id             | `string \| undefined`                                                             |         |             |
| tabIndex       | `number \| undefined`                                                             |         |             |
| rel            | `string \| undefined`                                                             |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`                                     |         |             |
| asChild        | `boolean \| undefined`                                                            |         |             |
| data-testid    | `string \| undefined`                                                             |         |             |
| align          | `{ left: string; center: string; right: string; }`                                |         |             |
| inline         | `{ true: string; }`                                                               |         |             |
| grow           | `{ true: string; }`                                                               |         |             |
| truncate       | `{ true: string; false: string; }`                                                |         |             |
| decoration     | `{ dashed: string; }`                                                             |         |             |
| lineHeight     | `{ none: string; tight: string; snug: string; normal: string; relaxed: string; }` |         |             |
| textTransform  | `{ uppercase: string; lowercase: string; capitalize: string; none: string; }`     |         |             |
| lineClamp      | `number \| undefined`                                                             |         |             |

### OverflowListMoreItems

| Prop           | Type                                                   | Default | Description                                                                                                                               |
| -------------- | ------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| show           | `"hidden" \| "all" \| undefined`                       | `all`   | `all` lists every item (visible ones first); `hidden` only the folded ones.                                                               |
| dimVisible     | `boolean \| undefined`                                 | `true`  | Fade the items that are already visible in the row. Only with `show='all'`.                                                               |
| renderItem     | `((item: T, index: number) => ReactNode) \| undefined` |         | Item renderer for the popover. Defaults to the list's `itemRenderer`. `T` is not linked to the list's item type — annotate the parameter. |
| title          | `string \| undefined`                                  |         |                                                                                                                                           |
| defaultChecked | `boolean \| undefined`                                 |         |                                                                                                                                           |
| defaultValue   | `string \| number \| readonly string[] \| undefined`   |         |                                                                                                                                           |
| autoFocus      | `boolean \| undefined`                                 |         |                                                                                                                                           |
| id             | `string \| undefined`                                  |         |                                                                                                                                           |
| tabIndex       | `number \| undefined`                                  |         |                                                                                                                                           |
| rel            | `string \| undefined`                                  |         |                                                                                                                                           |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`          |         |                                                                                                                                           |
| data-testid    | `string \| undefined`                                  |         |                                                                                                                                           |

### OverflowListMoreTrigger

| Prop           | Type                                                  | Default | Description |
| -------------- | ----------------------------------------------------- | ------- | ----------- |
| size           | `"small" \| "medium" \| "large" \| null \| undefined` |         |             |
| title          | `string \| undefined`                                 |         |             |
| defaultChecked | `boolean \| undefined`                                |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined`  |         |             |
| autoFocus      | `boolean \| undefined`                                |         |             |
| id             | `string \| undefined`                                 |         |             |
| tabIndex       | `number \| undefined`                                 |         |             |
| rel            | `string \| undefined`                                 |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`         |         |             |
| type           | `"button" \| "submit" \| "reset" \| undefined`        |         |             |
| disabled       | `boolean \| undefined`                                |         |             |
| name           | `string \| undefined`                                 |         |             |
| data-testid    | `string \| undefined`                                 |         |             |