Overflow
The Overflow engine automatically lays out items into up to N columns and adds an “and X more” label when content exceeds the available height. It also applies text clamping per-column width and handles grouped headers without leaving orphaned headings.
Basic Usage
You can enable Overflow on any container (e.g., a flex or grid column) by adding
data-overflow="true"
to the container.
<div class="flex flex--col gap" data-overflow="true">
<div class="item">
<div class="meta"></div>
<div class="content">
<span class="title title--small">Title goes here</span>
<span class="description">Description goes here</span>
</div>
</div>
<!-- more .item elements -->
</div>
Attribute | Default | Description |
---|---|---|
data-overflow
|
false |
Enable Overflow on any container (non-.columns ). Hides trailing items to fit the height budget. |
data-overflow-max-height
|
auto |
Override height budget. Pixel value (e.g., 320 ) or auto to inherit the parent’s content height. |
data-overflow-counter
|
false |
Show a trailing “and N more” label when items are hidden. |
data-overflow-max-cols
|
unset |
Best‑fit columns up to N on a .columns container. Optimizes for the most visible items. |
data-overflow-cols
|
unset |
Force exactly N columns on a .columns container. |
Smart Columns
Place .item
Item
elements inside a single .column
element, that's nested inside a .columns
Columns
container. Set the exact or maximum number of columns with data-overflow-cols
or data-overflow-max-cols
.
Number of columns
Set data-overflow-cols
to force an exact
column count. Use this when you want a consistent column count regardless of how many
items fit. The engine will still respect height constraints, but it will keep the
requested number of columns even if that shows fewer items than a best‑fit layout.
<div class="columns" data-overflow-cols="3">
<div class="column">
<!-- Items go here -->
</div>
</div>
Maximum number of columns
Set data-overflow-max-cols
to allow the
engine to choose the best number of columns up to the maximum you specify. This
best‑fit mode prioritizes the most visible items. For example, allowing 3 columns may
still render 2 columns if that shows more items due to less wrapping.
<div class="columns" data-overflow-max-cols="3">
<div class="column">
<!-- Items go here -->
</div>
</div>
Height Budget
Control how much vertical space Overflow can use by specifying data-overflow-max-height
. When not specified, the height budget defaults to the parent’s content height.
<div class="flex flex--col gap" data-overflow="true" data-overflow-max-height="220">
<!-- Items go here -->
</div>
Overflow Counter
Opt‑in to display a trailing “and N more” label by adding
data-overflow-counter="true"
The engine will reserve
space for the label during planning so it fits without pushing items out of bounds.
<div class="columns" data-overflow-max-cols="1" data-overflow-counter="true">
<div class="column">
<!-- Items go here -->
</div>
</div>
Clamp-aware Overflow
The Clamp engine
Clamp
re-clamps text for the actual column width. Apply data-clamp
on titles or descriptions as needed.
<div class="columns" data-overflow-max-cols="2">
<div class="column">
<!-- Items go here -->
</div>
</div>
Group Headers
Mark headers with group-header
. The engine avoids orphaned headers and duplicates a header at the start of the next column when a group spills over.
<div class="columns" data-overflow-max-cols="3">
<div class="column">
<span class="label label--medium group-header" data-group-header="true">Today</span>
<!-- Items go here -->
<span class="label label--medium group-header" data-group-header="true">Tomorrow</span>
<!-- Items go here -->
<span class="label label--medium group-header" data-group-header="true">This Week</span>
<!-- Items go here -->
</div>
</div>
- Headers are never left as the last visible element in a column.
- When a group spills, a gray duplicate header is added to the next column for context.
Harmonious Group Columns
When the number of group headers equals the maximum columns and there's enough space, the engine places each group in its own column for a more harmonious layout.
<div class="columns" data-overflow-max-cols="3">
<div class="column">
<span class="label label--medium group-header" data-group-header="true">Today</span>
<!-- Items go here -->
<span class="label label--medium group-header" data-group-header="true">Tomorrow</span>
<!-- Items go here -->
<span class="label label--medium group-header" data-group-header="true">This Week</span>
<!-- Items go here -->
</div>
</div>
Backwards compatibility
The Overflow engine
Overflow
remains compatible with legacy list attributes used in older plugins. When these
attributes are present on a descendant .column
or
.list
, the engine will promote them onto the
enclosing .columns
Columns
container at runtime.
Supported legacy attributes
data-list-limit="true"
: opts the list into Overflow. If the enclosing.columns
lacksdata-overflow-max-cols
, it will default to1
.data-list-max-columns
: sets the maximum column count. Responsive variants (e.g.,-sm
,-md
) on the legacy element are honored when present; the base value is used for the engine.data-list-max-height
: sets the height budget for the columns. Use a pixel value (e.g.,340
) orauto
to inherit from the parent container.data-list-hidden-count
: older toggle for the trailing label; still honored when present.
Legacy example (still works)
<div class="columns">
<div class="column"
data-list-limit="true"
data-list-max-height="340"
data-list-hidden-count="true"
data-list-max-columns="2">
<!-- Items go here -->
</div>
</div>
Notes
data-overflow-cols
(fixed count) takes precedence overdata-overflow-max-cols
(best‑fit up to N) when both are present.- When only
data-list-limit
is present, the engine defaults to 1 column. - By default, the trailing hidden count label is not shown. Enable with
data-overflow-counter="true"
. Legacydata-list-hidden-count
remains supported.