XDSOverflowList@xds/core · OverflowList
Preview coming soon

Usage

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.

Best practices

GuidancePractices
DoProvide a meaningful overflowRenderer — a "+N more" badge, a dropdown, or a count indicator.
DoSet minVisibleItems to keep key items visible regardless of container size.
Don'tUse OverflowList for vertical layouts — it only works with horizontal rows.

Import

ts
import {XDSOverflowList} from '@xds/core/OverflowList'

Props

PropTypeDescription
childrenrequired
ReactNodeItems to render. Each child should be a single element.
overflowRenderer
(overflowItems: XDSOverflowItem[]) => ReactNodeRender function for the overflow indicator. Receives the list of hidden items (each with child and index). Only called when items are overflowing.
gap
SpacingStep (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.
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
StyleXStylesStyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object.

Examples

Common configurations, variations, and states.
OverflowList — Badge TagsResizable row of badges that collapses into a count badge on overflow
tsx
'use client';
​
import * as stylex from '@stylexjs/stylex';
import {XDSOverflowList} from '@xds/core/OverflowList';
import {XDSBadge} from '@xds/core/Badge';
import {XDSCard} from '@xds/core/Card';
​
const styles = stylex.create({
  resizable: {
    resize: 'horizontal',
    overflow: 'hidden',
    minWidth: 80,
    width: 300,
  },
});
​
export default function OverflowListOverflowBadges() {
  return (
    <XDSCard padding={2} xstyle={styles.resizable}>
      <XDSOverflowList
        gap={1}
        overflowRenderer={overflowItems => (
          <XDSBadge variant="neutral" label={`+${overflowItems.length}`} />
        )}>
        <XDSBadge variant="info" label="React" />
        <XDSBadge variant="success" label="TypeScript" />
        <XDSBadge variant="warning" label="StyleX" />
        <XDSBadge variant="neutral" label="Storybook" />
        <XDSBadge variant="error" label="Vitest" />
      </XDSOverflowList>
    </XDSCard>
  );
}
OverflowList — Collapse From StartOverflow list that hides items from the start, keeping the latest visible
tsx
'use client';
​
import {XDSOverflowList} from '@xds/core/OverflowList';
import {XDSButton} from '@xds/core/Button';
import {XDSCard} from '@xds/core/Card';
import {XDSCenter} from '@xds/core/Center';
​
export default function OverflowListCollapseFromStartList() {
  return (
    <XDSCenter width={300}>
      <XDSCard padding={2}>
        <XDSOverflowList
          gap={2}
          collapseFrom="start"
          overflowRenderer={overflowItems => (
            <XDSButton
              label={`+${overflowItems.length} more`}
              variant="ghost"
              size="sm"
            />
          )}>
          <XDSButton label="Step 1" size="sm" />
          <XDSButton label="Step 2" size="sm" />
          <XDSButton label="Step 3" size="sm" />
          <XDSButton label="Step 4" size="sm" />
          <XDSButton label="Step 5" size="sm" />
        </XDSOverflowList>
      </XDSCard>
    </XDSCenter>
  );
}
OverflowList — Dropdown ActionsAction toolbar that collapses overflow buttons into a dropdown menu
tsx
'use client';
​
import * as stylex from '@stylexjs/stylex';
import {XDSOverflowList} from '@xds/core/OverflowList';
import {XDSButton} from '@xds/core/Button';
import {XDSDropdownMenu} from '@xds/core/DropdownMenu';
import {XDSCard} from '@xds/core/Card';
​
const actions = ['Save', 'Edit', 'Duplicate', 'Share', 'Archive', 'Delete'];
​
const styles = stylex.create({
  resizable: {
    resize: 'horizontal',
    overflow: 'hidden',
    minWidth: 100,
    width: 350,
    maxWidth: '100%',
  },
});
​
export default function OverflowListOverflowDropdownActions() {
  return (
    <XDSCard padding={2} xstyle={styles.resizable}>
      <XDSOverflowList
        gap={2}
        overflowRenderer={overflowItems => (
          <XDSDropdownMenu
            button={{
              label: `+${overflowItems.length}`,
              variant: 'ghost',
              size: 'sm',
            }}
            items={overflowItems.map(({index}) => ({
              label: actions[index],
              onClick: () => {},
            }))}
          />
        )}>
        <XDSButton label="Save" size="sm" variant="primary" />
        <XDSButton label="Edit" size="sm" />
        <XDSButton label="Duplicate" size="sm" />
        <XDSButton label="Share" size="sm" />
        <XDSButton label="Archive" size="sm" />
        <XDSButton label="Delete" size="sm" variant="destructive" />
      </XDSOverflowList>
    </XDSCard>
  );
}

Showcase source

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