Skip to content

[css-align][css-gaps] Move the gap properties to the Gaps spec and rename per CSSWG resolution. #13089 #13312

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kbabbitt wants to merge 6 commits into
base: main
Choose a base branch
from
Open

[css-align][css-gaps] Move the gap properties to the Gaps spec and rename per CSSWG resolution. #13089 #13312

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
84abff0
[css-align][css-gaps] Move the gap properties to the Gaps spec
kbabbitt Jan 7, 2026
956894a
Change title per CSSWG resolution
kbabbitt Jan 7, 2026
94cd4da
Move example image
kbabbitt Jan 7, 2026
ee5ed7c
Note changes
kbabbitt Jan 7, 2026
48773d3
Un-linkify reference that doesn't resolve yet
kbabbitt Jan 7, 2026
84c9f09
Merge branch 'main' into move-gaps
kbabbitt Jan 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
196 changes: 2 additions & 194 deletions css-align-3/Overview.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2003,200 +2003,6 @@ Default Alignment Shorthand: the 'place-items' property</h3>
The second value is assigned to 'justify-items';
if omitted, it is copied from the first value.


<!--
██████ ███ ████████ ██████
██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██
██ ████ ██ ██ ████████ ██████
██ ██ █████████ ██ ██
██ ██ ██ ██ ██ ██ ██
██████ ██ ██ ██ ██████
-->

<h2 id='gaps'>
Gaps Between Boxes</h2>

While 'margin' and 'padding' can be used to specify visual spacing around individual boxes,
it's sometimes more convenient to globally specify spacing
<em>between</em> adjacent boxes within a given layout context,
particularly when the spacing is different between sibling boxes
as opposed to between the first/last box and the container's edge.

The 'gap' property,
and its 'row-gap' and 'column-gap' sub-properties,
provide this functionality for
<a href="http://www.w3.org/TR/css3-multicol/">multi-column</a>,
<a href="http://www.w3.org/TR/css-flexbox/">flex</a>,
and <a href="http://www.w3.org/TR/css-grid/">grid layout</a>.

<h3 id='column-row-gap'>
Row and Column Gutters: the 'row-gap' and 'column-gap' properties</h3>

