CSS Subgrid Explained: Align Nested Layouts Perfectly (With Examples)
On this page
- The problem subgrid solves
- The fix: grid-template-rows: subgrid
- How subgrid works
- Example 2: forms with perfectly aligned labels
- Example 3: page layout with full-width sections
- Browser support and fallbacks
- Subgrid in React and component libraries
- Common mistakes
- When not to use subgrid
- Example 4: a pricing table that lines up
- Debugging subgrids in DevTools
- Frequently asked questions
- Oh hi there 👋It’s nice to meet you.
- Sign up to receive awesome content in your inbox.
CSS Grid made two-dimensional layouts easy, but it had one frustrating limit: a grid only controls its direct children. Anything nested inside a grid item had no idea where the parent’s rows and columns were. The classic symptom is a row of product cards where the titles have different lengths, so the descriptions start at different heights and the “Add to cart” buttons are scattered up and down. Subgrid fixes this. A nested element can now adopt its parent’s grid tracks, so content inside separate cards lines up as if it were in one big table.
The problem subgrid solves
<div class="cards">
<article class="card">
<h3>Wireless Keyboard</h3>
<p>Quiet keys, three device pairing.</p>
<button>Add to cart</button>
</article>
<article class="card">
<h3>Ergonomic Vertical Mouse With Adjustable DPI</h3>
<p>Reduces wrist strain during long sessions at the desk.</p>
<button>Add to cart</button>
</article>
</div>
.cards {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
gap: 24px;
}
The cards sit neatly in columns, but inside each card the title, text and button just stack. The second card’s long title pushes its description down, so the descriptions and buttons don’t line up across the row. Before subgrid, developers fixed this with fixed heights, which break when text changes, or JavaScript that measured and equalized heights.
The fix: grid-template-rows: subgrid
.cards {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
grid-auto-rows: auto; /* rows created as needed */
gap: 24px;
}
.card {
display: grid;
grid-row: span 3; /* each card covers three parent rows */
grid-template-rows: subgrid; /* …and uses those rows for its own children */
gap: 8px;
padding: 16px;
border: 1px solid #dde2ea;
border-radius: 12px;
}
.card button { align-self: end; }
Two lines do the work. grid-row: span 3 makes each card occupy three rows of the parent grid, one each for the title, the text and the button. grid-template-rows: subgrid tells the card to use those parent rows instead of creating its own. Now every title in a row of cards shares one row track, which grows to fit the longest title. The descriptions start at the same height, and the buttons line up at the bottom.
The number in span must match how many children you want aligned. If a card has an image, a title, a price, a description and a button, use span 5.
How subgrid works
- Subgrid works per axis. Use
grid-template-rows: subgrid,grid-template-columns: subgrid, or both. - The subgrid item must itself be
display: gridand must span the tracks it wants to inherit. - The subgrid inherits the parent’s gap by default, but can override it with its own
gap, as the card example does. - Line names from the parent grid are available inside the subgrid, and the subgrid can add its own.
- Content inside the subgrid contributes to the size of the shared tracks. That is why the longest title in a row determines the height of the title track for every card in that row.
Example 2: forms with perfectly aligned labels
Forms often wrap each label and input in a container for spacing and error messages. Without subgrid, labels of different lengths make the inputs start at different positions. With subgrid, all labels share one column:
<form class="form">
<div class="field"><label for="n">Name</label><input id="n"></div>
<div class="field"><label for="e">Email address</label><input id="e" type="email"></div>
<div class="field"><label for="p">Phone (optional)</label><input id="p" type="tel"></div>
</form>
.form {
display: grid;
grid-template-columns: max-content 1fr;
gap: 12px 16px;
}
.field {
grid-column: 1 / -1; /* span both columns */
display: grid;
grid-template-columns: subgrid; /* label in column 1, input in column 2 */
align-items: center;
}
@media (max-width: 480px) {
.form { grid-template-columns: 1fr; } /* stack on small screens */
}
The first column becomes exactly as wide as the longest label, and every input starts at the same line. You keep the wrapper element for spacing and validation messages, which is good for accessibility, without breaking the alignment.
Example 3: page layout with full-width sections
A common page design has text in a readable centered column, but some sections, such as images or banners, stretch to the edges. Named grid lines plus subgrid make this clean:
.page {
display: grid;
grid-template-columns:
[full-start] minmax(16px, 1fr)
[content-start] minmax(0, 720px) [content-end]
minmax(16px, 1fr) [full-end];
}
.page > * { grid-column: content; } /* default: centered column */
.page > .full-bleed { grid-column: full; } /* edge to edge */
.feature {
grid-column: full;
display: grid;
grid-template-columns: subgrid; /* inherit the page's lines */
background: #f2f4f7;
}
.feature > * { grid-column: content; } /* contents stay aligned with the article text */
The .feature section’s background spans the full width, while its text lines up exactly with the article text above and below, because it uses the same column lines through subgrid.
Browser support and fallbacks
Subgrid works in all current versions of Chrome, Edge, Firefox and Safari. Support arrived in Firefox first, then Safari, and Chromium-based browsers added it in 2023, so most users today have it. If you need to support older browsers, use @supports to provide a reasonable fallback:
.card {
display: flex;
flex-direction: column;
}
.card button { margin-top: auto; } /* fallback: buttons pinned to the bottom */
@supports (grid-template-rows: subgrid) {
.card {
display: grid;
grid-row: span 3;
grid-template-rows: subgrid;
}
}
The flexbox fallback at least aligns the buttons at the bottom of equal-height cards. Browsers that support subgrid get full alignment of every part.
Subgrid in React and component libraries
Subgrid fits component-based apps well, because a card component doesn’t need to know about its neighbors. The parent decides the grid, and the card simply declares how many rows it spans and that it uses a subgrid. One practical tip: let the parent set the span through a CSS variable, so the same card component works in different layouts:
.card {
display: grid;
grid-row: span var(--card-rows, 3);
grid-template-rows: subgrid;
}
/* a layout where cards also show an image and a price */
.shop .cards { --card-rows: 5; }
Design tokens and variables like this are covered in CSS variables and theming.
Common mistakes
- Forgetting the span. Without
grid-row: span N, the item covers only one parent row, so the subgrid has a single track and nothing aligns. - Span doesn’t match the children. If a card has four children but spans three rows, the extra child creates an implicit row inside the card that isn’t shared with other cards.
- Applying subgrid to a non-grid item. The element must have
display: gridas well assubgrid. - Wrapper elements in between. Subgrid only passes tracks to direct children of the subgrid item. If title and text are wrapped in an extra
div, that wrapper needs to be a subgrid too, or should be removed.display: contentscan flatten a wrapper, but test it, as it can affect accessibility in some cases. - Mixing gaps unintentionally. The subgrid inherits the parent gap unless you set its own. Set
gapon the subgrid explicitly when you want tighter spacing inside cards.
When not to use subgrid
If items don’t need to align with each other, a normal nested grid or flexbox is simpler and easier to read. Subgrid is the right tool specifically when content inside separate items should line up across those items: cards, forms, pricing tables, timelines and article layouts with aligned sections.
Example 4: a pricing table that lines up
Pricing tables are another place where alignment matters. Each plan is a separate card for design and accessibility reasons, yet visitors compare them feature by feature, so the price, the feature list and the button should sit on the same lines across all plans:
.plans {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
gap: 20px;
}
.plan {
display: grid;
grid-row: span 4; /* name, price, features, button */
grid-template-rows: subgrid;
gap: 12px;
padding: 24px;
border: 1px solid #dde2ea;
border-radius: 16px;
}
.plan.featured { border: 2px solid #cb4154; }
Even when one plan has a longer feature list or a “Most popular” label in its name, every price sits on the same line and every button aligns at the bottom. Visitors can scan across plans instantly, which is exactly what a pricing page needs.
Debugging subgrids in DevTools
Browser developer tools show grid lines on the page. In Chrome and Edge, open the Elements panel, find the element with display: grid and click the small “grid” badge next to it. Firefox has an excellent grid inspector in its Layout panel. Turn on the overlay for both the parent grid and the subgrid: you will see the subgrid’s tracks line up exactly with its parent’s, which makes span mistakes obvious at a glance.
Frequently asked questions
Is subgrid supported in all browsers?
Yes, all current versions of the major browsers support it. Use @supports (grid-template-rows: subgrid) if you need a fallback for older browsers.
Can I use subgrid for rows and columns at the same time?
Yes. Set both grid-template-columns: subgrid and grid-template-rows: subgrid on an item that spans several rows and columns of its parent.
Does subgrid replace flexbox?
No. Flexbox remains ideal for one-dimensional layouts such as toolbars and navigation. Subgrid solves alignment across nested grid items, which flexbox can’t do.
Does a subgrid have its own gap?
By default it uses the parent grid’s gap, but you can set a different gap on the subgrid item to override it.



