Skip to content

Early previewhamur is not on npm yet. The components are being built in the open, follow along on GitHub.

LayoutReact

Overflow List

A row that shows as many of its items as fit on one line and hides the rest behind a trigger.

Rendered by React 19.3.1

import * as React from 'react'
import { Menu } from '@hamur/react/menu'
import { OverflowList } from '@hamur/react/overflow-list'

const teams = [
  'Design',
  'Engineering',
  'Marketing',
  'Sales',
  'Support',
  'Legal',
  'Finance',
  'People',
]

export default function OverflowListExample() {
  const [hidden, setHidden] = React.useState<string[]>([])

  function changed(items: OverflowList.Root.HiddenItem[]) {
    setHidden(items.map((item) => item.value ?? ''))
  }

  return (
    <div className="stack">
      <div className="overflow-list-frame">
        <OverflowList.Root
          className="overflow-list"
          labels={{ indicator: '{count} more items' }}
          onHiddenItemsChange={changed}
        >
          {teams.map((team) => (
            <OverflowList.Item
              key={team}
              value={team}
              className="overflow-list-chip"
            >
              {team}
            </OverflowList.Item>
          ))}
          <OverflowList.Indicator className="overflow-list-indicator">
            {(state) => (
              <Menu.Root>
                <Menu.Trigger className="button" aria-label={state.label}>
                  {state.hiddenCount} more
                </Menu.Trigger>
                <Menu.Portal>
                  <Menu.Positioner sideOffset={6}>
                    <Menu.Popup className="menu">
                      <OverflowList.HiddenItems>
                        {(entry) => (
                          <Menu.Item key={entry.index} className="menu-item">
                            {entry.value}
                          </Menu.Item>
                        )}
                      </OverflowList.HiddenItems>
                    </Menu.Popup>
                  </Menu.Positioner>
                </Menu.Portal>
              </Menu.Root>
            )}
          </OverflowList.Indicator>
        </OverflowList.Root>
      </div>
      <p className="muted">{hidden.length ? `Hidden: ${hidden.join(', ')}` : 'Nothing hidden'}</p>
    </div>
  )
}
Not measured yetTests passing in React
10.9 KiBSize
Not measured yetMemory
Not measured yetSpeed
[N] commits

Installation

npm i @hamur/react

Not on npm yet. The package goes out under the chosen name.

Anatomy

Import the component and assemble its parts:

<OverflowList.Root>
  <OverflowList.Item />
  <OverflowList.Indicator>
    <OverflowList.HiddenItems />
  </OverflowList.Indicator>
</OverflowList.Root>

Examples

Start

A breadcrumb with collapseFrom="start": the first and last crumbs are pinned and the ellipsis after the first opens a Menu of the rest.

OverflowListStart.tsx
import { Menu } from '@hamur/react/menu'
import { OverflowList } from '@hamur/react/overflow-list'

const trail = ['Home', 'Docs', 'Components', 'Navigation', 'Overflow List', 'Examples']

function Crumb({ name, pinned }: { name: string; pinned?: boolean }) {
  return (
    <OverflowList.Item
      value={name}
      pinned={pinned}
      className="overflow-list-crumb"
    >
      <a className="breadcrumb-link" href={`#${name}`}>
        {name}
      </a>
    </OverflowList.Item>
  )
}

