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.

Gaps in a grid container; column gaps in orange and row gaps in blue. Note the shaded areas where gaps overlap.

Gaps in a flex container; column gaps in orange and row gaps in blue. Note that, unlike in grid, gaps in flex do not overlap.

Gaps in a multicol container with `column-wrap: wrap`; column gaps in orange and row gaps in blue). Note that column gaps in multicol containers do not overlap row gaps, similar to flex.

Column gaps in orange in a multicol container with a spanner element. Note that column gaps break when they encounter the spanner.

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

A grid with spanning items and gap decorations.

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

To create segment endpoints for a gap G:

Bounds of a Gap:
Create endpoints at G’s two bounds:
- At the start of G, create a start segment endpoint.
- At the end of G, create an end segment endpoint.
When a gap runs to the content boundary, these endpoints coincide with the corresponding content edge.
Within a Gap:
When a cross/perpendicular gap touches G (either overlapping it, or abutting it without overlapping), create two endpoints 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 and the beginning of the next.

The following examples illustrate the locations of segment endpoints, with a purple + for start segment endpoints and a green + for end segment endpoints in each case.

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

Locations of segment endpoints in a grid with spanning items. These are created at the bounds of each gap (which coincide with the edges of the container in this case), and within each gap in an end-start manner where the row and column gaps overlap/intersect.

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

