The items are the element children of the list, in document order. Items that do not fit are replaced by one count, +3 by default, which assistive technology reads as “3 more”. The list adds no role or focus behavior to its items, so interactive items keep their own semantics. Omitted items stay in the document but are not shown, focusable or announced.
The items are the element children of the list, in document order, except elements with the hidden attribute and the element in the count slot. Adding, removing, moving or hiding a child updates the list in place. Text directly inside the list is not shown; wrap it in an element.
A focused item that becomes omitted loses focus, as any content that becomes inert does. When the items form a list, give the list role="list" and each item role="listitem".
Item limit
limit shows at most that many items. Use it when the number of items matters more than the space they take, such as the first few assignees on a card.
Item limit
Default density
Compact density
Restart from the initial state
Show the copyable source
max-rows fits as many items as the available width allows within that many wrapped rows, with the count beside them. The list refits when its container resizes, and never changes height until its fitted rows do, so the content below stays in place. Drag the handle to see it refit.
Row limit
Default density
Compact density
Restart from the initial state
Show the copyable source
limit and max-rows combine: the fit never shows more than limit items. Items should keep their own width, since an item that grows to fill its row can’t be measured.
An item wider than a row takes a row of its own. With nothing to omit, every item shows and no count renders; when not even one item fits beside the count, the count shows alone.
A list with max-rows takes its width from its container and refits when the container resizes, an item or the count changes size, fonts load, items change, or limit, max-rows or collapse-from change. Many lists that refit together share one layout pass. A list that is not rendered, for example inside a closed panel, waits until it renders before it fits or emits tp-overflow-change.
Items should keep their own width: an item that grows to fill its row (flex-grow) or that generates no box (display: contents) cannot be measured as one item and emits a tp-diagnostic.
In a table
In a table cell, flex row or grid track, the list asks for the width of its items on one row and can shrink down to the count, so the column sizes as if nothing were omitted. In a flex row, give the list room to grow, for example with flex: 1.
In a table
Default density
Compact density
Restart from the initial state
Show the copyable source
An element in the count slot replaces the default count while items are omitted. It gets no generated content: listen for tp-overflow-change and read hiddenCount and hiddenItems to fill it. Here the count is a Button that opens a Popover with the omitted labels. The count needs a box of its own, so the Popover is wrapped in a span, and it must state the number of omitted items in its text or accessible name.
Only the first element in the count slot is used; further ones are not shown and emit a tp-diagnostic. Leave the items in the list: moving them out changes the list and triggers a refit. Use Badge for tags and labels, and Button with Popover, Menu or Dialog in the count slot when the omitted items should be reachable.
Custom count
Default density
Compact density
Restart from the initial state
Show the copyable source
To change only the text of the default count, set messages with count (visible, +N) and countLabel (accessible, N more); each is text or a function of the omitted and total counts.
The default count is a secondary Badge. It shows +N with tabular figures, and assistive technology hears “N more” instead.
AttributePropertyTypeDefaultDescriptionlimitlimitnumber | nullnullMost Items shown; a value below one means no limit.max-rowsmaxRowsnumber | nullnullMost rows of the available inline size; Items that do not fit are omitted.collapse-fromcollapseFromOverflowCollapseFrom'end'Side whose Items are omitted; the Count takes their place.
Properties
PropertyTypeDefaultDescriptionmessagesOverflowListMessages{}Replaceable Count texts: count (visible, +N) and countLabel (accessible, N more).hiddenCountread-onlynumber—The number of omitted Items.hiddenItemsread-onlyElement[]—The omitted Items, in document order.
Events
EventTypeDescriptiontp-overflow-changeTpValueChangeEvent<number>The omitted Items changed (not cancelable); detail.value is the omitted count, detail.reason is initial or layout.
Methods
MethodReturnsDescriptionadoptShown(shown)voidFit controller: presents shown Items.probeCounts(hidden)booleanFit controller: lays out default Counts for these omitted counts so they can be measured.partitionSettled()voidFit controller: the presented partition fits.itemDiagnostic(kind)voidFit controller: an Item that the fit cannot measure as intended.
Slots
SlotDescriptiondefaultItems: element children that are not hidden.countA Consumer element that replaces the default Count while Items are omitted.
CSS parts
PartDescription::part(overflow-list)The wrapping row of the shown items and the count.::part(overflow-list-count)The default count, a Badge of the omitted items.
Related
Components, widgets and patterns that use this one.