<pre class='propdef'>
Name: row-gap, column-gap
Value: normal | <<length-percentage [0,∞]>>
Initial: normal
Applies to: <a>multi-column containers</a>, <a>flex containers</a>, <a>grid containers</a>
Inherited: no
Percentages: see [[#gap-percent]]
Computed value: specified keyword, else a computed <<length-percentage>> value
Animation type: by computed value type
</pre>

These properties specify fixed-length <dfn export lt="gutter">gutters</dfn>
between items in the container,
adding space between them--
in a manner similar to the ''justify-content/space-between'' keyword
of the <a>content-distribution properties</a>,
but of a fixed size instead of as a fraction of remaining space.
The 'column-gap' property specifies spacing between “columns”,
separating boxes in the container's <a>inline axis</a>
similar to <a>inline-axis</a> margin;
while 'row-gap' indicates spacing between “rows”,
separating boxes in the container's <a>block axis</a>.

Values have the following meanings:

<dl dfn-type=value dfn-for="row-gap, column-gap, gap">
: <<length-percentage [0,∞]>>
::
Specifies a gap between “rows” or “columns”,
as defined by the layout modes to which it applies;
see subsections below for details.

Negative values are invalid.
For percentages,
see [[#gap-percent]].

: <dfn>normal</dfn>
:: The value ''gap/normal'' represents
a used value of ''1em'' on <a>multi-column containers</a>,
and a used value of ''0px'' in all other contexts.
</dl>

Gutters effect a minimum spacing between items:
additional spacing may be added by 'justify-content'/'align-content'.
Such additional space effectively increases the size of these <a>gutters</a>.

The exact handling of these properties varies by layout container:

<dl>
<dt id="gap-multicol"><a>multi-column containers</a>
<dd>
'column-gap' specifies the [=gutter=] between adjacent <a>column boxes</a>,
see [[CSS-MULTICOL-1]].
'row-gap' specifies the [=gutter=] between the rows of [=column boxes=] established by 'column-height',
see [[CSS-MULTICOL-2]].

<dt id="gap-flex"><a>flex containers</a>
<dd>
When applied to the <a>main axis</a>
(e.g. 'column-gap' in a ''flex-flow/row'' <a>flex container</a>),
indicates the [=gutter=] between items
(as if an additional fixed-size margin were inserted
between adjacent <a>flex items</a>
in a single line).

When applied to the <a>cross axis</a>
(e.g. 'row-gap' in a ''flex-flow/row'' <a>flex container</a>),
indicates the [=gutter=] between adjacent <a>flex lines</a>.

<dt id="gap-grid"><a>grid containers</a>
<dd>
The 'row-gap' and 'column-gap' properties,
when specified on a <a>grid container</a>,
define the [=gutters=] between <a>grid rows</a> and <a>grid columns</a>,
respectively.
See [[css-grid-1#gutters]] for precise details.
</dl>

In all cases, the [=gutter=] disappears when it coincides with
a [=fragmentation break=]. [[CSS-BREAK-3]]

Note: Table boxes do not use the 'gap' properties
to specify separation between their cells.
Instead, they use the 'border-spacing' property,
which has slightly different functionality:
it inherits,
and it also specifies the additional spacing between the outermost cells
and the border of the table
(similar to ''space-evenly'' rather than ''space-between'').

<h3 id='gap-shorthand'>
Gap Shorthand: the 'gap' property</h3>

<pre class='propdef'>
Name: gap
Value: <<'row-gap'>> <<'column-gap'>>?
Initial: see individual properties
Applies to: <a>multi-column containers</a>, <a>flex containers</a>, <a>grid containers</a>
Inherited: no
Percentages: refer to corresponding dimension of the content area
Computed value: see individual properties
Animation type: by computed value type
</pre>

This property is a <a>shorthand</a> that sets 'row-gap' and 'column-gap' in one declaration.
If <<'column-gap'>> is omitted,
it's set to the same value as <<'row-gap'>>.

<div class='example'>
<figure>
<img src="images/gutters-gaps.svg" alt="A diagram showing how margins and padding add to the visible gutter size" width="500" height="616">
</figure>

Note: The 'gap' property is only one component of the visible “gutter” or “alley” created between boxes.
Margins, padding, or the use of distributed alignment
may increase the visible separation between boxes
beyond what is specified in 'gap'.
</div>

<h3 id='gap-percent'>
Percentages In 'gap' Properties</h3>

In general,
gaps introduced by the 'gap' properties
are intended to act like an empty item/track/etc
with the gap's size;
in other words,
an author should be able to reproduce the effects of 'gap'
by just inserting additional empty items/tracks/etc
into the container.

'gap' always resolves percentages against
the corresponding size of the [=content box=]
of the element.
When this size is definite,
the behavior is well-defined
and consistent across layout modes.
But since different layout modes treat [=cyclic percentage sizes=] for items/tracks/etc differently,
'gap' does as well:

: In Grid Layout
::
<a href="https://www.w3.org/TR/css-sizing-3/#percentage-sizing">As in the min size properties and margins/paddings</a> [[CSS-SIZING-3]],
[=cyclic percentage sizes=] resolve against zero
for determining intrinsic size contributions,
but resolve against the box’s content box
when laying out the box’s contents.

: In Flex Layout
::
[=Cyclic percentage sizes=] resolve against zero in all cases.

<h3 id='gap-legacy'>
Legacy Gap Properties: the 'grid-row-gap', 'grid-column-gap', and 'grid-gap' properties</h3>

The Grid Layout module was originally written with its own set of [=gutter=] properties,
before all such properties were unified into the existing 'row-gap'/'column-gap' naming.
For compatibility with legacy content,
these grid-prefixed names must be supported as follows:

* <dfn property>grid-row-gap</dfn> as a [=legacy name alias=] of the 'row-gap' property
* <dfn property>grid-column-gap</dfn> as a [=legacy name alias=] of the 'column-gap' property
* <dfn property>grid-gap</dfn> as a [=legacy name alias=] of the 'gap' property

<!--
████████ ███ ██████ ████████ ██ ████ ██ ██ ████████
██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██
Expand Down Expand Up @@ -2525,6 +2331,8 @@ Changes</h2>
* Allow absolutely positioned boxes to honor alignment even when overflowing into
the scrollable overflow area of a scroll container containing block.
(<a href="https://github.com/w3c/csswg-drafts/issues/12106">Issue 12106</a>)
* Moved the gap properties to [[!CSS-GAPS-1]].
(<a href="https://github.com/w3c/csswg-drafts/issues/13089">Issue 13089</a>)

See also <a href="https://www.w3.org/TR/2025/WD-css-align-3-20250311/#changes">previous changes</a>.

Expand Down
Loading