OverflowList

Renders as many items as fit in one row and collapses the remainder into a custom overflow indicator. To measure natural item widths accurately, `OverflowList` renders every child in a hidden, inert measurement row, then renders the visible slice again. Visible child components therefore mount twice, and even collapsed children mount once for measurement. Avoid using it for hundreds of expensive items without first virtualizing or reducing them. Unrecognized props (`id`, `aria-*`, `data-*`, event handlers, …) are forwarded to the visible row.

Examples

Default

DesignEngineeringResearchOperationsSupport

<OverflowList
  {...args}
  overflowRenderer={overflowBadge}
  style={{maxWidth: 360}}>
  {labels.map(label => (
    <Badge key={label} label={label} />
  ))}
</OverflowList>

Collapse From Start

DesignEngineeringResearchOperationsSupport

<OverflowList
  {...args}
  overflowRenderer={overflowBadge}
  style={{maxWidth: 360}}>
  {labels.map(label => (
    <Badge key={label} label={label} />
  ))}
</OverflowList>

Keep Two Visible

DesignEngineeringResearchOperationsSupport

<OverflowList
  {...args}
  overflowRenderer={overflowBadge}
  style={{maxWidth: 360}}>
  {labels.map(label => (
    <Badge key={label} label={label} />
  ))}
</OverflowList>

Observe Parent

Teams:

DesignEngineeringResearchOperationsSupport

<div
  style={{
    alignItems: 'center',
    display: 'flex',
    gap: 12,
    maxWidth: 420,
  }}>
  <span style={{whiteSpace: 'nowrap'}}>Teams:</span>
  <OverflowList {...args} overflowRenderer={overflowBadge}>
    {labels.map(label => (
      <Badge key={label} label={label} />
    ))}
  </OverflowList>
</div>

API

OverflowList

Prop	Type	Default	Description
`behavior`	`'observeParent' \| 'observeSelf'`	`'observeSelf'`	Element whose width controls the fit calculation. `observeParent` uses the parent's content width and is useful when the list shares a flex row with other content.
`children`*	`ReactNode`	—	Items to measure and render.
`className`	`string`	—	Additional CSS class names applied to the visible row.
`collapseFrom`	`'end' \| 'start'`	`'end'`	Side of the list from which items are collapsed.
`data-testid`	`string`	—	Test ID applied to the visible row. The hidden measurement row uses the same value with a `-measure` suffix.
`gap`	`0 \| 0.5 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10`	`0`	Gap between visible items, on the spacing scale.
`minVisibleItems`	`number`	`0`	Minimum number of items kept visible even when they exceed the available width.
`overflowRenderer`	`(overflowItems: OverflowItem[]) => ReactNode`	—	Renders the collapsed items, typically as a `+N` indicator. The callback receives each item's original child and index.
`ref`	`Ref<HTMLDivElement>`	—	Ref forwarded to the visible row.
`style`	`CSSProperties`	—	Inline styles applied to the visible row.