Overflow List New Alpha Light DOM & Tailwind

Usage

Overflow List measures ordered direct children and hides the contiguous items that no longer fit. It preserves every original element, listener, value, and DOM position while exposing visible and overflowed element/index pairs through read-only state and nord-overflow-change.

Importing the component registers its custom element:

import "@nordhealth/components/lib/OverflowList"
import "@nordhealth/components/lib/OverflowListCount"
import "@nordhealth/components/lib/OverflowListMenu"

Composition

• Overflow List Count provides a localized declarative count affordance.
• Overflow List Menu provides equivalent actions for hidden interactive items.

Use the declarative nord-overflow-list-menu helper when hidden items are actions. It owns the Nord Dropdown affordance, mirrors the currently overflowed actions, and forwards activation to each original element without moving or cloning it. At its default width, the canonical example keeps Overview, Properties, and Edit visible while Duplicate and Share move into a +2 more menu.

State is available as immutable visibleItems and overflowItems arrays of { element, index } records. The read-only overflowCount is also reflected as data-overflow-count. nord-overflow-change bubbles and is composed, and fires only when an ordered classified set or original index changes. The Count and Menu helpers cover the common declarative integrations; a custom slot="overflow" affordance can synchronize equivalent content from the same event.

Examples

Collapse direction

The default collapse-from="end" keeps the earliest fitting items. collapse-from="start" keeps the latest fitting items. Classified arrays always remain in original order.

Because the light-DOM component never moves consumer content, place the overflow affordance at the matching logical edge in DOM order: last for end, first for start. This keeps visual and keyboard order aligned in LTR and RTL. The start-collapse example uses a five-step row: Step 1 and Step 2 move into +2 more, leaving Steps 3–5 visible.

Badge tags

When individual hidden tags are nonessential and a summary count is sufficient, nest nord-overflow-list-count compact inside a consumer-owned Nord Badge. The helper derives the live count from the nearest Overflow List, formats it for the active document language, and renders +N; without compact, it renders +N more. Set singular-label and plural-label so its accessible text describes the content, such as “1 more tag” or “2 more tags”. The resizable example uses Nord Badge variants for React, TypeScript, StyleX, Storybook, and Vitest.

Dropdown actions

Action rows need an equivalent interactive representation of every hidden action. Place nord-overflow-list-menu directly in the list with slot="overflow"; use compact for a +N toggle, or omit it for +N more. The resizable action example keeps Save, Edit, and Duplicate visible at its default width and moves Share, Archive, and Delete into a +3 Nord Dropdown. Menu activation forwards to the original action, preserving its listener and state.

Original click handlers

The built-in menu activates the original action with HTMLElement.click(), so direct and generated menu activation both run the listener attached to that original exactly once and its currentTarget remains the original element. The forwarded original click is programmatic, which means its isTrusted value is false.

If application behavior specifically requires a trusted event or cannot be represented by a forwarded click, provide a custom slot="overflow" affordance and synchronize it with nord-overflow-change instead. The resizable example lets you click Archive directly, resize until it moves into overflow, and choose Archive from the menu while a live output reports the handler count, current target, and trusted-event state.

Observation modes

observe="self" responds to the component’s actual assigned inline size. Use observe="parent" only when the containing element’s CSS content box is the relevant constraint. A Shadow DOM container can constrain slotted content internally—for example, with Card padding that is not visible on the host—so use the default self observation in that case. Both modes also respond to direct-child, content, item-size, affordance-size, font, and direction changes in one animation-frame batch.

Minimum visibility

Set min-visible-items to retain a required number of items. The minimum wins even if those items and the overflow affordance exceed the available inline size, so use it only for genuinely essential leading or trailing content.

Dynamic items

Items can be added, removed, reordered, or updated without recreating the component. Each change invalidates stale measurements and produces at most one classified-state event after the next stable layout.

Constrained containers

The gap defaults to Nord’s small spacing token. Choose none, xs, s, m, l, xl, or xxl, or set --n-overflow-list-gap when the surrounding product layout has a specific constraint.

State and events

• visibleItems and overflowItems are immutable arrays of { element, index } records.
• overflowCount is read-only and reflected as data-overflow-count, including 0.
• nord-overflow-change bubbles and is composed. It fires only when an ordered classified set or original index changes.
• nord-overflow-list-count handles locale-aware visible counts and accessible singular/plural labels for common count-only affordances.
• nord-overflow-list-menu handles the common action-menu case, including equivalent menu items and activation forwarding.
• For a custom slot="overflow" affordance, listen to nord-overflow-change as the custom integration escape hatch. Use its original element/index records to synchronize equivalent content, and supply translated labels through the product localization layer.

Accessibility

• Overflowed originals are both hidden and inert, so their controls cannot remain in the tab order or accessibility tree.
• Overflow List restores only attributes it added. Existing consumer hidden and inert state is preserved.
• Use nord-overflow-list-menu for a keyboard-accessible equivalent of hidden actions, or provide a custom affordance with the same semantics and behavior.
• The built-in menu keeps every generated action equivalent to its hidden original and forwards activation to that original, as shown in the Overview and Collapse from start examples.
• Keep the affordance at the logical collapse edge in DOM order. CSS-only visual reordering would create a different keyboard order and is intentionally avoided.
• Logical grid layout supports RTL, brand themes, high contrast, text resizing, and zoom without physical left/right assumptions.