[FEE-11003] CSS Subgrid
INFO
CSS Subgrid lets a nested grid element participate in its parent grid's track sizing — so sibling cards can align their internal rows and columns to the same tracks without JavaScript, fixed heights, or margin hacks.
Baseline
This feature is Baseline Widely Available. Supported in Chrome 117+, Firefox 71+, Safari 16+.
Context
CSS Grid Level 1 introduced a powerful two-dimensional layout system, but it had a deliberate limitation: grid tracks exist only on the element that declares them. A child element placed in a grid cell becomes a new independent layout context. Its own children — grandchildren of the original grid — cannot participate in the grandparent's tracks. Each nesting level defines its own isolated grid.
This limitation matters most when building card-based layouts. Consider a three-column product grid: each card contains an image, a title, a description, and a call-to-action button. The title in one card might be one line; in another, two lines. The description in one card might be short; in another, four lines. Because each card is an independent grid (or flex) container, the "Buy Now" buttons land at different vertical positions in every column. The visual rhythm is broken.
The workarounds engineers reached for before subgrid were numerous and none were elegant:
- Flexbox column with
margin-top: auto— setdisplay: flex; flex-direction: columnon the card andmargin-top: autoon the button. This pushes the button to the card's bottom edge, but it cannot align buttons across sibling cards to the same baseline — the bottom of one card and the bottom of another card are at different heights if the cards have different total heights. - Fixed
min-heightper section — give the title, description, and image areas a fixed minimum height so they all occupy the same vertical space regardless of content. This is brittle: a content change (a longer product name, a translated string, a larger image) breaks the layout silently. - JavaScript measurement — use
ResizeObserveror a one-time measurement script to read the tallest element in each row, then apply that height to all siblings. Works, but requires JavaScript before the layout is correct, costs a second layout pass, and must be re-run on every resize. - CSS Grid with
align-items: stretch— stretch-align all cards so they are the same height as the tallest sibling, then use absolute positioning or flex inside. Still cannot align internal rows across siblings.
CSS Grid Level 2 introduced the subgrid value to solve this problem at the specification level. A subgrid item opts into the parent's tracks instead of defining its own, enabling declarative cross-sibling alignment with no JavaScript and no magic values.
Scenario
You are building a product listing page. The design calls for a three-column grid of cards. Each card has four distinct sections that must align horizontally across all three columns: a product image, a product name (one or two lines), a product description (two to four lines), and a "Buy Now" button. The button must sit at the same vertical position in every column, regardless of how much text the title and description contain.
Before subgrid — the flex-column workaround:
/* Each card is a flex column */
.card {
display: flex;
flex-direction: column;
border: 1px solid #ccc;
padding: 1rem;
}
/* Push button to bottom of card */
.card button {
margin-top: auto;
}This approach keeps the button at the bottom of its own card, but cards in the same row are different heights (because the tallest card determines the row height in the parent grid). The button in the short card sits higher than the button in the tall card — no horizontal alignment across siblings.
To work around that, the engineer adds fixed minimum heights to each internal section:
.card img { min-height: 200px; }
.card h2 { min-height: 3.5rem; } /* enough for 2 lines */
.card p { min-height: 6rem; } /* enough for 4 lines */These magic values are fragile. Add a longer product name or translate the UI to German and the layout breaks again.
After subgrid — declarative track alignment:
.product-grid {
display: grid;
grid-template-columns: repeat(3, 1fr);
grid-template-rows: repeat(4, auto);
gap: 1rem;
}
.card {
display: grid;
grid-row: span 4;
grid-template-rows: subgrid;
}Each card spans four parent row tracks and maps its four children — image, title, description, button — onto those tracks. The parent grid controls the track sizing. The tallest title across all three cards determines the height of the title track; the longest description determines the description track height. Every element in the same logical row aligns to exactly the same baseline, automatically, with no fixed values and no JavaScript.
Best Practices
MUST set the subgrid item to span the parent tracks it participates in. A card with four internal rows needs
grid-row: span 4so the parent allocates four tracks for the subgrid to map to. Without the correct span, the subgrid has fewer parent tracks than children and the layout collapses unexpectedly.SHOULD use subgrid for any multi-card or multi-item layout where internal alignment across siblings matters — product cards, pricing tables, form grids, feature comparison tables, image galleries with captions.
SHOULD name parent tracks when more than three rows are involved. Named lines make it immediately clear which track corresponds to which semantic section of the card.
css.product-grid { grid-template-rows: [card-img-start] auto [card-img-end card-title-start] auto [card-title-end card-desc-start] auto [card-desc-end card-cta-start] auto [card-cta-end]; }SHOULD NOT apply subgrid when the child has fewer direct children than the parent has allocated tracks in the span. Tracks with no children in a subgrid do not collapse — they remain as empty track slots. This can introduce unexpected gaps.
MAY use subgrid on both axes simultaneously for complex aligned form layouts. A form where labels and inputs must share both column tracks (label column / input column) and row tracks (shared with adjacent sections in a multi-panel form) benefits from
grid-template-rows: subgrid; grid-template-columns: subgrid.SHOULD understand that gap on the subgrid element is ignored — the subgrid inherits its gaps from the parent grid. To change spacing within a subgrid, change the parent's
gapor userow-gap/column-gapon the parent.MAY combine subgrid with
align-selfandjustify-selfon the subgrid's children to fine-tune alignment within the inherited track.
Design Thinking
Why grid children cannot share parent tracks by default
When CSS Grid Level 1 was designed, each grid item was defined as establishing a new independent layout context for its children. This was a deliberate scope decision: Grid Level 1 focused on the relationship between a grid container and its direct children. The specification did not define any mechanism for grandchildren to participate in the grandparent's tracks.
The underlying reason is architectural. A CSS Grid's tracks are defined by the dimensions of its direct children and the explicit sizing the author specifies. Allowing grandchildren to influence track sizing would have required the specification to define a new kind of upward dependency — a child's content affecting an ancestor's track sizing — which significantly complicates the layout algorithm. Level 1 avoided this complexity entirely.
The consequence: every grid item is an opaque box from the parent grid's perspective. Whether the grid item contains a flat paragraph or a deeply nested multi-row structure, the parent grid only sees one box. This is why the "align buttons at the same row" problem cannot be solved in Grid Level 1 without external help.
How the ecosystem worked around the limitation
Four patterns emerged as industry standard before subgrid:
Flexbox column with margin-top: auto was the most common. It at least guaranteed the button touched the card's bottom edge. Combined with align-items: stretch on the parent grid (the default), all cards grew to the height of the tallest sibling, so the buttons were all at the same height — but only if the tallest card's button was also at the bottom. This worked for single-CTA cards but broke immediately when adding a second action or a badge between the description and the button.
Fixed minimum heights per section were used in production design systems, often encoded as design tokens. The design team measured the tallest expected content, added a buffer, and fixed that as a minimum. This required constant maintenance as content changed and was inherently fragile across languages and screen sizes.
JavaScript ResizeObserver equalization was the most robust pre-subgrid solution. A small utility observed each row of cards, found the tallest element in each semantic slot (title, description), and applied min-height to all siblings in that slot. Libraries like Masonry and CSS Grid polyfills included similar utilities. The cost: JavaScript must execute and complete before the layout is visually correct; during hydration in SSR applications, users see a layout flash; observers must be torn down and re-created when the DOM changes.
CSS Grid with named areas and display: contents was explored as a pure-CSS workaround. Setting display: contents on the card element makes the card's children become direct children of the parent grid, allowing them to participate in the parent's tracks directly. This works but destroys the card as a styling unit — you can no longer apply borders, backgrounds, padding, or overflow to the card element itself, because display: contents removes the box entirely.
Why subgrid is architecturally better
Subgrid solves the problem at the correct level of abstraction. The parent grid remains the authority over track sizing. The subgrid item participates in those tracks instead of fighting them. Children of the subgrid item are placed into parent tracks as if they were direct children of the parent grid for the purpose of track sizing, while remaining logically children of their parent element for all other CSS purposes (inheritance, display, position, events).
The key benefits over the workarounds:
- Declarative: the alignment relationship is expressed in CSS, not computed in JavaScript. The browser's layout engine handles it in the same pass as everything else.
- Resilient: content can change freely — longer titles, translated strings, dynamic data — and the layout adapts automatically because track sizing is driven by actual content.
- Composable: a card that uses subgrid is still a normal DOM element. It can have borders, backgrounds, padding, scroll, and overflow.
display: contentsworkarounds sacrifice this. - No fixed values: no magic
min-heightconstants to maintain. No design tokens that need updating when content strategy changes.
The broader architectural lesson is that subgrid moves alignment responsibility from child to parent, which is where it belongs. The parent grid knows the semantic structure of its columns and rows. The children (cards) know their internal structure. Subgrid provides the bridge that lets both levels describe what they know without either needing to know the other's measurements.
Example
A three-column product card grid. Each card contains a product image, a product name (one to two lines), a description (two to four lines), and a "Buy Now" button. Without subgrid, the buttons are at different vertical positions depending on description length. With subgrid, all four internal elements align across all three cards.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>CSS Subgrid — Product Card Grid</title>
<style>
/* ── Reset ────────────────────────────────────────────── */
*, *::before, *::after { box-sizing: border-box; }
body {
font-family: system-ui, sans-serif;
padding: 2rem;
background: #f9fafb;
}
/* ── Parent grid ───────────────────────────────────────── */
.product-grid {
display: grid;
grid-template-columns: repeat(3, 1fr);
/*
4 implicit rows per card:
1. product image
2. product name
3. product description
4. call-to-action button
*/
grid-template-rows: repeat(4, auto);
gap: 1.5rem;
list-style: none;
padding: 0;
margin: 0;
}
/* ── Card — subgrid item ────────────────────────────────── */
.card {
display: grid;
/*
Span all 4 parent row tracks.
Without this span, the subgrid would have no parent tracks
to map to and the layout would collapse.
*/
grid-row: span 4;
/*
Participate in the parent's row tracks instead of
defining an independent grid. The parent controls sizing.
*/
grid-template-rows: subgrid;
background: #ffffff;
border: 1px solid #e5e7eb;
border-radius: 0.75rem;
overflow: hidden;
gap: 0; /* subgrid ignores this; parent gap controls row spacing */
}
/* ── Card children — placed into parent tracks ─────────── */
.card img {
width: 100%;
aspect-ratio: 4 / 3;
object-fit: cover;
display: block;
}
.card h2 {
margin: 0;
padding: 1rem 1rem 0;
font-size: 1rem;
font-weight: 600;
line-height: 1.4;
}
.card p {
margin: 0;
padding: 0.5rem 1rem 0;
font-size: 0.875rem;
color: #6b7280;
line-height: 1.5;
}
.card button {
/* align-self: end pushes the button to the bottom of its track */
align-self: end;
margin: 1rem;
padding: 0.625rem 1.25rem;
background: #2563eb;
color: #fff;
border: none;
border-radius: 0.5rem;
font-size: 0.875rem;
font-weight: 500;
cursor: pointer;
}
.card button:hover {
background: #1d4ed8;
}
</style>
</head>
<body>
<ul class="product-grid">
<li class="card">
<!--
Background colour simulates an image placeholder.
Replace src with a real image in production.
-->
<img
src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='300'%3E%3Crect width='400' height='300' fill='%23c7d2fe'/%3E%3Ctext x='50%25' y='50%25' dominant-baseline='middle' text-anchor='middle' fill='%234f46e5' font-size='18' font-family='system-ui'%3EProduct A%3C/text%3E%3C/svg%3E"
alt="Product A"
/>
<h2>Product A</h2>
<p>Short description.</p>
<button>Buy Now</button>
</li>
<li class="card">
<img
src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='300'%3E%3Crect width='400' height='300' fill='%23bbf7d0'/%3E%3Ctext x='50%25' y='50%25' dominant-baseline='middle' text-anchor='middle' fill='%2315803d' font-size='18' font-family='system-ui'%3EProduct B%3C/text%3E%3C/svg%3E"
alt="Product B — Extended Edition"
/>
<h2>Product B — Extended Edition</h2>
<p>A much longer description that wraps onto multiple lines easily, giving this card more vertical content than its siblings.</p>
<button>Buy Now</button>
</li>
<li class="card">
<img
src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='300'%3E%3Crect width='400' height='300' fill='%23fde68a'/%3E%3Ctext x='50%25' y='50%25' dominant-baseline='middle' text-anchor='middle' fill='%23b45309' font-size='18' font-family='system-ui'%3EProduct C%3C/text%3E%3C/svg%3E"
alt="Product C"
/>
<h2>C</h2>
<p>Medium length description here.</p>
<button>Buy Now</button>
</li>
</ul>
<!--
What you should see:
All three "Buy Now" buttons sit on the same horizontal baseline,
regardless of how long each card's title and description are.
The image row, name row, description row, and button row all align
perfectly across all three cards — with zero JavaScript and no
fixed min-height values.
-->
</body>
</html>Minimal code — the essential subgrid pattern
If the example above is too verbose, here is the minimal pattern to memorise:
/* Parent: declare a grid with N rows per item */
.product-grid {
display: grid;
grid-template-columns: repeat(3, 1fr);
grid-template-rows: repeat(4, auto); /* 4 rows per card */
gap: 1rem;
}
/* Child: opt into the parent's rows */
.card {
display: grid;
grid-row: span 4; /* span the same N rows */
grid-template-rows: subgrid; /* use parent tracks, not own */
}The two key lines on .card are grid-row: span 4 and grid-template-rows: subgrid. They always appear together. The span tells the parent how many tracks to allocate; the subgrid value tells the card to use those allocated tracks for its own children.
Named tracks variant
When the number of rows is more than three, naming the tracks improves maintainability:
.product-grid {
display: grid;
grid-template-columns: repeat(3, 1fr);
grid-template-rows:
[card-img-start] auto
[card-img-end card-title-start] auto
[card-title-end card-desc-start] auto
[card-desc-end card-cta-start] auto
[card-cta-end];
gap: 1rem;
}
.card {
display: grid;
/* Named lines are inherited from the parent into the subgrid */
grid-row: card-img-start / card-cta-end;
grid-template-rows: subgrid;
}Named lines from the parent are available inside the subgrid. A child in the subgrid can use grid-row: card-title-start / card-title-end to pin itself to the title track explicitly — useful when a card variant needs to skip the image track.
Both axes simultaneously
For a form layout where labels and inputs must share column tracks and also align row-by-row with an adjacent summary panel:
.form-layout {
display: grid;
grid-template-columns: [label-start] 120px [label-end input-start] 1fr [input-end];
grid-template-rows: repeat(5, auto);
gap: 0.75rem;
}
.form-section {
display: grid;
grid-column: 1 / -1; /* span all columns */
grid-row: span 3; /* span 3 parent rows */
grid-template-columns: subgrid; /* inherit label + input columns */
grid-template-rows: subgrid; /* inherit row tracks */
}Both axes can subgrid simultaneously. The grid-template-columns: subgrid on .form-section inherits the named label and input columns. The grid-template-rows: subgrid inherits the row tracks. Children of .form-section are placed into parent tracks on both axes.
Browser Support
| Browser | First version | Notes |
|---|---|---|
| Chrome | 117 | Shipped September 2023 |
| Firefox | 71 | Shipped December 2019 — first browser to ship subgrid |
| Safari | 16 | Shipped September 2022 |
| Edge | 117 | Chromium-based; matches Chrome |
Firefox shipped subgrid in December 2019, nearly four years before Chrome. Safari shipped in September 2022. Chrome and Edge shipped in September 2023, achieving cross-browser availability.
Baseline Widely Available as of 2024. Global coverage exceeds 95%. MDN compatibility data: CSS subgrid browser compatibility.
No @supports guard is required for production use targeting modern browsers. For applications that must support browsers older than the above versions, the safe fallback is the flexbox-column pattern with margin-top: auto on the CTA:
/* Fallback: flexbox column with button at bottom */
.card {
display: flex;
flex-direction: column;
}
.card button {
margin-top: auto;
}
/* Enhancement: subgrid alignment when supported */
@supports (grid-template-rows: subgrid) {
.product-grid {
display: grid;
grid-template-columns: repeat(3, 1fr);
grid-template-rows: repeat(4, auto);
gap: 1rem;
}
.card {
display: grid;
grid-row: span 4;
grid-template-rows: subgrid;
}
}Internal References
- FEE-11002 Container Queries — Size & Style — Container queries and subgrid are complementary responsive layout tools. Container queries let a component respond to its available space; subgrid lets components in the same grid share track sizing. A card grid using subgrid for internal alignment and container queries for layout switching (vertical vs. horizontal card orientation) covers both axes of responsive card design.