Locations of segment endpoints in a flex container. Column gaps create endpoints at their bounds; some bounds coincide with the container edges (like the start of the gaps between #1 and #2, and #2 and #3 which coincide with the top edge of the container, and the end of the gap between #7 and #8 which coincides with the bottom edge of the container). Row gaps (between flex lines) create endpoints at their bounds, which coincide with the left and right edges of the container. Where column gaps abut row gaps, two endpoints are created in an end-start manner.

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

Locations of segment endpoints in a multi-column container. Column gaps (between column boxes) create endpoints at their bounds;some bounds coincide with the container edges (like the start of the first 2 column gaps which coincide with the top edge, and the end of the last 2 column gaps which coincide with the bottom edge). The row gap (between rows of column boxes) creates endpoints at its bounds, which coincide with the left and right edges of the container. Where column gaps abut the row gap, two endpoints are created in an end-start manner.

Tests

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.

Tests

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

To determine the gap decoration segments for a given gap G:

Let S, the collection of gap decoration segments for G, be an empty list.
Let endpoints be the list of segment endpoints created for G, ordered from start to end.
Let segmentStart be the first segment endpoint in endpoints.
Note: The first endpoint is always a start segment endpoint since every gap begins with a start bound.
Let counter be 1.
For each segment endpoint a in endpoints starting from the second:
1. If a is a start segment endpoint:
  1. If counter is 0, set segmentStart to a.
  2. Increment counter by 1.
2. If a is an end segment endpoint:
  1. Decrement counter by 1.
  2. If counter is 0:
    1. Create a new gap decoration segment from segmentStart to a, and append it to S.

Note: A segment is only created when counter transitions from 1 to 0. Due to item positioning in flex, consecutive segment endpoints of the same type can occur, causing some endpoints to remain unpaired.

Illustration of gap decoration segments (blue and red rectangles) in a grid container. The segments are drawn between pairs of segment endpoints, with start segment endpoints marked with purple crosses and end segment endpoints marked with green crosses.

Illustration of gap decoration segments (blue and red rectangles) in a flex container. The segments are drawn between pairs of segment endpoints, with start segment endpoints marked with purple crosses and end segment endpoints marked with green crosses.

Illustration of gap decoration segments (blue and red rectangles) in a multicol container (with column-wrap: wrap). The segments are drawn between pairs of segment endpoints, with start segment endpoints marked with purple crosses and end segment endpoints marked with green crosses.

Illustration of gap decoration segments (blue rectangles) in a multicol container (with a spanner element). The segments are drawn between pairs of segment endpoints, with start segment endpoints marked with purple crosses and end segment endpoints marked with green crosses.

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

Name:	column-rule-break, row-rule-break
Value:	none \| spanning-item \| intersection
Initial:	spanning-item
Applies to:	grid containers, flex containers, multicol containers, and grid lanes containers
Inherited:	no
Percentages:	n/a
Computed value:	as specified
Canonical order:	per grammar
Animation type:	discrete

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

Name:	rule-break
Value:	<'column-rule-break'>
Initial:	see individual properties
Applies to:	Same as column-rule-break and row-rule-break
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

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

Tests

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.

To determine candidate segments C from segments list S:

Let S be the list of segments determined for the given gap, ordered from start to end along the gap’s axis.
Let C be an empty list of segments.
Let break be the used value of either column-rule-break or row-rule-break, whichever applies to the gap.
If S is empty, return C.
If break is none:
1. Let s be the first segment in S.
2. Let last be the last segment in S.
3. UNION(s, last)
4. Append s to C
5. Return C.
Remove the first segment from S. Let s be that segment.
If s’s endpoints are discontiguous, go back to step 4.
If S is not empty:
1. Let next be the first segment in S.
2. Let candidate be a copy of s, then UNION(candidate, next)
3. If candidate’s endpoints are discontiguous, go to step 9.
4. If break is intersection and candidate is not flanked by spanning items, go to step 9.
5. Remove the first segment from S.
6. UNION(s, next)
7. Go back to step 8.
Append s to C.
Go back to step 4.

To append a segment for painting, given a segment s = [start, end}:

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

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.

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

Grid gap decorations with no breaks. Note that the gap decorations extend "behind" items placed in the grid.

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

Grid gap decorations broken at spanning items.

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

Grid gap decorations contained within each gap decoration segment that is not flanked by spanning items on opposing sides.

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

Flexbox gap decorations with no breaks. Note that each flex line has its own distinct gaps. Therefore, gap decorations in adjacent flex lines are separate from each other even if the gaps happen to line up.

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

Flexbox gap decorations contained within each gap decoration segment.

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

Name:	column-rule-edge-inset-start, column-rule-edge-inset-end, row-rule-edge-inset-start, row-rule-edge-inset-end
Value:	auto \| <length-percentage>
Initial:	auto
Applies to:	grid containers, flex containers, multicol containers, and grid lanes containers
Inherited:	no
Percentages:	refer to the crossing gap width
Computed value:	as specified
Canonical order:	per grammar
Animation type:	by computed value type

Name:	column-rule-interior-inset-start, column-rule-interior-inset-end, row-rule-interior-inset-start, row-rule-interior-inset-end
Value:	auto \| <length-percentage>
Initial:	auto
Applies to:	grid containers, flex containers, multicol containers, and grid lanes containers
Inherited:	no
Percentages:	refer to the crossing gap width
Computed value:	as specified
Canonical order:	per grammar
Animation type:	by computed value type

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.

Name:	column-rule-edge-inset, row-rule-edge-inset
Value:	<length-percentage> [ <length-percentage> ]?
Initial:	see individual properties
Applies to:	Same as column-rule-edge-inset-start, column-rule-interior-inset-start, row-rule-edge-inset-end, and row-rule-interior-inset-end
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

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.

Name:	column-rule-interior-inset, row-rule-interior-inset
Value:	<length-percentage> [ <length-percentage> ]?
Initial:	see individual properties
Applies to:	Same as column-rule-edge-inset-start, column-rule-interior-inset-start, row-rule-edge-inset-end, and row-rule-interior-inset-end
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

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.

Name:	rule-edge-inset
Value:	<'column-rule-edge-inset'>
Initial:	see individual properties
Applies to:	Same as column-rule-edge-inset and row-rule-edge-inset
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

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

Name:	rule-interior-inset
Value:	<'column-rule-interior-inset'>
Initial:	see individual properties
Applies to:	Same as column-rule-interior-inset and row-rule-interior-inset
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

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

Name:	column-rule-inset, row-rule-inset
Value:	<length-percentage> <length-percentage>? [/ <length-percentage> <length-percentage>?]?
Initial:	see individual properties
Applies to:	Same as column-rule-edge-inset, column-rule-interior-inset, row-rule-edge-inset, and row-rule-interior-inset
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

Name:	rule-inset
Value:	<'column-rule-inset'>
Initial:	see individual properties
Applies to:	Same as column-rule-inset and row-rule-inset
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

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

where each of edge-start, edge-end, interior-start, and interior-end are <length-percentage> values.

Name:	column-rule-inset-start, row-rule-inset-start
Value:	auto \| <length-percentage>
Initial:	see individual properties
Applies to:	column-rule-edge-inset-start and column-rule-interior-inset-start for column-rule-inset-start, row-rule-edge-inset-start and row-rule-interior-inset-start for row-rule-inset-start
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

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.

Name:	column-rule-inset-end, row-rule-inset-end
Value:	auto \| <length-percentage>
Initial:	see individual properties
Applies to:	column-rule-edge-inset-end and column-rule-interior-inset-end for column-rule-inset-end, row-rule-edge-inset-end and row-rule-interior-inset-end for row-rule-inset-end
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

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.

Name:	rule-inset-start
Value:	<'column-rule-inset-start'>
Initial:	see individual properties
Applies to:	Same as column-rule-inset-start and row-rule-inset-start
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

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

Name:	rule-inset-end
Value:	<'column-rule-inset-end'>
Initial:	see individual properties
Applies to:	Same as column-rule-inset-end and row-rule-inset-end
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

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

An inset of 0px aligns the ends of gap decorations with adjacent items.

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

An inset of -5px extends the ends of gap decorations slightly beyond the edges of adjacent items.

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

A start edge inset of 8px and an end edge inset of 0px recede the start segment endpoints of edge gap decorations away from the start of the gap, and align the end segment endpoints with the content edge at the end of the gap. A start interior inset of 8px and an end interior inset of 0px recede the start segment endpoints of interior gap decorations away from the edges of adjacent items at the start of the gap, and align the end segment endpoints with the edges of adjacent items at the end of the gap.

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

An interior inset of -5px extends the endpoints of interior gap decorations slightly beyond the edges of adjacent items. An edge inset of 0px aligns the endpoints of edge gap decorations with the content edges.

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

An inset of 50% - the initial value - extends each end of a gap decoration halfway into its intersection. Neighboring gap decorations "meet in the middle" to create a continuous line. Note that at the edges of the container, the crossing gap width is defined to be 0, so the inset value of 50% resolves to 0 and thus the gap decoration does not extend beyond the bounds of the container. (Contrast with the previous example, which specified an inset in px units.)

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

An inset of 5px shortens the ends of gap decorations relative to the edges of adjacent items.

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.

To compute the offset for a given segment endpoint point within a given gap:

Let width be the crossing gap width for point.
Let inset be the computed value of either column-rule-inset or row-rule-inset, whichever applies to gap. Resolve any percentages in inset against width.
Let result be width multiplied by 50%. Add inset to result.
Return result.

For details on how the offset is applied, see append a segment for painting.

Tests

3.4. Gap decoration overlap: The rule-overlap property

Name:	rule-overlap
Value:	row-over-column \| column-over-row
Initial:	row-over-column
Applies to:	grid containers, flex containers, and grid lanes containers
Inherited:	no
Percentages:	n/a
Computed value:	as specified
Canonical order:	per grammar
Animation type:	discrete

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;

Tests

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

Name:	column-rule-color, row-rule-color
Value:	<line-color-list> \| <auto-line-color-list>
Initial:	currentcolor
Applies to:	grid containers, flex containers, multicol containers, and grid lanes containers
Inherited:	no
Percentages:	n/a
Computed value:	as specified
Canonical order:	per grammar
Animation type:	repeatable list, see § 4.4.1 Interpolation behavior.

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

Tests

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

Name:	column-rule-style, row-rule-style
Value:	<line-style-list> \| <auto-line-style-list>
Initial:	none
Applies to:	grid containers, flex containers, multicol containers, and grid lanes containers
Inherited:	no
Percentages:	n/a
Computed value:	as specified
Canonical order:	per grammar
Animation type:	discrete

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

Tests

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

Name:	column-rule-width, row-rule-width
Value:	<line-width-list> \| <auto-line-width-list>
Initial:	medium
Applies to:	grid containers, flex containers, multicol containers, and grid lanes containers
Inherited:	no
Percentages:	n/a
Computed value:	list of absolute lengths, snapped as a border width
Canonical order:	per grammar
Animation type:	repeatable list, see § 4.4.1 Interpolation behavior.

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

Tests

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

An author might specify alternating red and blue column rules as follows:

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

To assign gap decoration values to a list of gaps using a list of values:

Replace any integer repeaters in values with their expanded-out equivalents.
If the list contains no auto repeater, then:
1. Beginning from the first item in values and the first item in gaps, assign each value to the corresponding gap. If there are fewer values than gaps, repeat beginning from the first item in values, as many times as needed.
2. End this algorithm.
values contains an auto repeater. Let leading count be the number of items in values before the auto repeater. Let trailing count be the number of items in values after the auto repeater.
Partition gaps as follows:
1. Let leading gaps contain the first leading count items in gaps.
2. Let trailing gaps contain the last trailing count items in gaps, excluding any items in leading gaps.
3. Let auto gaps contain any items in gaps that are not in either leading gaps or trailing gaps.
If leading gaps is non-empty, assign gap decoration values to leading gaps using the first leading count items in values.
If trailing gaps is non-empty, assign gap decoration values to trailing gaps using the first trailing count items in values.
If auto gaps is non-empty, assign gap decoration values to auto gaps using the list of values in the second argument of the auto repeater.

Tests

gap-decorations-011-crash.html (live test) (source)

4.4.1. Interpolation behavior

When interpolating repeat() values, or lists of values for rule-color or rule-width, the interpolation proceeds in two steps:

Expansion: Expand any integer repeater into its equivalent list of values.
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; }
}

