Stop Guessing: How to Master CSS Grid Auto-Fill for Dynamic Content Layouts

You are building a page that pulls in products from a database. Some days you have three items. Other days you have thirty. You want them to flow into a grid without gaps, without extra markup, and without a line of JavaScript. This is exactly the problem CSS Grid auto-fill solves.

Understanding How Auto-Fill Works

CSS Grid has two main ways to handle items that don’t fit into an explicit grid. The first is grid-auto-flow: row, which is the default. Items fill left to right, then drop to the next row. The second is grid-auto-flow: column, which fills top to bottom first. The third option, grid-auto-flow: dense, is where the real magic happens for dynamic content.

When you combine grid-auto-flow with auto-fill (the auto-fill keyword in the repeat() function), you tell the browser: “figure out the best column count based on the minimum size I give you.” This means your grid can go from two columns on a phone to six columns on a desktop without a single breakpoint.

The Core Syntax

.grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
  grid-auto-flow: dense;
}

That single line does the heavy lifting. The browser calculates how many columns of at least 250 pixels fit in the available space. Any leftover space is distributed evenly using 1fr. If the container is 800 pixels wide, you get three columns. At 500 pixels, you get two. At 300 pixels, you get one. No media queries needed.

A Practical Process for Setting Up Auto-Fill

Follow these steps to add auto-fill to any project.

1. Define your minimum column size. Look at your content. A card with an image and two lines of text might need 220 pixels. A product tile with a price, rating, and button might need 280. Pick the smallest width that still looks good.

2. Write the grid-template-columns rule. Use repeat(auto-fill, minmax(YOUR_MIN, 1fr)). The 1fr makes columns grow equally if there is extra space.

3. Set grid-auto-flow to dense. This tells the browser to fill any empty cells before creating new rows. It prevents weird gaps when items have different heights.

4. Add a max-width to the container. Without one, the grid could stretch across the whole viewport on ultra-wide screens, making columns too wide to read. A max-width of 1200 or 1400 pixels is a safe bet.

5. Test with different amounts of content. Add two items, then add twenty. Check that the layout adjusts smoothly. If columns look cramped, bump up the minimum size. If they look too sparse, lower it.

Common Mistakes and How to Avoid Them

Even experienced developers hit snags with auto-fill. Here is a table of the most frequent issues and their fixes.

Mistake	What Happens	The Fix
Using auto-fill without minmax()	The grid may collapse to one column or overflow	Always pair auto-fill with minmax(MIN, 1fr)
Forgetting grid-auto-flow: dense	Items may leave gaps when heights vary	Add grid-auto-flow: dense; to the grid container
Setting a fixed height on grid items	Items cannot grow to fill the row evenly	Use min-height instead, or let content determine height
Applying auto-fill to the wrong container	The grid behaves like a normal block element	Make sure display: grid is on the parent of the items
Not accounting for gaps and padding	Columns appear smaller than expected	Subtract gap and padding from your minimum column value

When Auto-Fill Shines vs. When to Use Something Else

Auto-fill is not the right tool for every layout. Here is how to decide.

• Use auto-fill when: you have an unknown number of items, all items are roughly the same size, and you want the layout to adapt without breakpoints. Product catalogs, image galleries, blog post grids, and dashboard widgets are perfect candidates.

• Use explicit columns when: you need a specific layout that does not change. A two-column article with a sidebar should stay two columns regardless of screen size. In that case, write grid-template-columns: 1fr 300px; and use a media query for smaller screens.

• Use Flexbox when: items have different widths or you need them to wrap in one direction only. Flexbox is better for toolbars, navigation menus, and inline form elements.

Expert advice: If your content includes items with wildly different heights, consider adding a min-height to each item. This prevents short items from creating large gaps when grid-auto-flow: dense tries to fill them. A consistent minimum height makes the dense algorithm work much more predictably.

Troubleshooting Auto-Fill Layouts

Sometimes the grid does not behave the way you expected. Here are three scenarios and how to fix them.

Scenario 1: Columns are too narrow.
Your minimum is 200 pixels, but on a 600 pixel screen you get four columns of 150 pixels each. This happens when padding, borders, or gaps are not accounted for. Check the container’s padding, gap, and box-sizing. Add box-sizing: border-box to your grid items. Then increase your minimum to compensate.

