CSS Gap Decorations Module Level 1

1. Introduction

This section is not normative.

CSS Multicol 1 § 4 Column Gaps and Rules allows for rules to be drawn between columns in a multicol container. This specification expands upon the column-rule-width, column-rule-style, and column-rule-color properties, adding equivalents in the row direction, expanding their application to other container layouts, and giving advanced control over where and how gap decorations are painted.

1.1. Value Definitions

This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units [CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the CSS-wide keywords as their property value. For readability they have not been repeated explicitly.

2. Gaps

Various layouts in CSS such as multicol containers, flex containers, grid containers, and grid lanes containers position child boxes adjacent to each other with gaps, also known as gutters, between them.

For the purposes of this specification, gap, column gap, and row gap are defined as follows depending on the type of container:

multi-column containers

In the column direction, gap (column gap) refers to the gutter between adjacent column boxes within each multicol line, see [CSS-MULTICOL-1]. In the row direction, gap (row gap) refers to the gutter between the rows of column boxes established by column-height, see [CSS-MULTICOL-2].

Note: It is important to note that column gaps in Multicol containers break when encountering a spanner element or a row gap.

flex containers

In the main axis (e.g. column-gap in a row flex container), gap (column gap) refers to the gutter between items within a single flex line.

In the cross axis (e.g. row-gap in a row flex container), gap (row gap) refers to the gutter between adjacent flex lines.

grid containers

row gaps and column gaps refer to the gutters between grid rows and grid columns, respectively. See CSS Grid Layout 1 § 10.1 Gutters: the row-gap, column-gap, and gap properties for precise details.

3. Gap decorations

Gaps may contain a gap decoration, which is a visible separator (such as a line) painted between adjacent boxes.

.grid-with-spans {
  display: grid;
  grid-template: repeat(4, 100px) / repeat(4, 100px);
  gap: 20px;
  row-rule: 6px solid red;
  column-rule: 6px solid blue;
}

.flex {
  display: flex;
  flex-wrap: wrap;
  gap: 20px;
  width: 500px;
  row-rule: 6px solid red;
  column-rule: 6px solid blue;
}

3.1. Layout and painting

Gap decorations do not take up space. That is, the presence or width of a gap decoration will not alter the placement of anything else. If a gap decoration is wider than its gap, any adjacent boxes will overlap the decoration, and in some cases the decoration may extend outside the box of the container. Gap decorations are painted just above the border of the container. For scrollable containers, note that while the border and background of the container aren’t scrolled, the decorations need to scroll along with items in the container.

Gap Decorations are painted within a gap as one or more gap decoration segments.

3.1.1. Segment Endpoints

A gap segment endpoint is a point on a gap’s centerline where a gap decoration segment may start or end. There are two endpoint types:

• start segment endpoint: Point at which a segment begins.
• end segment endpoint: Point at which a segment ends.

Segment endpoints are created at the following locations:

1. Bounds of a Gap:

   For each gap, endpoints are created at its two bounds:

   • At the start of the gap, a start segment endpoint is created.
   • At the end of the gap, an end segment endpoint is created.

   When a gap runs to the content boundary, these endpoints coincide with the corresponding content edge.

2. Within a Gap:

   When a cross/perpendicular gap touches a given gap (either overlapping it, or abutting it without overlapping), two endpoints are created which align with the boundaries of the cross/perpendicular gap:

   • The earlier boundary creates an end segment endpoint.
   • The later boundary creates a start segment endpoint.

   This ordering (end segment endpoint, start segment endpoint) reflects that the junction corresponds to the end of one track/item/column-box and the beginning of the next.

.grid-with-spans {
  display: grid;
  grid-template: repeat(4, 100px) / repeat(4, 100px);
  gap: 20px;
  background: rgb(255 255 128);
}
.grid > * {
  border: 1px dashed black;
}

.flex {
  display: flex;
  flex-wrap: wrap;
  gap: 20px;
  width: 500px;
  background: rgb(255 255 128);
}
.flex > * {
  border: 1px dashed black;
}

.multi-column {
  column-count: 3;
  column-width: 100px;
  column-height: 50px;
  column-wrap: wrap;
  gap: 20px;
  background: rgb(255 255 128);
}

.multi-column > * {
  height: 100px;
  border: 1px dashed black;
}	

NB: Should I mention different layout types and their gap behaviors here? Or is it implied? From preceeding sections. Feel Like I should for emphasis.

CSS Box Alignment 3 § 8.1 Row and Column Gutters: the row-gap and column-gap properties specifies that gaps disappear where they coincide with a fragmentation break. Because there is no gap in such locations, no gap decoration is drawn in them either.

Gap decorations are assigned after collapsed gutter has been applied. A given set of collapsed gutters consume exactly one gap decoration; the next gap decoration is applied to the next gutter (or set of collapsed gutters). Therefore, collapsed gutters are treated as a single gutter for decoration purposes.

3.1.2. Gap decoration segments

A gap decoration segment is formed by pairing a start segment endpoint with an end segment endpoint. Each gap forms a collection of gap decoration segments.

Note: In the end, there may remain ignored segment endpoints. These result in negative gap decoration segments. These are segments that would end up overlapping with other gap decoration segments, as a result these are purposefully ignored and no decoration is painted for them. See below for examples.

3.2. Breaking gap decorations into segments: The column-rule-break, row-rule-break, and rule-break properties

Sets the behavior for breaking decorations within a given gap into segments at visible "T" or "cross" intersections formed by items in the container. Precise details for how to apply these values are given in the steps to determine pairs of gap decoration endpoints.

none

Gap decorations do not start or end at visible "T" or "cross" intersections. Instead, a single continuous decoration is painted from one end of the gap to the other.

spanning-item

Gap decorations start and end at visible "T" intersections but continue through visible "cross" intersections.

intersection

Gap decorations start and end at visible "T" and "cross" intersections.

Bikeshed these values.

Sets the column-rule-break and row-rule-break properties to the same value.

3.2.1. Determining Candidate Gap Segments From Break Rules

Recall that a gap decoration segment, s, can be represented as: s = [s.start, s.end] where s.start is the start segment endpoint of the segment, and s.end is the end segment endpoint of the segment.

In the context of a given gap, a pair of segment endpoints a and b is considered discontiguous if a line segment from a to b, with the same width as the gap, intersects a child item in the container.

Define an operation UNION(s1, s2) which updates s1 such that: s1 = [s1.start, s2.end]

For two adjacent segments s and t (where t begins where s ends), UNION(s, t) is flanked by spanning items if spanning items exist on opposing sides of the segments.

The following examples illustrate various settings for the *-rule-break properties. To make the differences more apparent, the *-rule-*-inset properties are set to 0 and *-rule-visibility-items is set to all.

.break-none-grid {
  display: grid;
  grid-template: repeat(4, 100px) / repeat(4, 100px);
  gap: 20px;
  row-rule: 6px solid red;
  column-rule: 6px solid blue;
  rule-break: none;
  rule-inset: 0px;
}

.break-spanning-item-grid {
  display: grid;
  grid-template: repeat(4, 100px) / repeat(4, 100px);
  gap: 20px;
  row-rule: 6px solid red;
  column-rule: 6px solid blue;
  rule-break: spanning-item;
  rule-inset: 0px;
}

.break-intersection-grid {
  display: grid;
  grid-template: repeat(4, 100px) / repeat(4, 100px);
  gap: 20px;
  row-rule: 6px solid red;
  column-rule: 6px solid blue;
  rule-break: intersection;
  rule-inset: 0px;
}

.break-none-flex {
  display: flex;
  flex-wrap: wrap;
  gap: 20px;
  row-rule: 6px solid red;
  column-rule: 6px solid blue;
  rule-break: none;
  rule-inset: 0px;
}

Note: Because flexbox has no concept of spanning items, spanning-item on a flexbox has the same effect as none.

.break-intersection-flex {
  display: flex;
  flex-wrap: wrap;
  gap: 20px;
  width: 500px;
  gap: 20px;
  row-rule: 6px solid red;
  column-rule: 6px solid blue;
  rule-break: intersection;
  rule-inset: 0px;
}

3.3. Painting Gap Decorations with Visibility Rules

These properties control whether a candidate gap decoration segment is painted in portions of gutters adjacent to empty cells.

all

Paint decorations in all gap segments, regardless of whether cells are occupied. This is the initial value.

around

Paint decorations in a gap segment if at least one of the two cells adjacent to that segment contains an item.

between

Paint decorations in a gap segment if both of the two cells adjacent to that segment contain items.

Sets the column-rule-visibility-items and row-rule-visibility-items properties to the same value.

TODO: FIX: SAM ADD WPT LINKS HERE.

3.3.1. Adjusting Endpoints When Appending

Given a segment s = [start, end], when appending s to the list of segments to be painted in the above algorithms:

1. Compute the offset for start within gap. Offset start by the result, in the forward direction along gap’s axis.
2. Compute the offset for end within gap. Offset end by the result, in the reverse direction along gap’s axis.
3. Replace s with the adjusted [start, end].

TODO: FIX: SAM ADD EXAMPLE ILLUSTRATING THIS VISIBILITY RULES.

3.4. Adjusting gap segment endpoints: The rule-inset properties

These properties can be used to offset the start and end points of gap decorations relative to the segment endpoints which would normally determine where decorations start and end.

A value of 0 places the gap decoration start and end points exactly on the [start segment endpoint=] and end segment endpoint, respectively, of the gap decoration segment. For the interior properties, because percentages refer to the crossing gap width, a value of -50% places the gap decoration endpoint exactly in the middle of the adjoining intersection.

auto

The used value of auto is 0 for edge properties and -50% for interior properties.

An edge segment endpoint is any segment endpoint at the content edges of the container.

An interior segment endpoint is any segment endpoint that is not an edge segment endpoint.

A given start segment endpoint and end segment endpoint can be either an edge segment endpoint or an interior segment endpoint.

These properties control the behavior for any start segment endpoint that is an edge segment endpoint, while the column-rule-edge-inset-end and row-rule-edge-inset-end properties control the behavior for any end segment endpoint that is an edge segment endpoint. Positive values recede inwards from the content edge, while negative values extend outwards, beyond the container’s content bounds.

The column-rule-interior-inset-start and row-rule-interior-inset-start properties control the behavior for any start segment endpoint that is an interior segment endpoint, while the column-rule-interior-inset-end and row-rule-interior-inset-end properties control the behavior for any end segment endpoint that is an interior segment endpoint. Positive values recede away from the segment endpoint, while negative values extend beyond it.

Sets the column-rule-edge-inset-start and column-rule-edge-inset-end properties to the specified values. Similarly, sets the row-rule-edge-inset-start and row-rule-edge-inset-end properties to the specified values.

Sets the column-rule-interior-inset-start and column-rule-interior-inset-end properties to the specified values. Similarly, sets the row-rule-interior-inset-start and row-rule-interior-inset-end properties to the specified values.

Sets the column-rule-edge-inset and row-rule-edge-inset properties to the same value.

Sets the column-rule-interior-inset and row-rule-interior-inset properties to the same value.

Sets the column-rule-inset and row-rule-inset properties to the same value. Syntax is as follows:

edge-start edge-end? [/ interior-start interior-end?]?

Sets the column-rule-edge-inset-start and column-rule-interior-inset-start properties to the same value. Similarly, sets the row-rule-edge-inset-start and row-rule-interior-inset-start properties to the same value.

Sets the column-rule-edge-inset-end and column-rule-interior-inset-end properties to the same value. Similarly, sets the row-rule-edge-inset-end and row-rule-interior-inset-end properties to the same value.

Sets the column-rule-inset-start and row-rule-inset-start properties to the same value.

Sets the column-rule-inset-end and row-rule-inset-end properties to the same value.

.inset-0px {
  column-rule-inset: 0px;
  column-rule-break: intersection;
}

.inset-negative-5px {
  column-rule-inset: -5px;
  column-rule-break: intersection;
}

.inset-start-8px-end-0px {
  column-rule-inset-start: 8px;
  column-rule-inset-end: 0px;
}

.inset-edge-0px-interior-negative-5px {
  column-rule-edge-inset: 0px;
  column-rule-interior-inset: -5px;
  column-rule-break: intersection;
}

.inset-50percent {
  column-rule-inset: 50%;
  column-rule-break: intersection;
}

.inset-positive-5px {
  column-rule-inset: 5px;
  column-rule-break: intersection;
}

When considering the segment endpoints within a given gap, each point is assigned a crossing gap width, defined as follows:

At the content edge of the container

The crossing gap width is 0.

At an intersection with another gap

The crossing gap width is the used value of the column-gap or row-gap property, whichever applies to the intersecting gap.

For details on how the offset is applied, see § 3.3.1 Adjusting Endpoints When Appending.

3.5. Gap decoration overlap: The rule-overlap property

Sets the overlap for gap decorations in two-dimensional containers.

The following examples illustrate adjustment of gap decoration overlap using the rule-overlap property.

.row-over-coulumn {
  rule-overlap: row-over-column;
  row-rule: 6px solid red;
  column-rule: 6px solid blue;
}

rule-overlap: column-over-row;
row-rule: 6px solid red;
column-rule: 6px solid blue;

4. Color, style, and width

Property definitions in this section supersede the definitions of properties with the same names in [CSS-MULTICOL-1].

4.1. Gap decoration color: The column-rule-color and row-rule-color properties

<line-color-list>          = [ <line-color-or-repeat> ]+

<auto-line-color-list>     = [ <line-color-or-repeat> ]*
                             <auto-repeat-line-color>
                             [ <line-color-or-repeat> ]*

<line-color-or-repeat>     = [ <color> | <repeat-line-color> ]

<repeat-line-color>        = repeat( [ <integer [1,∞]> ] , [ <color> ]+ )

<auto-repeat-line-color>   = repeat( auto , [ <color> ]+ )

<color>

Sets the color of gap decorations.

4.2. Gap decoration style: The column-rule-style and row-rule-style properties

<line-style-list>          = [ <line-style-or-repeat> ]+

<auto-line-style-list>     = [ <line-style-or-repeat> ]*
                             <auto-repeat-line-style>
                             [ <line-style-or-repeat> ]*

<line-style-or-repeat>     = [ <line-style> | <repeat-line-style> ]

<repeat-line-style>        = repeat( [ <integer [1,∞]> ] , [ <line-style> ]+ )

<auto-repeat-line-style>   = repeat( auto , [ <line-style> ]+ )

These properties set the styles of gap decorations. The <line-style> values are interpreted as in the collapsing border model.

4.3. Gap decoration width: The column-rule-width and row-rule-width properties

<line-width-list>          = [ <line-width-or-repeat> ]+

<auto-line-width-list>     = [ <line-width-or-repeat> ]*
                             <auto-repeat-line-width>
                             [ <line-width-or-repeat> ]*

<line-width-or-repeat>     = [ <line-width> | <repeat-line-width> ]

<repeat-line-width>        = repeat( [ <integer [1,∞]> ] , [ <line-width> ]+ )

<auto-repeat-line-width>   = repeat( auto , [ <line-width> ]+ )

This property sets the widths of gap decorations. Negative values are not allowed.

4.4. Lists of values and the repeat() notation

Each of the properties in this section accepts a space-separated list of values. Setting multiple values in this way allows for varying gap decorations within a given container.

column-rule-width: 1px;
column-rule-style: solid;
column-rule-color: red blue;

Such a list may contain repeat() notations. Similar to CSS Grid Layout 1 § 7.2.3 Repeating Rows and Columns: the repeat() notation, these notations allow a series of gap decorations that exhibit a recurring pattern to be written in a more compact form.

The generic form of the repeat() syntax is, approximately,

repeat( [ <integer [1,∞]> | auto ] , <value>+ )

The first argument to repeat() specifies the number of repetitions.

<integer>

Specifies an integer repeater. An integer repeater expands out to the list of values in the second argument, repeated as many times as specified by the first argument.

An author may write:

column-rule-color: gray red blue red blue red blue gray;

Or shorten to the following, which produces the same sequence of colors:

column-rule-color: gray repeat(3, red blue) gray;

auto

Specfies an auto repeater. An auto repeater will be used to fill in values for gaps that would not otherwise receive values from other parts of the list. At most one repeat() in a given list of values may be an auto repeater.

Continuing from the previous example, if the author does not know how many columns will be in the final layout, they might instead write:

column-rule-color: gray repeat(auto, red blue) gray;

Which will produce a gray decoration in the first and last column gaps, and alternating red and blue decorations in the in-between column gaps.

The second argument to repeat() is a space-separated list of values that would be accepted by the property in which the repeat() appears.

4.4.1. Interpolation behavior

1. Expansion: Expand any integer repeater into its equivalent list of values.
2. List Interpolation: Apply the repeatable list interpolation algorithm to the expanded lists, interpolating each item against its counterpart.

@keyframes example {
  from { column-rule-width: 10px; }
  to   { column-rule-width: 20px 40px; }
}

From:   10px 10px
At 50%: 15px 25px
To:     20px 40px

@keyframes example {
  from { column-rule-width: repeat(2, 5px 10px); }
  to   { column-rule-width: repeat(2, 15px 20px); }
}

From:    5px 10px  5px 10px
At 50%: 10px 15px 10px 15px
To:     15px 20px 15px 20px

@keyframes example {
  from { column-rule-width: repeat(2, 10px 20px); }
  to   { column-rule-width: 20px; }
}

From:   10px 20px 10px 20px
At 50%: 15px 20px 15px 20px
To:     20px 20px 20px 20px

@keyframes example {
  from { column-rule-width: repeat(2, 10px 20px); }
  to   { column-rule-width: 20px 30px; }
}

From:   10px 20px 10px 20px
At 50%: 15px 25px 15px 25px
To:     20px 30px 20px 30px

4.4.1.1. Lists with Auto Repeaters

@keyframes example {
  from { column-rule-width: 10px repeat(auto, 20px) 30px }
  to   { column-rule-width: 20px repeat(auto, 40px) 40px }
}

From:   10px repeat(auto, 20px) 30px
At 50%: 15px repeat(auto, 30px) 35px
To:     20px repeat(auto, 40px) 40px

@keyframes example {
  from { column-rule-width: 10px 20px repeat(auto, 20px) 30px }
  to   { column-rule-width: 20px 30px repeat(auto, 40px 50px) 40px }
}

From:   10px 20px repeat(auto, 20px 20px) 30px
At 50%: 15px 25px repeat(auto, 30px 35px) 35px
To:     20px 30px repeat(auto, 40px 50px) 40px

@keyframes example {
  from { column-rule-width: 10px repeat(auto, 20px) }
  to   { column-rule-width: 20px 30px repeat(auto, 40px 50px) }
}

@keyframes example {
  from { column-rule-width: 10px repeat(auto, 20px) 30px }
  to   { column-rule-width: 20px repeat(auto, 40px) 40px 50px }
}

@keyframes example {
  from { column-rule-width: 10px repeat(auto, 20px) 30px }
  to   { column-rule-width: 20px }
}

4.5. Gap decoration shorthands: The column-rule and row-rule properties

<gap-rule-list>        = <gap-rule-or-repeat>#

<gap-auto-rule-list>   = <gap-rule-or-repeat>#? ,
                         <gap-auto-repeat-rule> ,
                         <gap-rule-or-repeat>#?

<gap-rule-or-repeat>   = <gap-rule> | <gap-repeat-rule>

<gap-repeat-rule>      = repeat( <integer [1,∞]> , <gap-rule># )

<gap-auto-repeat-rule> = repeat( auto , <gap-rule># )

<gap-rule>             = <line-width> || <line-style> || <color>

These shorthands set the corresponding width, style, and color properties as a set.

4.6. Bi-directional gap decoration shorthands: The rule-color, rule-style, rule-width, and rule properties

These shorthands set the corresponding column and row properties to the same values.

5. Privacy Considerations

No new privacy considerations have been reported on this specification.

6. Security Considerations

No new security considerations have been reported on this specification.

7. Acknowledgements

This specification is made possible by contributions and feedback from many people, including: Ahmad Shadeed, Alison Maher, Benoît Rouleau, Elika Etemad, Ian Kilpatrick, Javier Contreras Tenorio, Josh Tumath, Kurt Catti-Schmidt, Lea Verou, Oliver Williams, Rachel Andrew, Sam Davis Omekara Jr., Sebastian Zartner, Tab Atkins-Bittner, and the CSS Working Group members. Special thanks to Mats Palmgren who drafted an initial proposal for Gap Decorations.

8. Changes

8.1. Changes since the 17 April 2025 Working Draft

• Specified the behavior when gaps are coincident due to track collapsing. (Issue 11814)
• Added links to WPT suite.
• Updated rule-paint-order to rule-overlap. (Issue 12540)
• Updated the definition for intersections to use gutter. (Issue 12084)
• Updated trailing gap decoration assignment to use values in forward order. (Issue 12527)
• Specified the interpolation behavior for values which may contain repeaters. (Issue 12431)
• Removed the special case of column-rule-width having a computed value of 0 when column-rule-style is none or hidden. (Issue 11494)
• Updated `*-outset` to `*-inset` and introduced related properties. (Issue 12603, Issue 12848, Issue 8402)
• Added a paragraph clarifying that gap decorations are not drawn where gaps are suppressed due to fragment breaks.
• Corrected syntax errors for the inset shorthands.
• Updated the behavior for when gaps are coincident due to track collapsing. (Issue 11814)