export default function OverflowListStartExample() {
  return (
    <div className="stack">
      <div className="overflow-list-frame">
        <nav aria-label="Breadcrumb">
          <OverflowList.Root className="overflow-list" collapseFrom="start">
            <Crumb name={trail[0]} pinned />
            <OverflowList.Indicator className="overflow-list-crumb">
              {(state) => (
                <Menu.Root>
                  <Menu.Trigger className="breadcrumb-ellipsis-trigger" aria-label={state.label}>
                    …
                  </Menu.Trigger>
                  <Menu.Portal>
                    <Menu.Positioner sideOffset={6}>
                      <Menu.Popup className="menu">
                        <OverflowList.HiddenItems>
                          {(entry) => (
                            <Menu.Item key={entry.index} className="menu-item">
                              {entry.value}
                            </Menu.Item>
                          )}
                        </OverflowList.HiddenItems>
                      </Menu.Popup>
                    </Menu.Positioner>
                  </Menu.Portal>
                </Menu.Root>
              )}
            </OverflowList.Indicator>
            {trail.slice(1, -1).map((name) => (
              <Crumb key={name} name={name} />
            ))}
            <Crumb name={trail[trail.length - 1]} pinned />
          </OverflowList.Root>
        </nav>
      </div>
      <p className="muted">The first and last crumbs stay; the rest hide from the start.</p>
    </div>
  )
}

Priority

Seven mail folders with priority 3 to 0: the lowest hide first, and Inbox is the last to go.

OverflowListPriority.tsx
import * as React from 'react'
import { Menu } from '@hamur/react/menu'
import { OverflowList } from '@hamur/react/overflow-list'

const folders = [
  { name: 'Inbox', priority: 3 },
  { name: 'Starred', priority: 2 },
  { name: 'Sent', priority: 1 },
  { name: 'Drafts', priority: 1 },
  { name: 'Archive', priority: 0 },
  { name: 'Spam', priority: 0 },
  { name: 'Trash', priority: 0 },
]

export default function OverflowListPriorityExample() {
  const [hidden, setHidden] = React.useState<string[]>([])

  function changed(items: OverflowList.Root.HiddenItem[]) {
    setHidden(items.map((item) => item.value ?? ''))
  }

  return (
    <div className="stack">
      <div className="overflow-list-frame">
        <OverflowList.Root
          className="overflow-list"
          labels={{ indicator: '{count} more items' }}
          onHiddenItemsChange={changed}
        >
          {folders.map((folder) => (
            <OverflowList.Item
              key={folder.name}
              value={folder.name}
              priority={folder.priority}
              className="overflow-list-chip"
            >
              {folder.name}
            </OverflowList.Item>
          ))}
          <OverflowList.Indicator className="overflow-list-indicator">
            {(state) => (
              <Menu.Root>
                <Menu.Trigger className="button" aria-label={state.label}>
                  {state.hiddenCount} more
                </Menu.Trigger>
                <Menu.Portal>
                  <Menu.Positioner sideOffset={6}>
                    <Menu.Popup className="menu">
                      <OverflowList.HiddenItems>
                        {(entry) => (
                          <Menu.Item key={entry.index} className="menu-item">
                            {entry.value}
                          </Menu.Item>
                        )}
                      </OverflowList.HiddenItems>
                    </Menu.Popup>
                  </Menu.Positioner>
                </Menu.Portal>
              </Menu.Root>
            )}
          </OverflowList.Indicator>
        </OverflowList.Root>
      </div>
      <p className="muted">
        {hidden.length ? `Hidden: ${hidden.join(', ')}` : 'Nothing hidden'}. Lower priorities hide
        first.
      </p>
    </div>
  )
}

Max

maxVisibleItems held by the app: Show fewer and Show more change the cap while the row stays wide.

OverflowListMax.tsx
import * as React from 'react'
import { Menu } from '@hamur/react/menu'
import { OverflowList } from '@hamur/react/overflow-list'

const photos = ['Beach', 'Forest', 'Harbor', 'Market', 'Station', 'Summit', 'Bridge']

