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].

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.

Note: As specified in CSS Box Alignment 3 § 8.1 Row and Column Gutters: the row-gap and column-gap properties, additional spacing between items added by justify-content and align-content is included in gap size.

3. Gap decorations

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

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.

3.1. Geometry

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

3.1.1. Segment endpoints

A 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.

.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;
}	

3.1.2. Gap decoration segments

Definitions

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.

In this section, we represent a gap decoration segment s 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.

Let UNION(s1, s2) be equal to [s1.start, s2.end].

A gap decoration segment is flanked by spanning items if, for every gap junction between its endpoints, there exist items on opposing sides of the gap that span across all perpendicular gaps contributing to that junction.

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.

Algorithms

3.2. Break behaviors at intersections: The column-rule-break, row-rule-break, and rule-break properties

These properties set 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 gap decoration segments.

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.

normal

Behavior depends on the type of container.

Grid containers

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

Flex containers

Behaves the same as none.

Multicol containers

On column-rule-break, behaves the same as intersection. On row-rule-break, behaves the same as none.

intersection

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

This shorthand property sets column-rule-break and row-rule-break to the same value.

The following examples illustrate various settings for the *-rule-break properties.

.break-normal-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: normal;
}

.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;
}

.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;
}

.break-normal-multicol {
  column-width: 150px;
  column-height: 300px;
  gap: 1em;
  row-rule: 4px solid red;
  column-rule: 4px solid blue;
  rule-break: normal;
}

.break-intersection-multicol {
  column-width: 150px;
  column-height: 300px;
  gap: 1em;
  row-rule: 4px solid red;
  column-rule: 4px solid blue;
  rule-break: intersection;
}

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

Note that each flex line has its own distinct gaps between items. This has two implications:

1. Gap decorations in adjacent flex lines are separate from each other even if the gaps happen to line up.
2. none would have the same visual effect as normal.

.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;
}

3.3. Adjusting gap decoration 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.

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

An interior segment endpoint is any segment endpoint created at a gap junction.

Percentages are resolved against the crossing gap width, defined as follows:

Edge segment endpoints

The crossing gap width is 0.

Interior segment endpoints

The crossing gap width is the size of the gap junction in the same dimension as the gap in which the segment endpoint lies (the horizontal dimension for row gaps and the vertical dimension for column gaps).

Note: Typically, this will be the used value of the column-gap or row-gap property, whichever applies to the intersecting or abutting gap, plus any additional spacing added due to justify-content or align-content. However, in cases where gaps intersect or abut one another at overlapping intervals, the crossing gap width will be determined by the union of such intervals. See this example for one such case.

The column-rule-edge-inset-start and row-rule-edge-inset-start properties apply to start segment endpoints that are edge segment endpoints. The column-rule-interior-inset-start and row-rule-interior-inset-start properties apply to start segment endpoints that are interior segment endpoints. For these properties, positive values offset in the forward direction, and negative values offset in the reverse direction, along the axis of the gap.

The column-rule-edge-inset-end and row-rule-edge-inset-end properties apply to end segment endpoints that are edge segment endpoints. The column-rule-interior-inset-end and row-rule-interior-inset-end properties apply to end segment endpoints that are interior segment endpoints. For these properties, positive values offset in the reverse direction, and negative values offset in the forward direction, along the axis of the gap.

3.3.1. -start and -end shorthands

These shorthands allow authors to achieve uniform asymmetric decorations.

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

These shorthand properties set the corresponding -edge- and -interior- properties to the same value. For example, column-rule-inset-start sets both column-rule-edge-inset-start and column-rule-interior-inset-start to the same value.

This shorthand property sets column-rule-inset-start and row-rule-inset-start to the same value.

This shorthand property sets column-rule-inset-end and row-rule-inset-end to the same value.

3.3.2. -edge- and -interior- shorthands

These shorthands allow authors to achieve different treatments at edge versus interior intersections.

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

These shorthands set the corresponding -start and -end properties. For example, column-rule-edge-inset sets both column-rule-edge-inset-start and column-rule-edge-inset-end. If one value is specified, both properties are set to that value. If two values are specified, -start is set to the first and -end is set to the second.

This shorthand property sets column-rule-edge-inset and row-rule-edge-inset to the same value.

This shorthand property sets column-rule-interior-inset and row-rule-interior-inset to the same value.

3.3.3. Universal shorthands

These shorthands allow authors to achieve uniform treatments throughout a container.

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

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

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

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

These shorthands set the corresponding edge and interior start and end values. The order of values is:

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

Omitted values are filled in as follows:

1. If the interior values are omitted, they are copied from the edge values.
2. Any omitted end value is copied from the corresponding start value.

This shorthand property sets column-rule-inset and row-rule-inset to the same value.

3.4. Gap decoration visibility: The rule-visibility-items properties

These properties control whether a gap decoration segment is painted in portions of gaps adjacent to empty areas.

all

Paint decorations in all gap segments, regardless of whether adjacent items are present.

around

Paint decorations in a gap segment if at least one of the two adjacent areas is occupied by an item.

between

Paint decorations in a gap segment if both adjacent areas are occupied by items.

