OverflowList·component·@astryxdesign/core

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.

Open in Playground @astryxdesign/core/OverflowList

Showcases and examples

7 documented examples

Overflow List

A list of buttons that collapses overflowing items into a +N indicator.

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · overflow-list-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {OverflowList} from '@astryxdesign/core/OverflowList';
import {Button} from '@astryxdesign/core/Button';

export default function OverflowListShowcase() {
  return (
    <div style={{maxWidth: 400, border: '1px dashed #ccc', padding: 8}}>
      <OverflowList
        gap={2}
        overflowRenderer={overflowItems => (
          <Button
            label={`+${overflowItems.length} more`}
            variant="ghost"
            size="sm"
          />
        )}>
        <Button label="Edit" size="sm" />
        <Button label="Duplicate" size="sm" />
        <Button label="Share" size="sm" />
        <Button label="Archive" size="sm" />
        <Button label="Delete" size="sm" />
      </OverflowList>
    </div>
  );
}

Usage

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

Typed props

Prop	Type and behavior
`children`	`ReactNode` · required 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` · default 2 Gap between items as a spacing token step (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10).
`minVisibleItems`	`number` · default 0 Minimum number of items to always show, even when overflowing.
`maxVisibleItems`	`number` · default 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` · default 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'` · default 'end' Which end to collapse items from when overflow occurs.
`behavior`	`'observeSelf' \| 'observeParent'` · default '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.

Anatomy

List · required

Visible horizontal list container for the currently shown content.

Items · required

Caller-supplied items selected for visible display by the current width and count limits.

Overflow indicator · optional

Optional caller-rendered indicator for items collapsed by width or count limits.

Theming

Targets

astryx-overflow-list