Scenario 2: Items overflow the grid.
An item with a very long word or an unbreakable image can push the column wider than expected. Add overflow-wrap: break-word to the item, or set a max-width: 100% on images inside the grid.

Scenario 3: Auto-fill is not working in older browsers.
The auto-fill keyword is well supported in modern browsers as of 2026, but if you need to support Internet Explorer or very old versions of Safari, provide a fallback. Use @supports or a @media query as a backup.

.grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
}

@supports not (grid-template-columns: repeat(auto-fill, minmax(250px, 1fr))) {
  .grid {
    grid-template-columns: repeat(3, 1fr);
  }
}

Combining Auto-Fill with Other CSS Grid Features

Auto-fill works well with other grid properties to create more complex layouts.

• Add a sidebar. Use grid-template-columns: 280px repeat(auto-fill, minmax(200px, 1fr));. This gives you a fixed sidebar on the left and an auto-filling content area on the right. On small screens, use a media query to stack them.

• Use subgrids. If one of your auto-filled items needs its own internal grid, apply display: grid to that item. This is called a subgrid, and it is a clean way to manage complex content inside a dynamic layout. For more on this technique, read our guide on why CSS subgrid is your secret weapon for complex layouts in 2026.

• Nest auto-fill inside a larger grid. You can place an auto-fill grid inside a specific cell of a manually defined grid. This is useful for dashboards where one section has a fixed chart and another has a dynamic list of recent items.

A Checklist for Your Next Auto-Fill Project

Before you ship your layout, run through this list.

• Container has display: grid and a defined max-width
• grid-template-columns uses repeat(auto-fill, minmax(X, 1fr)) where X is your minimum column width
• grid-auto-flow is set to dense
• All grid items have box-sizing: border-box
• Images inside items have max-width: 100%
• Long text has overflow-wrap: break-word
• The layout works with 1 item, 5 items, and 30 items
• The layout works on a 320 pixel phone, a 768 pixel tablet, and a 1440 pixel desktop

Putting Auto-Fill to Work in a Real Example

Let us build a simple product grid. Each product has an image, a title, and a price. The minimum comfortable width for this card is 240 pixels.

.product-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
  grid-auto-flow: dense;
  gap: 1.5rem;
  max-width: 1200px;
  margin: 0 auto;
  padding: 1rem;
}

.product-card {
  box-sizing: border-box;
  border: 1px solid #ddd;
  border-radius: 8px;
  padding: 1rem;
}

.product-card img {
  max-width: 100%;
  height: auto;
}

That is all the CSS you need. The grid handles everything else. Add ten products, and you get four columns on a desktop. Add two, and they sit centered in two columns. The layout never breaks, and you never touch the code again.

If you are working with WordPress and want to apply this to your theme, check out our post on 7 CSS Grid layout patterns every WordPress developer should know. It covers how to integrate auto-fill with the Block Editor and custom post type archives.

Fixing the Most Frustrating Auto-Fill Bug

There is one bug that trips up almost everyone. You set up auto-fill, it works perfectly in your test file, but when you paste it into your production site, the grid collapses into a single column. The culprit is almost always a parent container that does not have a defined width. If the grid’s parent has width: 100% but no max-width and no explicit width on its own parent, the browser cannot calculate the available space correctly.

The fix is simple. Give the grid’s direct parent a width. If it is a <section> or a <div>, add width: 100% or max-width: 1200px. The grid needs a concrete number to work with, even if that number is a percentage.

Your Turn to Stop Guessing

You now have a clear path to using CSS Grid auto-fill in your projects. Start with one layout. A simple card grid for a portfolio or a product listing. Apply the process from this guide. Test it with different amounts of content. Once you see how smoothly it adapts, you will wonder why you ever wrote media queries for grid columns.

The best part is that this technique works today. No JavaScript, no build tools, no extra classes. Just clean, modern CSS that handles the unpredictable nature of dynamic content. Give it a try on your next project. Your future self will thank you when a client adds five more items and the layout does not break.