export default function OverflowListMaxExample() {
  const [max, setMax] = React.useState(3)

  return (
    <div className="stack">
      <div className="overflow-list-frame overflow-list-wide">
        <OverflowList.Root
          className="overflow-list"
          labels={{ indicator: '{count} more items' }}
          maxVisibleItems={max}
        >
          {photos.map((photo) => (
            <OverflowList.Item
              key={photo}
              value={photo}
              className="overflow-list-chip"
            >
              {photo}
            </OverflowList.Item>
          ))}
          <OverflowList.Indicator className="overflow-list-indicator">
            {(state) => (
              <Menu.Root>
                <Menu.Trigger className="button" aria-label={state.label}>
                  {state.hiddenCount} more
                </Menu.Trigger>
                <Menu.Portal>
                  <Menu.Positioner sideOffset={6}>
                    <Menu.Popup className="menu">
                      <OverflowList.HiddenItems>
                        {(entry) => (
                          <Menu.Item key={entry.index} className="menu-item">
                            {entry.value}
                          </Menu.Item>
                        )}
                      </OverflowList.HiddenItems>
                    </Menu.Popup>
                  </Menu.Positioner>
                </Menu.Portal>
              </Menu.Root>
            )}
          </OverflowList.Indicator>
        </OverflowList.Root>
      </div>
      <div className="overflow-list-controls">
        <button
          type="button"
          className="button"
          disabled={max <= 1}
          onClick={() => setMax((current) => current - 1)}
        >
          Show fewer
        </button>
        <button
          type="button"
          className="button"
          disabled={max >= photos.length}
          onClick={() => setMax((current) => current + 1)}
        >
          Show more
        </button>
      </div>
      <p className="muted">Showing at most {max} of 7 photos.</p>
    </div>
  )
}

Toolbar

A formatting Toolbar that is the Overflow List Root; each Item is a Toolbar Button and the trigger is one more roving stop.

OverflowListToolbar.tsx
import * as React from 'react'
import { Menu } from '@hamur/react/menu'
import { OverflowList } from '@hamur/react/overflow-list'
import { Toolbar } from '@hamur/react/toolbar'

const actions = ['Bold', 'Italic', 'Underline', 'Strike', 'Code', 'Link', 'Quote']

export default function OverflowListToolbarExample() {
  const [last, setLast] = React.useState('nothing yet')

  return (
    <div className="stack">
      <div className="overflow-list-frame">
        <Toolbar.Root
          className="toolbar overflow-list-toolbar"
          aria-label="Formatting"
          render={
            <OverflowList.Root labels={{ indicator: '{count} more items' }} />
          }
        >
          {actions.map((action) => (
            <OverflowList.Item
              key={action}
              value={action}
              className="toolbar-button"
              render={<Toolbar.Button onClick={() => setLast(action)} />}
            >
              {action}
            </OverflowList.Item>
          ))}
          <OverflowList.Indicator className="overflow-list-indicator">
            {(state) => (
              <Menu.Root>
                <Toolbar.Button
                  className="toolbar-button"
                  aria-label={state.label}
                  render={<Menu.Trigger />}
                >
                  {state.hiddenCount} more
                </Toolbar.Button>
                <Menu.Portal>
                  <Menu.Positioner sideOffset={6}>
                    <Menu.Popup className="menu">
                      <OverflowList.HiddenItems>
                        {(entry) => (
                          <Menu.Item
                            key={entry.index}
                            className="menu-item"
                            onClick={() => setLast(entry.value ?? '')}
                          >
                            {entry.value}
                          </Menu.Item>
                        )}
                      </OverflowList.HiddenItems>
                    </Menu.Popup>
                  </Menu.Positioner>
                </Menu.Portal>
              </Menu.Root>
            )}
          </OverflowList.Indicator>
        </Toolbar.Root>
      </div>
      <p className="muted">Last pressed: {last}</p>
    </div>
  )
}

API reference

13 props across 4 parts, in React syntax. className, style, render are listed once, under Shared props.

HiddenItemsOverflowList.HiddenItems

Calls its function child once per hidden Item, in DOM order, with { value, index }. Placed inside the app's popup. Doesn’t render its own element.

HiddenItems props
PropTypeDefault
childrenrequiredRenders one hidden Item: { value, index }, index being its place among all Items.(entry: OverflowListHiddenItem) => React.ReactNode—

