XDS — Design System

OverflowList@xds/core · XDSOverflowList v0.0.13

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.

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

Best practices

Guidance	Practices
Do	Provide a meaningful overflowRenderer — a "+N more" badge, a dropdown, or a count indicator.
Do	Set minVisibleItems to keep key items visible regardless of container size.
Don't	Use OverflowList for vertical layouts — it only works with horizontal rows.

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>
  );
}

Usage

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

Best practices

Guidance	Practices
Do	Provide a meaningful overflowRenderer — a "+N more" badge, a dropdown, or a count indicator.
Do	Set minVisibleItems to keep key items visible regardless of container size.
Don't	Use OverflowList for vertical layouts — it only works with horizontal rows.

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> ); }

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> ); }

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> ); }

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> ); }