LayoutReact
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
Installation
npm i @hamur/reactNot 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.
Priority
Seven mail folders with priority 3 to 0: the lowest hide first, and Inbox is the last to go.
Max
maxVisibleItems held by the app: Show fewer and Show more change the cap while the row stays wide.
Toolbar
A formatting Toolbar that is the Overflow List Root; each Item is a Toolbar Button and the trigger is one more roving stop.
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.
| Prop | Type | Default |
|---|---|---|
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>.
| Prop | Type | Default |
|---|---|---|
alwaysVisibleWhether the Indicator shows while no Item is hidden. | boolean | false |
childrenThe trigger, or a function of the Indicator's state that returns it. | React.ReactNode | ((state: OverflowListIndicatorState) => React.ReactNode) | — |
| Data attribute | Description |
|---|---|
data-hidden-count | The number of hidden Items. |
ItemOverflowList.Item
One Item of the row. Hidden with the hidden attribute while it does not fit. Renders a <div>.
| Prop | Type | Default |
|---|---|---|
valueThe Item's value, given to OverflowList.HiddenItems while it is hidden. | string | — |
pinnedWhether the Item is never hidden. | boolean | false |
priorityThe Item's priority: lower values hide first. | number | 0 |
| Data attribute | Description |
|---|---|
data-pinned | Present 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>.
| Prop | Type | Default |
|---|---|---|
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 the | Partial<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. | boolean | false |
| Data attribute | Description |
|---|---|
data-overflowing | Present while an Item is hidden. |
data-orientation | The axis the Items are measured on. |
Shared props
Every part that renders an element takes these.
| Prop | Type |
|---|---|
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
| Keys | Does | Part |
|---|---|---|
| ArrowRightArrowLeft | In a Toolbar, reaches the trigger as one more roving stop and comes back | Root |
| Tab | In a Toolbar, still reaches the toolbar after the item holding the tab stop hides | Root |
Accessibility
| Part | Sets | So that |
|---|---|---|
| Root | no role and no ARIA; data-overflowing while an Item is hidden | the row takes the role of the component it is, such as a toolbar, a tab list or a list |
| Item | the hidden attribute while it does not fit, data-pinned when pinned | a hidden Item is out of the accessibility tree and the tab order, and no screen reader reads it |
| Indicator | hidden while no Item is hidden, data-hidden-count; its state has a label | the trigger is named, "More items" or the app's own text with {count} in it |
| HiddenItems | renders nothing itself; calls its child once per hidden Item | the popup lists what is hidden, in the same order as the row |
Focus order
- 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). - The
Indicator's trigger comes where the app put it in the DOM, after theItems unless the app places it elsewhere. - In a Toolbar the tab stop moves off an
Itemthat hides, soTabstill reaches the toolbar. - The menu's items are reached once the menu is open, as a Menu's are.