Interpolation of the above values would result in expansion of the "from" and "to" values to create lists of equal lengths:

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

Interpolation of the above values would result in expansion of the "from" and "to" values to create lists of equal lengths:

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

Interpolation of the above values would result in expansion of the "from" and "to" values to create lists of equal lengths:

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

Interpolation of the above values would result in expansion of the "from" and "to" values to create lists of equal lengths:

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

4.4.1.1. Lists with Auto Repeaters

When either of the lists we are interpolating between (from and to) include an auto repeater:

Split each of from and to into segments, similar to how we assign gap decoration values:
1. Let leading values be the values before the auto repeater.
2. Let trailing values be the values after the auto repeater.
3. Let auto values be the values inside the auto repeater.
If only one of from or to contains an auto-repeater, we fall back to discrete interpolation.
Expand any integer repeaters on each segment.
If the length of leading values in from and leading values in to don’t match, we fall back to discrete interpolation. If the length of trailing values in from and trailing values in to don’t match, we fall back to discrete interpolation.
When both from and to contain auto-repeaters, and the length of their segments match as described above, apply repeatable list interpolation to the lists of values in each auto values.

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

Length of the leading values and trailing values across from and to match, so we can apply the repeatable list algorithm to each segment.

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

Length of the leading values and trailing values across from and to match, so we can apply the repeatable list algorithm to each segment.

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) }
}