This shorthand property sets column-rule-visibility-items and row-rule-visibility-items to the same value.

.break-normal-with-all-grid {
  display: grid;
  grid-template: repeat(3, 100px) / repeat(3, 100px);
  gap: 20px;
  row-rule: 6px solid red;
  column-rule: 6px solid blue;
  rule-visibility-items: all;
}

.break-normal-with-around-grid {
  display: grid;
  grid-template: repeat(3, 100px) / repeat(3, 100px);
  gap: 20px;
  row-rule: 6px solid red;
  column-rule: 6px solid blue;
  rule-visibility-items: around;
}

.break-normal-with-between-grid {
  display: grid;
  grid-template: repeat(3, 100px) / repeat(3, 100px);
  gap: 20px;
  row-rule: 6px solid red;
  column-rule: 6px solid blue;
  rule-visibility-items: between;
}

3.5. Gap decoration overlap: The rule-overlap property

This property sets the paint order for overlapping gap decorations.

row-over-column

Row-direction decorations are painted above column-direction decorations.

column-over-row

Column-direction decorations are painted above row-direction decorations.

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

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

3.6. Fragmentation

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.

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, row-rule-color, and 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> ]# )

These properties set the color of gap decorations.

This shorthand property sets column-rule-color and row-rule-color to the same value.

4.2. Gap decoration style: The column-rule-style, row-rule-style, and 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 apply the same as for border-style.

This shorthand property sets column-rule-style and row-rule-style to the same value.

4.3. Gap decoration width: The column-rule-width, row-rule-width, and 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> ]# )

These properties set the widths of gap decorations. Negative values are not allowed.

This shorthand property sets column-rule-width and row-rule-width to the same value.

4.4. Gap decoration shorthands: The column-rule, row-rule, and 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 shorthand properties set values for the column-rule-width, column-rule-style, and column-rule-color properties, or the row-rule-width, row-rule-style, and row-rule-color properties, respectively.

This shorthand property sets column-rule and row-rule to the same values.

4.5. Lists of values and the repeat() notation

Each of the properties in this section accepts a comma-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

Specifies 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 comma-separated list of values that would be accepted by the property in which the repeat() appears.

4.6. Assigning gap decoration values to gaps

Gap decorations are assigned after gutter collapsing 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 gap for decoration purposes.

4.7. Interpolation of list values

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

@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.8. Serialization

The column-rule, row-rule, and rule shorthands are serialized from component longhand properties only if the longhand properties are repeater aligned. If the longhand properties are not repeater aligned, the shorthand serializes as an empty string.

column-rule: 1px solid red, 2px dashed green, 3px dotted blue;

column-rule-width: 1px, 2px, 3px;
column-rule-style: solid, dashed, dotted;
column-rule-color: red, green, blue;

column-rule: 1px solid red, repeat(2, 2px dashed green);

column-rule-width: 1px, repeat(2, 2px);
column-rule-style: solid, repeat(2, dashed);
column-rule-color: red, repeat(2, green);

column-rule: repeat(auto, 1px solid red, 2px dashed green);

column-rule-width: repeat(auto, 1px, 2px);
column-rule-style: repeat(auto, solid, dashed);
column-rule-color: repeat(auto, red, green);

column-rule: repeat(auto, 1px solid red, 2px dashed green);
column-rule-width: repeat(auto, 3px, 4px, 5px);

column-rule-width: repeat(auto, 3px, 4px, 5px);
column-rule-style: repeat(auto, solid, dashed);
column-rule-color: repeat(auto, red, green);

column-rule: repeat(2, 1px solid red, 2px dashed green);
column-rule-style: dashed, dotted, solid;

column-rule-width: repeat(2, 1px, 2px);
column-rule-style: dashed, dotted, solid;
column-rule-color: repeat(2, red, green);

column-rule: repeat(2, 1px solid red, 2px dashed green);
column-rule-color: repeat(4, red, cyan);

column-rule-width: repeat(2, 1px, 2px);
column-rule-style: repeat(2, solid, dashed);
column-rule-color: repeat(4, red, cyan);

5. 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.

6. Privacy Considerations

No new privacy considerations have been reported on this specification.

7. Security Considerations

No new security considerations have been reported on this specification.

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)
• Renamed 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)
• Changed the rule-outset properties to rule-inset and introduced related properties. (Issue 12603, Issue 12848, Issue 8402)
• Updated the initial value of the inset properties to 0 and removed the auto keyword. (Issue 13137)
• Added a paragraph clarifying that gap decorations are not drawn where gaps are suppressed due to fragment breaks. (Issue 11520)
• Updated the behavior for when gaps are coincident due to track collapsing. (Issue 11814)
• Added a section for serializing shorthands from separate longhands. (Issue 12201)
• Updated the color, width, and style longhand properties to use comma-separated lists instead of space-separated lists. (Issue 12201)
• Added section for gap decorations next to empty grid areas. (Issue 12602)
• Clarified that alignment space contributes to gap size. (Issue 12922)
• Renamed the break value spanning-item to normal. (Issue 13127)
• Refreshed examples to reflect changes to the specification.
• Added links to WPT suite.
• Added Acknowledgements section.