gap

The gap CSS shorthand property sets the gaps (also called gutters) between rows and columns. This property applies to multi-column, flex, and grid containers.

Try it

Constituent properties

This property is a shorthand for the following CSS properties:

Syntax

css
/* One <length> value */
gap: 20px;
gap: 1em;
gap: 3vmin;
gap: 0.5cm;

/* One <percentage> value */
gap: 16%;
gap: 100%;

/* Two <length> values */
gap: 20px 10px;
gap: 1em 0.5em;
gap: 3vmin 2vmax;
gap: 0.5cm 2mm;

/* One or two <percentage> values */
gap: 16% 100%;
gap: 21px 82%;

/* calc() values */
gap: calc(10% + 20px);
gap: calc(20px + 10%) calc(10% - 5px);

/* Global values */
gap: inherit;
gap: initial;
gap: revert;
gap: revert-layer;
gap: unset;

Values

This property is specified as a value for <'row-gap'>, followed optionally by a value for <'column-gap'>. If <'column-gap'> is omitted, it is set to the same value as <'row-gap'>. Both <'row-gap'> and <'column-gap'> can each be specified as a <length> or a <percentage>.

<length>

Specifies the width of the gutter separating columns, flex items, flex lines, and grid lines.

<percentage>

Specifies the width of the gutter separating columns, flex items, flex lines, and grid lines relative to the dimension of the element.

Description

This property defines gaps between columns in CSS multi-column layout, between flex items and flex lines in CSS flexible box layout, and between rows and columns in CSS grid layout.

The generated gaps create empty spaces that have the width or height of the gap's specified size, much like an empty item or track. The visible space between elements may differ from the provided gap value because margins, padding, and distributed alignment may increase the separation between elements beyond what is determined by gap.

In grid layout, the first value defines the gutter between rows, and the second defines the gutter between columns. In both grid and flex layouts, if only one value is included, that value is used for both dimensions.

With flex containers, whether the first value is the gap between flex items or between flex lines depends on the direction. Flex items are laid out in either rows or columns depending on the value of the flex-direction property. For rows (row (the default) or row-reverse), the first value defines the gap between flex lines, and the second value defines the gap between items within each line. For columns (column or column-reverse), the first value defines the gap between flex items within a flex line, and the second value defines the gaps between each flex line.

In multi-column containers, the first value defines the gap between columns. A dividing line can be added to the otherwise "empty space" by using the column-rule-style property or column-rule shorthand.

Percentage gap values are always calculated against the content box size of the container element. The behavior is well-defined and consistent across layout modes when the container size is definite. As these three layout modes (multi-column, flex, and grid) treat cyclic percentage sizes differently, gap also does so. In grid layout, cyclic percentage sizes resolve against zero for determining intrinsic size contributions but resolve against the element's content box when laying out the contents. Two examples below demonstrate percentage gap values with explicit container size and implicit container size in the examples section.

Early versions of the specification called this property grid-gap, and to maintain compatibility with legacy websites, browsers still accept grid-gap as an alias for gap.

Formal definition

Initial valueas each of the properties of the shorthand:
Applies tomulti-column elements, flex containers, grid containers
Inheritedno
Computed valueas each of the properties of the shorthand:
  • row-gap: as specified, with <length>s made absolute, and normal computing to zero except on multi-column elements
  • column-gap: as specified, with <length>s made absolute, and normal computing to zero except on multi-column elements
Animation typeas each of the properties of the shorthand:

Formal syntax

gap = 
<'row-gap'> <'column-gap'>?

<row-gap> =
normal |
<length-percentage [0,∞]>

<column-gap> =
normal |
<length-percentage [0,∞]>

<length-percentage> =
<length> |
<percentage>

Examples

Flex layout

HTML

html
<div id="flexbox">
  <div></div>
  <div></div>
  <div></div>
  <div></div>
  <div></div>
  <div></div>
</div>

CSS

css
#flexbox {
  display: flex;
  flex-wrap: wrap;
  width: 300px;
  gap: 20px 5px;
}

#flexbox > div {
  border: 1px solid green;
  background-color: lime;
  flex: 1 1 auto;
  width: 100px;
  height: 50px;
}

Result

Grid layout

HTML

html
<div id="grid">
  <div></div>
  <div></div>
  <div></div>
  <div></div>
  <div></div>
  <div></div>
  <div></div>
  <div></div>
  <div></div>
</div>

CSS

css
#grid {
  display: grid;
  height: 200px;
  grid-template: repeat(3, 1fr) / repeat(3, 1fr);
  gap: 20px 5px;
}

#grid > div {
  border: 1px solid green;
  background-color: lime;
}

Result

Multi-column layout

HTML

html
<p class="content-box">
  This is some multi-column text with a 40px column gap created with the CSS
  <code>gap</code> property. Don't you think that's fun and exciting? I sure do!
</p>

CSS

css
.content-box {
  column-count: 3;
  gap: 40px;
}

Result

Percentage gap value and explicit container size

If the container has a fixed size set, then gap percentage value calculations are based on the size of the container. Thus, gap behavior is consistent across all layouts. In the following example, there are two containers, one with a grid layout and the other with a flex layout. The containers have five red 20x20px children. Both containers are explicitly set to 200px high using height: 200px and the gap is set with gap: 12.5% 0.

html
<span>Grid</span>
<div id="grid">
  <div>1</div>
  <div>2</div>
  <div>3</div>
  <div>4</div>
  <div>5</div>
</div>
<span>Flex</span>
<div id="flex">
  <div>1</div>
  <div>2</div>
  <div>3</div>
  <div>4</div>
  <div>5</div>
</div>
css
#grid {
  display: inline-grid;
  height: 200px;
  gap: 12.5% 0;
}

#flex {
  display: inline-flex;
  height: 200px;
  gap: 12.5% 0;
}

#grid > div,
#flex > div {
  background-color: coral;
  width: 20px;
  height: 20px;
}

Now inspect the grid and flex elements using Inspector tab in Web Developer Tools. In order to see the actual gaps hover mouse over <div id="grid"> and <div id="flex"> tags in the inspector. You will notice that the gap is the same in both cases which is 25px.

Percentage gap value and implicit container size

If size is not explicitly set on the container, then the percentage gap behaves differently in case of grid and flex layouts. In the following example the containers don't have height explicitly set.

In case of the grid layout, percentage gap doesn't contribute to the actual height of the grid. The container's height is calculated using 0px gap, so the actual height turns out to be 100px (20px x 5). Then the actual percentage gap is calculated using the content box's height, the gap turns out to be 12.5px (100px x 12.5%). The gap is applied just before rendering. Thus the grid remains 100px high but it overflows due to the percentage gap added later just before rendering.

In case of the flex layout, the percentage gap always results in zero value.

Specifications

Specification
CSS Box Alignment Module Level 3
# gap-shorthand

Browser compatibility

BCD tables only load in the browser

See also