Length of the from leading values and to leading values don’t match, so we fall back to discrete interpolation.

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

Length of the from trailing values and to trailing values don’t match, so we fall back to discrete interpolation.

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

Only from contains an auto repeater, so we fall back to discrete interpolation.

Tests

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

Name:	column-rule, row-rule
Value:	<gap-rule-list> \| <gap-auto-rule-list>
Initial:	see individual properties
Applies to:	see individual properties
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

<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. When serializing a shorthand from its corresponding longhand properties, if the longhand properties are not repeater aligned, the shorthand serializes as an empty string.

4.5.1. Longhand Properties Alignment

Let W, S and C be the values for the width, style and color longhand properties respectively. Recall that each is a list of items, where an item is either a single value or a repeat() notation.

The longhands are repeater aligned if and only if all of the following are true:

W, S and C have the same number of items.
For each item index i, W[i], S[i] and C[i] all have the same shape:
1. they are either all non-repeat values, all integer repeaters, or all auto repeaters.
2. If they are integer repeaters, the <integer> values are equal.
3. Each repeat() notation contains the same number of values.

This shorthand declaration:

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

Breaks down to the following longhand values:

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

Which serialize back to the same original shorthand value, because the longhands are repeater aligned: all three properties have the same number of items (3), and each item is a single value (not a repeater).