Grid
A 24-column grid layout system. Pair it with oas-grid-item to divide column widths, with support for gap, offset and a custom total column count; setting columns switches to an auto equal-width layout (simple-grid).
Basic grid
Three equal columns
Unequal columns
Unequal columns
Offset
Offset
Custom total columns
Custom cols
Auto columns (simple-grid)
Setting columns divides the width equally with repeat(n, 1fr); child span is ignored (span only takes effect without columns), and it coexists with the 24-column grid without conflict.
columns auto equal-width
columns ignores span
Responsive column counts
columns accepts breakpoint shorthand: a base value plus space-separated breakpoint:value pairs (same protocol as span: sm=640 / md=768 / lg=1024 / xl=1280, mobile-first). Children stay auto equal-width and ignore span. Resize the window to see the count adapt.
columns breakpoints: 1 → sm:2 → md:3
<640px 1 column per row; ≥640px 2; ≥768px 3.
Min child width (auto-fit grid)
min-child-width sets the minimum width of each child (e.g. 180px; bare numbers are treated as px). The grid derives its column count automatically from the available width via auto-fit + minmax — children reflow without any breakpoints. When combined with columns, columns wins (min-child-width is ignored); in this mode child span / offset are also disabled (auto placement).
min-child-width auto-fit grid
Narrow or widen the container to see the column count change automatically — no breakpoints needed.
Large gap
Gap
Separated row/column gutters
gap supports a two-value syntax: space- or comma-separated row column (8 16 / 8,16) controls row-gap and column-gap independently; a single value still applies to both axes (zero regression). The row-gap / column-gap attributes can be set individually and override the matching axis of gap.
gap two values: row 8 / column 24
gap comma pair + row-gap/column-gap attributes
Responsive breakpoints
span / offset accept breakpoint shorthand: a base value plus space-separated breakpoint:value pairs (breakpoints sm=640 / md=768 / lg=1024 / xl=1280, mobile-first). Resize the window to see the columns adapt.
span breakpoints: 24 → md:12 → lg:8
<640px each item fills a row; ≥768px two per row; ≥1024px three equal columns.
offset breakpoints: 0 → md:4
From ≥768px the right item starts at column 5 and spans 4 columns (offset 4 / span 4).
Auto-width columns
span="auto" sizes an item to its natural content width (no column span); it can be combined with offset.
span=auto columns
Container alignment
justify controls the inline axis (justify-items), align the block axis (align-items); valid values are applied directly, invalid values fall back to stretch with a dev warning.
justify (inline axis)
align (block axis, fixed height)
Reordering (order / push / pull)
orderexpresses reordering: the DOM/source order (and screen-reader semantics) stays unchanged, only the visual order changes.push/pullshift the start line right / left by N columns on top ofoffset(net shift = push − pull combined with offset); a net shift ≤ 0 falls back to auto-placement.
Last column first (order)
push/pull shift
Custom order
Visual order: D (0) → B (1) → C (2) → A (3).
Collapsed rows (collapsed-rows)
collapsed-rows sets how many rows stay visible in the collapsed state (row model accumulates child span/offset): children beyond the limit are hidden and an Expand tail cell appears (spanning the remaining columns of its row); clicking expands, and the tail turns into Collapse to fold back. The collapsed state writes back to the controlled collapsed attribute and emits oas-collapse. Not enabled under columns / min-child-width auto layout (the row model relies on span/offset semantics); the row model counts in 24 columns, so with a non-24 cols the row estimate deviates from the real layout (push/pull are not counted either) — avoid that combination. When the total row count does not exceed collapsed-rows, collapsed is never written (nothing to fold: everything stays visible with no tail cell).
collapsed-rows=1 query filters
Only the first row shows by default (filters 1–3); click the Expand tail to reveal all, Collapse to fold back.
Child flex passthrough
The oas-grid-item flex attribute writes the CSS flex shorthand inline (not consumed by grid layout per CSS spec, zero interference) — a passthrough for host scenarios that place the item into flex containers.
API
oas-grid
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
align | Block-axis alignment (align-items): start / center / end / stretch / baseline; invalid values fall back to stretch with a dev warning (deduped) | string | — |
collapsed | Controlled collapsed attr for collapsed-rows (bootstrapped collapsed by default; host/tail can toggle) | — | — |
collapsed-rows | Rows visible when collapsed; overflow hidden with an expand/collapse tail cell (writes back collapsed, emits oas-collapse) | string | 1 |
cols | Total column count | string | 24 |
column-gap | Independent column gap (same rules) | string | — |
columns | Auto equal column count (simple-grid; child span ignored when set): supports breakpoint shorthand (e.g. 3 md:2 sm:1; breakpoints sm=640/md=768/lg=1024/xl=1280); takes precedence over min-child-width | string | — |
gap | Gap; a single value applies to both axes, two space-separated values set row column (e.g. 8 16 = row 8, column 16); three or more values are invalid and silently fall back to 0 | string | 0 |
justify | Inline-axis alignment (justify-items): start / center / end / stretch; invalid values fall back to stretch with a dev warning (deduped) | string | — |
min-child-width | Minimum child width (e.g. 180px; bare numbers read as px): auto-fit + minmax derives the column count from container width (breakpoint-free fluid reflow); columns wins when both are set, and child span/offset are inert in this mode | string | — |
row-gap | Independent row gap overriding the matching axis of gap (numbers as px) | string | — |
Events
| Event | Description |
|---|---|
oas-collapse | Emitted on collapsed-rows tail toggle, detail: { collapsed } |
Slots
| Name | Description |
|---|---|
| default | Grid children (oas-grid-item) |
CSS Variables
| CSS Variable | Default |
|---|---|
--oas-grid-columns | repeat(${base ?? 1}, 1fr) |
oas-grid-item
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
flex | Writes the CSS flex shorthand inline (unused by grid; passthrough for flex contexts) | string | — |
offset | Number of columns offset on the left; supports breakpoint shorthand (e.g. 0 lg:4: base value + space-separated breakpoint:value, breakpoints sm=640 / md=768 / lg=1024 / xl=1280) | string | 0 |
order | Ordering weight (number, default 0); higher values appear later, for reordering columns (equivalent to offset-based push/pull scenarios) | string | 0 |
pull | Shifts the start line left by N columns (same rules) | string | 0 |
push | Shifts the start line right by N columns (net = push−pull on top of offset) | string | 0 |
span | Number of columns spanned; supports auto (natural content width) and breakpoint shorthand (e.g. 24 md:12: base value + space-separated breakpoint:value, breakpoints sm=640 / md=768 / lg=1024 / xl=1280) | string | 24 |
Slots
| Name | Description |
|---|---|
| default | Grid cell content |
CSS Variables
| CSS Variable | Default |
|---|---|
--oas-grid-item-column | ${baseColumn} |
oas-grid renders as CSS Grid where each child occupies a share of the 24 columns; oas-grid-item declares its footprint with span. Setting columns divides equally and ignores span, so plain elements can be placed directly.