When setting up a responsive CSS Grid, you often end up with unexpected empty gaps at the end of a row or grid items refusing to stretch as the viewport widens. This usually boils down to a single keyword choice inside your repeat() function: auto-fit versus auto-fill. Using the wrong one breaks the fluid layout, forcing you to rely on unnecessary media queries just to fix the alignment.

Keyword Core Behavior Extra Space Handling Best Used For
auto-fit Collapses empty tracks Stretches existing items to fill the row Fluid product cards, flexible content
auto-fill Retains empty tracks Leaves blank spaces (grid slots) open Static image galleries, avatar grids

What Is the Difference Between auto-fit and auto-fill?

Up to a certain viewport width, both keywords produce identical results by wrapping columns neatly. The exact moment they diverge is when the screen becomes wide enough to fit an additional column, but you do not have any extra grid items to put in it.

Diagram comparing auto-fill, which keeps empty grid tracks, with auto-fit, which collapses empty tracks and stretches items to fill the row.
auto-fill keeps unused columns as empty tracks, while auto-fit collapses them so the remaining items stretch to fill the space.

How auto-fill Works (Implicit Columns)

The auto-fill keyword tells the browser to cram as many columns into the row as mathematically possible. If the viewport expands and there is enough room for another column based on your minimum width limit, it creates an invisible, empty column.

  • The empty column reserves physical space in the layout.
  • Existing grid items stay at their designated size.
  • The grid structure remains rigid, leaving a visible gap at the end of the row.

How auto-fit Works (Collapsing Empty Tracks)

Instead of preserving empty grid tracks, auto-fit completely collapses them down to zero pixels. Once the empty tracks are collapsed, the browser takes the remaining available space and distributes it equally among the actual grid items.

  • Empty columns lose their footprint entirely.
  • Existing items stretch and expand to occupy the newly freed space.
  • The row always appears perfectly flush and filled, regardless of item count.

Real-World Use Cases

Choosing between these two depends entirely on the UI behavior you want to achieve when user-generated content fluctuates.

When to Use auto-fit (Product Cards & Fluid Grids)

E-commerce layouts and blog archive pages benefit the most from auto-fit. If a category page only returns two products instead of four, you want those two cards to scale up and fill the container rather than looking broken or incomplete. This creates a visually balanced, highly responsive grid without writing separate CSS rules for different item counts.

When to Use auto-fill (Image Galleries & Fixed Slots)

User profile dashboards or strict image galleries require auto-fill. If you are displaying user avatars or a calendar interface, you need the grid cells to remain fixed in size and position. If only three avatars load in a five-column layout, stretching them to fill the row ruins the visual hierarchy. Maintaining that empty, structured space keeps the design predictable.

Advertisement

How minmax() Works with Auto-Placement

These auto-placement keywords only trigger their responsive magic when paired with the minmax() function, which is also the core formula behind collapsing a 4-column layout down to one on mobile. A static pixel value prevents the browser from calculating flexible track sizes.

/* The standard responsive grid formula */
.grid-container {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
  gap: 1.5rem;
}

Setting 250px ensures columns never shrink beyond readability on mobile devices. The 1fr maximum allows the browser to distribute any remaining fractional space gracefully. If the screen is 800px wide, three 250px items fit perfectly, with the remaining 50px distributed evenly across the three columns thanks to the fractional unit.

Common Mistakes When Using repeat()

Many developers accidentally combine explicit column counts with auto keywords, breaking the layout engine entirely.

  • Mixing exact counts with auto: writing repeat(3, auto-fit) is invalid CSS and causes the declaration to fail silently in most modern browsers.
  • Forgetting the fractional maximum: setting minmax(200px, 400px) instead of 1fr creates rigid upper limits. This eventually causes the grid container to overflow or leave unwanted margins on ultra-wide monitors.
  • Ignoring content constraints: if a child element contains a massive, unscaled image, it forces the minmax() base width to expand unnecessarily, breaking the wrap behavior. Always ensure grid items have max-width: 100% applied.