HTML Guides for gap

The gap property is a shorthand for row-gap and column-gap, used in CSS Grid, Flexbox, and multi-column layouts to define spacing between items or tracks. According to the CSS Box Alignment specification, the accepted values for gap are length values (px, em, rem, %, vh, etc.), the normal keyword, or the calc() function. The keyword auto — while valid for many other CSS properties like margin, width, and grid-template-columns — is simply not part of the gap property’s value grammar.

This confusion often arises because developers are accustomed to using auto for spacing in other contexts. For instance, margin: auto is a common centering technique, and auto is widely used in grid track sizing. However, the gap property serves a different purpose: it defines a fixed or computed gutter size between items, and auto has no defined meaning in that context.

Why this matters

• Standards compliance: Using an invalid value means the browser will ignore the entire gap declaration, falling back to the default value of normal (which is typically 0px in Grid and Flexbox). This can lead to unexpected layout results where items have no spacing at all.
• Cross-browser consistency: While some browsers may be lenient with invalid CSS values, others will strictly discard them. This creates inconsistent layouts across different browsers and versions.
• Maintainability: Invalid CSS values can mask the developer’s intent, making it harder for others (or your future self) to understand what spacing was desired.

How to fix it

Replace auto with a valid value for gap:

• A specific length: gap: 16px;, gap: 1rem;, gap: 0.5em;
• A percentage: gap: 2%;
• The normal keyword: gap: normal; (resolves to 0px in Flexbox and Grid)
• A calc() expression: gap: calc(1rem + 4px);
• Two values for row and column separately: gap: 16px 24px;

If you were using auto because you wanted the browser to determine the spacing dynamically, consider using a percentage value, a viewport-relative unit (vw, vh), or CSS clamp() for responsive gutters.

Examples

Incorrect: using auto as a gap value

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: auto;">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
</div>

This triggers the validation error because auto is not a valid gap value. The browser will discard the declaration entirely.

Correct: using a fixed length

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 16px;">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
</div>

Correct: using separate row and column gaps

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 12px 24px;">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
</div>

Correct: using a percentage for responsive spacing

<div style="display: flex; flex-wrap: wrap; gap: 2%;">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

Correct: using clamp() for fluid responsive gaps

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: clamp(8px, 2vw, 32px);">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
</div>

This approach gives you a gap that scales with the viewport width, bounded between 8px and 32px — a useful alternative if you were reaching for auto to get flexible spacing behavior.