Data

Overflow List

List that adapts to available width by collapsing overflow into a "+N more" indicator.

Preview

'use client';

import { Badge } from '@brika/clay/components/badge';
import {
  OverflowList,
  OverflowListContent,
  OverflowListIndicator,
  OverflowListItem,
  useOverflowList,
} from '@brika/clay/components/overflow-list';
const TAGS = [
  'production',
  'staging',
  'eu-west-1',
  'us-east-1',
  'ap-southeast-2',
  'cdn',
  'edge',
  'preview',
];

/** Tags that overflow the container collapse into a "+N more" badge. Resize the window to see it adapt. */
export default function OverflowListDefaultDemo() {
  const { containerRef, visible, overflow } = useOverflowList({
    items: TAGS,
    getKey: (t) => t,
  });

  return (
    <OverflowList className="w-full max-w-sm">
      <OverflowListContent ref={containerRef}>
        {TAGS.map((tag) => (
          <OverflowListItem key={tag} itemId={tag}>
            <Badge variant={visible.includes(tag) ? 'outline' : 'secondary'}>{tag}</Badge>
          </OverflowListItem>
        ))}
      </OverflowListContent>
      <OverflowListIndicator active={overflow.length > 0}>
        <Badge>+{overflow.length} more</Badge>
      </OverflowListIndicator>
    </OverflowList>
  );
}

01 Installation

Install

Pull Overflow List from the barrel for everyday use, or the granular path when you want a tighter bundle.

tsxBarrel1 line

import { OverflowList } from "@brika/clay";

tsxGranular1 line

import { OverflowList } from "@brika/clay/components/overflow-list";

02 Usage

A minimal example

Drop this into a page. Native HTML attributes pass through to the underlying primitive.

tsxOverflow List.tsx43 lines

'use client';

import { Badge } from '@brika/clay/components/badge';
import {
  OverflowList,
  OverflowListContent,
  OverflowListIndicator,
  OverflowListItem,
  useOverflowList,
} from '@brika/clay/components/overflow-list';
const TAGS = [
  'production',
  'staging',
  'eu-west-1',
  'us-east-1',
  'ap-southeast-2',
  'cdn',
  'edge',
  'preview',
];

/** Tags that overflow the container collapse into a "+N more" badge. Resize the window to see it adapt. */
export default function OverflowListDefaultDemo() {
  const { containerRef, visible, overflow } = useOverflowList({
    items: TAGS,
    getKey: (t) => t,
  });

  return (
    <OverflowList className="w-full max-w-sm">
      <OverflowListContent ref={containerRef}>
        {TAGS.map((tag) => (
          <OverflowListItem key={tag} itemId={tag}>
            <Badge variant={visible.includes(tag) ? 'outline' : 'secondary'}>{tag}</Badge>
          </OverflowListItem>
        ))}
      </OverflowListContent>
      <OverflowListIndicator active={overflow.length > 0}>
        <Badge>+{overflow.length} more</Badge>
      </OverflowListIndicator>
    </OverflowList>
  );
}

03 Examples

Overflow List, every way

Active

The active item is always kept visible even when it would otherwise be hidden.

GitHub

'use client';

import { Badge } from '@brika/clay/components/badge';
import {
  OverflowList,
  OverflowListContent,
  OverflowListIndicator,
  OverflowListItem,
  useOverflowList,
} from '@brika/clay/components/overflow-list';
const ENVIRONMENTS = [
  { id: 'production', label: 'production' },
  { id: 'staging', label: 'staging' },
  { id: 'preview-1', label: 'preview-1' },
  { id: 'preview-2', label: 'preview-2' },
  { id: 'review-app', label: 'review-app' },
  { id: 'nightly', label: 'nightly' },
  { id: 'canary', label: 'canary' },
];

/** The active item is always kept visible even when it would otherwise be hidden. */
export default function OverflowListActiveDemo() {
  const { containerRef, visible, overflow } = useOverflowList({
    items: ENVIRONMENTS,
    getKey: (e) => e.id,
    activeKey: 'nightly',
  });

  return (
    <OverflowList className="w-full max-w-xs">
      <OverflowListContent ref={containerRef}>
        {ENVIRONMENTS.map((env) => (
          <OverflowListItem key={env.id} itemId={env.id}>
            <Badge
              variant={env.id === 'nightly' ? 'default' : 'outline'}
              className={visible.some((v) => v.id === env.id) ? '' : 'invisible'}
            >
              {env.label}
            </Badge>
          </OverflowListItem>
        ))}
      </OverflowListContent>
      <OverflowListIndicator active={overflow.length > 0}>
        <Badge variant="secondary">+{overflow.length}</Badge>
      </OverflowListIndicator>
    </OverflowList>
  );
}

04 Accessibility

Accessibility

Hidden items remain in the DOM, the indicator communicates the count to all users.
The activeKey item is always visible; this preserves context for the current selection.
Consider wrapping the indicator in a Popover or Tooltip to reveal hidden items on demand.

05 API reference

API reference

Props specific to Overflow List. Native HTML attributes pass through to the underlying primitive, see the component source on GitHub for the full type signature.

<OverflowList />

passthrough

No wrapper-specific props, all attributes pass through to the underlying primitive.

<OverflowListContent />

passthrough

No wrapper-specific props, all attributes pass through to the underlying primitive.

<OverflowListIndicator />

1 prop

activedefault false
boolean
Whether to render in the active overflow state.

<OverflowListItem />

1 prop

itemId*
string
Stable identifier matching one of the items passed to useOverflowList.