IndicatorOverflowList.Indicator

Holds the app's trigger for the hidden Items, placed where the trigger belongs. Hidden while no Item is hidden, unless alwaysVisible. Renders a <div>.

Indicator props
PropTypeDefault
alwaysVisibleWhether the Indicator shows while no Item is hidden.booleanfalse
childrenThe trigger, or a function of the Indicator's state that returns it.React.ReactNode | ((state: OverflowListIndicatorState) => React.ReactNode)—
Indicator data attributes
Data attributeDescription
data-hidden-countThe number of hidden Items.

ItemOverflowList.Item

One Item of the row. Hidden with the hidden attribute while it does not fit. Renders a <div>.

Item props
PropTypeDefault
valueThe Item's value, given to OverflowList.HiddenItems while it is hidden.string—
pinnedWhether the Item is never hidden.booleanfalse
priorityThe Item's priority: lower values hide first.number0
Item data attributes
Data attributeDescription
data-pinnedPresent when the Item is pinned: it is never hidden.

RootOverflowList.Root

Groups a row that shows as many of its Items as fit on one line and hides the rest behind an Indicator holding the app's trigger. Writes no role: give it another component's root through render (Toolbar.Root, Tabs.List, Breadcrumb.List) or a list element. Renders a <div>.

Root props
PropTypeDefault
orientationThe axis the Items are measured on.OverflowListOrientation'horizontal'
collapseFromThe side whose Items hide first, among Items of equal priority.OverflowListCollapseFrom'end'
maxVisibleItemsThe most Items shown, pinned ones included.number—
onHiddenItemsChangeCalled when the set of hidden Items changes, with the hidden Items in DOM order.((hiddenItems: OverflowListHiddenItem[], eventDetails: OverflowListChangeEventDetails) => void)—
labelsThe trigger's name, given to the Indicator's state as label; {count} is replaced by thePartial<OverflowListLabels>—
actionsRefA ref to imperative actions: measure() measures again.React.Ref<OverflowListActions>—
renderBeforeHydrationWhether to fit the server-rendered row with an inline script before React hydrates.booleanfalse
Root data attributes
Data attributeDescription
data-overflowingPresent while an Item is hidden.
data-orientationThe axis the Items are measured on.

Shared props

Every part that renders an element takes these.

Shared props
PropType
classNameCSS class applied to the element, or a function that returns a class based on the component's state.string | ((state: State) => string | undefined)
styleStyle applied to the element, or a function that returns a style object based on the component's state.React.CSSProperties | ((state: State) => React.CSSProperties | undefined)
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component.React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State>

Keyboard and accessibility

Keyboard

Keyboard
KeysDoesPart
ArrowRightArrowLeftIn a Toolbar, reaches the trigger as one more roving stop and comes backRoot
TabIn a Toolbar, still reaches the toolbar after the item holding the tab stop hidesRoot

Accessibility

What the parts set
PartSetsSo that
Rootno role and no ARIA; data-overflowing while an Item is hiddenthe row takes the role of the component it is, such as a toolbar, a tab list or a list
Itemthe hidden attribute while it does not fit, data-pinned when pinneda hidden Item is out of the accessibility tree and the tab order, and no screen reader reads it
Indicatorhidden while no Item is hidden, data-hidden-count; its state has a labelthe trigger is named, "More items" or the app's own text with {count} in it
HiddenItemsrenders nothing itself; calls its child once per hidden Itemthe popup lists what is hidden, in the same order as the row

Focus order

  1. The row's visible Items keep the tab order of the component they are (a Toolbar has one tab stop, a list of links has one each).
  2. The Indicator's trigger comes where the app put it in the DOM, after the Items unless the app places it elsewhere.
  3. In a Toolbar the tab stop moves off an Item that hides, so Tab still reaches the toolbar.
  4. The menu's items are reached once the menu is open, as a Menu's are.