8000 csswg-drafts/css-grid-1/Overview.bs at ce3d9a9778531d90961012e8f634b936e8b8c47d · w3c/csswg-drafts · GitHub
Skip to content
7FFF

Overview.bs

Latest commit

 

History

History
4660 lines (3921 loc) · 204 KB

Overview.bs

File metadata and controls

4660 lines (3921 loc) · 204 KB
<pre class='metadata'>
Title: CSS Grid Layout Module Level 1
Status: ED
Work Status: Testing
Shortname: css-grid
Level: 1
Group: csswg
ED: https://drafts.csswg.org/css-grid/
TR: https://www.w3.org/TR/css-grid-1/
Previous version: https://www.w3.org/TR/2016/WD-css-grid-1-20160519/
Previous version: https://www.w3.org/TR/2015/WD-css-grid-1-20150917/
Previous version: https://www.w3.org/TR/2015/WD-css-grid-1-20150806/
Previous version: https://www.w3.org/TR/2015/WD-css-grid-1-20150317/
Previous version: https://www.w3.org/TR/2014/WD-css-grid-1-20140513/
Previous version: https://www.w3.org/TR/2014/WD-css-grid-1-20140123/
Previous version: https://www.w3.org/TR/2013/WD-css3-grid-layout-20130402/
Previous version: https://www.w3.org/TR/2012/WD-css3-grid-layout-20121106/
Editor: Tab Atkins Jr., Google, http://www.xanthir.com/contact/, w3cid 42199
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Rossen Atanassov, Microsoft, ratan@microsoft.com, w3cid 49885
Former editor: Alex Mogilevsky, Microsoft Corporation, alexmog@microsoft.com
Former editor: Phil Cupp, Microsoft Corporation, pcupp@microsoft.com
Issue Tracking: Disposition of Comments https://drafts.csswg.org/css-grid-1/issues
Abstract: This CSS module defines a two-dimensional grid-based layout system, optimized for user interface design. In the grid layout model, the children of a grid container can be positioned into arbitrary slots in a predefined flexible or fixed-size layout grid.
Ignored Terms: containing block, <positive-integer>, <ident>, auto, grid-*-start, grid-*-end, flex factor, flex factors, block formatting context, grid-auto-position, min size property, max size property
Ignored Vars: A, B, C, size-contribution, track-sizes, extra-space
Link Defaults: css21 (property) margin/min-height/max-height/min-width/max-width, css-align-3 (value) stretch/baseline, css-position-3 (property) left, css-position-3 (property) position, css-writing-modes-3 (dfn) start/end
At Risk: application of grid placement to absolutely-positioned boxes
</pre>
<pre class="link-defaults">
spec:css-align-3;
type:value;
text:stretch; for:align-self
text:stretch; for:align-content
text:space-between; for:justify-content
text:space-around; for:justify-content
type:property; text:column-gap
spec:css-break-3; type:dfn; text:fragment
spec:css-flexbox-1; type:dfn
text: specified size
text: content size
text: transferred size
spec:css-pseudo-4; type:selector;
text:::first-line
text:::first-letter
</pre>
<style>
.example {
clear:both
}
.pseudo-code {
font-family:monospace
}
.pseudo-code > ol {
list-style-type:decimal
}
.pseudo-code > ol > li > ol {
list-style-type:lower-latin
}
.pseudo-code > ol > li > ol > li > ol {
list-style-type:lower-roman
}
.pseudo-code ul {
list-style-type:disc
}
dd > p:nth-child(1) {
margin-top:0
}
dd:last-child {
margin-bottom: 0;
}
dl.phase {
padding-left: .5em;
border-left: .5em #e0e0e0 solid;
}
#grid-property-breakdown tr:nth-child(3) td {
width: 25%;
border-style: solid;
}
</style>
Issue: If you notice any inconsistencies between this Grid Layout Module
and the <a href="http://www.w3.org/TR/css-flexbox/">Flexible Box Layout Module</a>,
please report them to the CSSWG,
as this is likely an error.
<h2 id='intro'>
Introduction</h2>
<em>This section is not normative.</em>
Grid Layout is a new layout model for CSS
that has powerful abilities to control the sizing and positioning of boxes and their contents.
Unlike <a href="http://www.w3.org/TR/css-flexbox-1/">Flexible Box Layout</a>, which is single-axis&ndash;oriented,
Grid Layout is optimized for 2-dimensional layouts:
those in which alignment of content is desired in both dimensions.
<figure>
<img src="images/flex-layout.png"
alt="An example of flex layout:
two rows of items,
the first being three items a third of the space each,
and the second being five items, a fifth of the space each.
There is therefore alignment along the row axis, but not along the column axis.">
<figcaption>Exemplary Flex Layout Example</figcaption>
</figure>
<figure>
<img src="images/grid-layout.png"
alt="An example of grid layout:
two rows of items,
the first being four items&mdash;the last of which spans both rows,
and the second being two items&mdash;the first of which spans the first two columns&mdash; plus the spanned item from the first row.">
<figcaption>Exemplary Grid Layout Example</figcaption>
</figure>
In addition, due to its ability to explicitly position items in the grid,
Grid Layout allows dramatic transformations in visual layout structure
without requiring corresponding markup changes.
By combining <a href="http://www.w3.org/TR/css3-mediaqueries/">media queries</a> with the CSS properties that control layout of the grid container and its children,
authors can adapt their layout to changes in device form factors, orientation, and available space,
while preserving a more ideal semantic structuring of their content
across presentations.
Although many layouts can be expressed with either Grid or Flexbox,
they each have their specialties.
Grid enforces 2-dimensional alignment,
uses a top-down approach to layout,
allows explicit overlapping of items,
and has more powerful spanning capabilities.
Flexbox focuses on space distribution within an axis,
uses a simpler bottom-up approach to layout,
can use a content-size&ndash;based line-wrapping system to control its secondary axis,
and relies on the underlying markup hierarchy
to build more complex layouts.
It is expected that both will be valuable
and complementary tools for CSS authors.
<h3 id='background'>
Background and Motivation</h3>
<figure class="sidefigure">
<img class="figure" alt="Image: Application layout example requiring horizontal and vertical alignment." src="images/basic-form.png" />
<figcaption>Application layout example requiring horizontal and vertical alignment.</figcaption>
</figure>
As websites evolved from simple documents into complex, interactive applications,
techniques for document layout, e.g. floats,
were not necessarily well suited for application layout.
By using a combination of tables, JavaScript, or careful measurements on floated elements,
authors discovered workarounds to achieve desired layouts.
Layouts that adapted to the available space were often brittle
and resulted in counter-intuitive behavior as space became constrained.
As an alternative, authors of many web applications opted for a fixed layout
that cannot take advantage of changes in the available rendering space on a screen.
The capabilities of grid layout address these problems.
It provides a mechanism for authors to divide available space for layout into columns and rows
using a set of predictable sizing behaviors.
Authors can then precisely position and size the building block elements of their application
into the <a>grid areas</a> defined by the intersections of these columns and rows.
The following examples illustrate the adaptive capabilities of grid layout,
and how it allows a cleaner separation of content and style.
<h4 id='adapting-to-available-space'>
Adapting Layouts to Available Space</h4>
<figure class="sidefigure">
<img src="images/game-smaller.png"
alt="Let us consider the layout of a game in two columns and three rows: the game title in the top left corner, the menu below it, and the score in the bottom left with the game board occupying the top and middle cells on the right followed by game controls filling the bottom left. The left column is sized to exactly fit its contents (the game title, menu items, and score), with the right column filling the remaining space."/>
<figcaption>Five grid items arranged according to content size and available space.</figcaption>
</figure>
<figure class="sidefigure">
<img src="images/game-larger.png"
alt="As more space becomes available in larger screens, the middle row / right column are allowed to expand to fill that space." />
<figcaption>Growth in the grid due to an increase in available space.</figcaption>
</figure>
Grid layout can be used to intelligently resize elements within a webpage.
The adjacent figures represent a game with five major components in the layout:
the game title, stats area, game board, score area, and control area.
The author's intent is to divide the space for the game such that:
<ul>
<li>
The stats area always appears immediately under the game title.
<li>
The game board appears to the right of the stats and title.
<li>
The top of the game title and the game board should always align.
<li>
The bottom of the game board and bottom of the stats area align when the game has reached its minimum height.
In all other cases the game board will stretch to take advantage of all the space available to it.
<li>
The controls are centered under the game board.
<li>
The top of the score area is aligned to the top of the controls area.
<li>
The score area is beneath the stats area.
<li>
The score area is aligned to the controls beneath the stats area.
</ul>
The following grid layout example shows how an author might achieve
all the sizing, placement, and alignment rules declaratively.
<div class="example">
<pre class="lang-css">
/**
* Define the space for each <a>grid item</a> by declaring the grid
* on the <a>grid container</a>.
*/
#grid {
/**
* Two columns:
* 1. the first sized to content,
* 2. the second receives the remaining space
* (but is never smaller than the minimum size of the board
* or the game controls, which occupy this column [Figure 4])
*
* Three rows:
* 3. the first sized to content,
* 4. the middle row receives the remaining space
* (but is never smaller than the minimum height
* of the board or stats areas)
* 5. the last sized to content.
*/
display: grid;
grid-template-columns:
/* 1 */ auto
/* 2 */ 1fr;
grid-template-rows:
/* 3 */ auto
/* 4 */ 1fr
/* 5 */ auto;
}
/* Specify the position of each <a>grid item</a> using coordinates on
* the 'grid-row' and 'grid-column' properties of each <a>grid item</a>.
*/
#title { grid-column: 1; grid-row: 1; }
#score { grid-column: 1; grid-row: 3; }
#stats { grid-column: 1; grid-row: 2; align-self: start; }
#board { grid-column: 2; grid-row: 1 / span 2; }
#controls { grid-column: 2; grid-row: 3; justify-self: center; }
</pre>
<pre class="lang-markup">
&lt;div id="grid">
&lt;div id="title">Game Title&lt;/div>
&lt;div id="score">Score&lt;/div>
&lt;div id="stats">Stats&lt;/div>
&lt;div id="board">Board&lt;/div>
&lt;div id="controls">Controls&lt;/div>
&lt;/div>
</pre>
</div>
Note: There are multiple ways to specify the structure of the grid
and to position and size <a>grid items</a>,
each optimized for different scenarios.
<h4 id='source-independence'>
Source-Order Independence</h4>
<figure class="sidefigure">
<img alt="Image: An arrangement suitable for portrait orientation." src="images/game-portrait.png" />
<figcaption>An arrangement suitable for “portrait” orientation.</figcaption>
</figure>
<figure class="sidefigure">
<img alt="Image: An arrangement suitable for landscape orientation." src="images/game-landscape.png" />
<figcaption>An arrangement suitable for “landscape“ orientation.</figcaption>
</figure>
Continuing the prior example,
the author also wants the game to adapt to different devices.
Also, the game should optimize the placement of the components when viewed either in portrait or landscape orientation (Figures 6 and 7).
By combining grid layout with media queries,
the author is able to use the same semantic markup,
but rearrange the layout of elements independent of their source order,
to achieve the desired layout in both orientations.
The following example uses grid layout’s ability to name the space which will be occupied by a <a>grid item</a>.
This allows the author to avoid rewriting rules for <a>grid items</a>
as the grid’s definition changes.
<div class="example">
<pre class="lang-css">
@media (orientation: portrait) {
#grid {
display: grid;
/* The rows, columns and areas of the grid are defined visually
* using the grid-template-areas property. Each string is a row,
* and each word an area. The number of words in a string
* determines the number of columns. Note the number of words
* in each string must be identical. */
grid-template-areas: "title stats"
"score stats"
"board board"
"ctrls ctrls";
/* The way to size columns and rows can be assigned with the
* grid-template-columns and grid-template-rows properties. */
grid-template-columns: auto 1fr;
grid-template-rows: auto auto 1fr auto;
}
}
@media (orientation: landscape) {
#grid {
display: grid;
/* Again the template property defines areas of the same name,
* but this time positioned differently to better suit a
* landscape orientation. */
grid-template-areas: "title board"
"stats board"
"score ctrls";
grid-template-columns: auto 1fr;
grid-template-rows: auto 1fr auto;
}
}
/* The grid-area property places a grid item into a named
* area of the grid. */
#title { grid-area: title }
#score { grid-area: score }
#stats { grid-area: stats }
#board { grid-area: board }
#controls { grid-area: ctrls }
</pre>
<pre class="lang-markup">
&lt;div id="grid">
&lt;div id="title">Game Title&lt;/div>
&lt;div id="score">Score&lt;/div>
&lt;div id="stats">Stats&lt;/div>
8096
&lt;div id="board">Board&lt;/div>
&lt;div id="controls">Controls&lt;/div>
&lt;/div>
</pre>
</div>
Note: The reordering capabilities of grid layout intentionally affect
<em>only the visual rendering</em>,
leaving speech order and navigation based on the source order.
This allows authors to manipulate the visual presentation
while leaving the source order intact and optimized for non-CSS UAs
and for linear models such as speech and sequential navigation.
Advisement: Grid item placement and reordering must not be used
as a substitute for correct source ordering,
as that can ruin the accessibility of the document.
<h2 id='overview'>
Overview</h2>
<em>This section is not normative.</em>
Grid Layout controls the layout of its content
through the use of a <a>grid</a>:
an intersecting set of horizontal and vertical lines
which create a sizing and positioning coordinate system
for the <a>grid container</a>’s contents.
Grid Layout features
<ul>
<li>
fixed, flexible, and content-based <a href="#track-sizing">track sizing functions</a>
<li>
<a href="#placement">explicit item placement</a> via forwards (positive) and backwards (negative) numerical grid coordinates,
named grid lines, and named grid areas;
automatic item placement into empty areas, including <a href="#order-property">reordering with <css>order</css></a>
<li>
space-sensitive track repetition
and
automatic addition of rows or columns to accommodate additional content
<li>
control over alignment and spacing with
<a href="#auto-margins">margins</a>, <a>gutters</a>, and the <a href="http://www.w3.org/TR/css-align/">alignment properties</a>
<li>
the ability to overlap content and <a href="#z-order">control layering with <css>z-index</css></a>
</ul>
<a>Grid containers</a> can be nested or mixed with <a>flex containers</a>
as necessary to create more complex layouts.
<h3 id="overview-grid">
Declaring the Grid</h3>
The <a>tracks</a> (<a>rows</a> and <a>columns</a>) of the <a>grid</a>
are declared and sized
either explicitly through the <a>explicit grid</a> properties
or are implicitly created when items are placed outside the <a>explicit grid</a>.
The 'grid' shorthand and its sub-properties define the parameters
of the grid.
[[#grid-definition]]
<div class="example">
Below are some examples of grid declarations:
<ul>
<li>
The following declares a grid with four named areas:
<code>H</code>, <code>A</code>, <code>B</code>,
and <code>F</code>.
The first column is sized to fit its contents (''grid-template-columns/auto''),
and the second column takes up the remaining space (<a value lt=fr>1fr</a>).
Rows default to ''grid-template-rows/auto'' (content-based) sizing;
the last row is given a fixed size of ''30px''.
<pre>
main {
grid: "H H "
"A B "
"F F " 30px
/ auto 1fr;
}
</pre>
<li>
The following declares a grid with as many rows of at least ''5em''
as will fit in the height of the grid container (''100vh'').
The grid has no explicit columns;
instead columns are added as content is added,
the resulting column widths are equalized (<a value lt=fr>1fr</a>).
Since content overflowing to the right won't print,
an alternate layout for printing adds rows instead.
<pre>
main {
grid: repeat(auto-fill, 5em) / auto-flow 1fr;
height: 100vh;
}
@media print {
main {
grid: auto-flow 1fr / repeat(auto-fill, 5em);
}
}
</pre>
<li>
The following declares a grid with 5 evenly-sized columns
and three rows,
with the middle row taking up all remaining space
(and at least enough to fit its contents).
<pre>
main {
grid: auto 1fr auto / repeat(5, 1fr);
min-height: 100vh;
}
</pre>
</ul>
</div>
<h3 id="overview-placement">
Placing Items</h3>
The contents of the <a>grid container</a> are organized into individual <a>grid items</a>
(analogous to <a>flex items</a>),
which are then assigned to predefined [=grid areas|areas=] in the <a>grid</a>.
They can be explicitly placed using coordinates through the <a>grid-placement properties</a>
or implicitly placed into empty areas using <a href="#auto-placement">auto-placement</a>.
[[#placement]]
<div class="example">
Below are some examples of grid placement declarations
using the 'grid-area' shorthand:
<pre>
grid-area: a; /* Place into named grid area “a” */
grid-area: auto; /* Auto-place into next empty area */
grid-area: 2 / 4; /* Place into row 2, column 4 */
grid-area: 1 / 3 / -1; /* Place into column 3, span all rows */
grid-area: header-start / sidebar-start / footer-end / sidebar-start;
/* Place using named lines */
</pre>
These are equivalent to the following 'grid-row' + 'grid-column' declarations:
<pre>
grid-row: a; grid-column: a;
grid-row: auto; grid-column: auto;
grid-row: 2; grid-column: 4;
grid-row: 1 / -1; grid-column: 3;
grid-row: header-start / footer-end; grid-column: sidebar-start / footer-end;
</pre>
They can further be decomposed into the 'grid-row-start'/'grid-row-end'/'grid-column-start'/'grid-column-end' longhands, e.g.
<pre>
grid-area: a;
/* Equivalent to grid-row-start: a; grid-column-start: a; grid-row-end: a; grid-column-end: a; */
grid-area: 1 / 3 / -1;
/* Equivalent to grid-row-start: 1; grid-column-start: 3; grid-row-end: -1; grid-column-end: auto; */
</pre>
</div>
<h3 id="overview-sizing">
Sizing the Grid</h3>
Once the <a>grid items</a> have been <a href="#placement">placed</a>,
the sizes of the <a>grid tracks</a> (rows and columns) are calculated,
accounting for the sizes of their contents and/or available space as specified in the grid definition.
The resulting sized grid is <a href="#grid-align">aligned</a> within the <a>grid container</a>
according to the <a>grid container</a>’s 'align-content' and 'justify-content' properties.
[[#alignment]]
<div class="example">
The following example justifies all columns
by distributing any extra space among them,
and centers the grid in the <a>grid container</a>
when it is smaller than 100vh.
<pre>
main {
grid: auto-flow 1fr / repeat(auto-fill, 5em);
min-height: 100vh;
justify-content: space-between;
align-content: safe center;
}
</pre>
</div>
Finally each <a>grid item</a> is sized and aligned within its assigned <a>grid area</a>,
as specified by its own <a href="https://www.w3.org/TR/CSS2/visudet.html">sizing</a> [[!CSS21]] and <a lt="box alignment properties">alignment properties</a> [[!CSS-ALIGN-3]].
<!--
██████ ███████ ██ ██ ██████ ████████ ████████ ████████ ██████
██ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██████ ████████ ██ ██████
██ ██ ██ ██ ████ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ██
██████ ███████ ██ ██ ██████ ████████ ██ ██ ██████
-->
<h2 id='grid-concepts'>
Grid Layout Concepts and Terminology</h2>
In <dfn export>grid layout</dfn>,
the content of a <a>grid container</a> is laid out
by positioning and aligning it into a <a>grid</a>.
The <dfn export>grid</dfn> is an intersecting set of horizontal and vertical <a>grid lines</a>
that divides the <a>grid container</a>’s space into <a>grid areas</a>,
into which <a>grid items</a> (representing the <a>grid container</a>’s content) can be placed.
There are two sets of <a>grid lines</a>:
one set defining <dfn export lt="grid column" local-lt="column">columns</dfn>
that run along the <a href="https://www.w3.org/TR/css3-writing-modes/#block-axis">block axis</a> (the <dfn export>column axis</dfn>),
and an orthogonal set defining <dfn export lt="grid row" local-lt="row">rows</dfn>
along the <a href="https://www.w3.org/TR/css3-writing-modes/#inline-axis">inline axis</a> (the <dfn export>row axis</dfn>).
[[!CSS3-WRITING-MODES]]
<!--
<div class="figure">
<img class="figure" alt="Image: A diagram illustrating the relationship between the Grid Element and its Tracks, Lines, Areas and Items." src="images/grid-concepts.png" />
<p class="caption">A diagram illustrating the relationship between the <a>grid container</a> and its tracks, lines, areas and items.
</div>
-->
<figure>
<img class="figure" alt="Image: Grid Lines." src="images/grid-lines.png" />
<figcaption>Grid lines: Three in the block axis and four in the inline axis.</figcaption>
</figure>
Note: The “column axis” term as used here was chosen to match the <a>block axis</a>
because this matches the visual orientation of the column boxes themselves
and matches the direction that a column grows as more items are added to it.
As a result, it does not match the axis in which new columns are added
or in which their track size is measured,
which is the <a lt="inline axis">inline</a> or <a>row axis</a>
The opposite logic, of course, applies to the “row axis”.
<h3 id="grid-line-concept">
Grid Lines</h3>
<dfn id='grid-line' export lt='grid line|grid row line|grid column line'>Grid lines</dfn> are the horizontal and vertical dividing lines of the <a>grid</a>.
A <a>grid line</a> exists on either side of a column or row.
They can be referred to by numerical index,
or by an author-specified name.
A <a>grid item</a> references the <a>grid lines</a> to determine its position within the <a>grid</a>
using the <a href="#placement">grid-placement properties</a>.
<div class="example">
The following two examples both create three column <a>grid lines</a> and four row <a>grid lines</a>.
This first example demonstrates how an author would position a <a>grid item</a> using <a>grid line</a> numbers:
<pre class="lang-css">
#grid {
display: grid;
grid-template-columns: 150px 1fr;
grid-template-rows: 50px 1fr 50px;
}
#item1 { grid-column: 2;
grid-row-start: 1; grid-row-end: 4; }
</pre>
This second example uses explicitly named <a>grid lines</a>:
<pre class="lang-css">
/* equivalent layout to the prior example, but using named lines */
#grid {
display: grid;
grid-template-columns: 150px [item1-start] 1fr [item1-end];
grid-template-rows: [item1-start] 50px 1fr 50px [item1-end];
}
#item1 {
grid-column: item1-start / item1-end;
grid-row: item1-start / item1-end;
}
</pre>
</div>
<h3 id="grid-track-concept">
Grid Tracks and Cells</h3>
<dfn export local-lt="track">Grid track</dfn> is a generic term for a <a>grid column</a> or <a>grid row</a>&mdash;in
other words, it is the space between two adjacent <a>grid lines</a>.
Each <a>grid track</a> is assigned a sizing function,
which controls how wide or tall the column or row may grow,
and thus how far apart its bounding <a>grid lines</a> are.
Adjacent <a>grid tracks</a> can be separated by <a href="#gutters">gutters</a>
but are otherwise packed tightly.
A <dfn export>grid cell</dfn> is the intersection of a grid row and a grid column.
It is the smallest unit of the grid that can be referenced when positioning <a>grid items</a>.
<div class="example">
In the following example there are two columns and three rows.
The first column is fixed at 150px.
The second column uses flexible sizing, which is a function of the unassigned space in the grid,
and thus will vary as the width of the <a>grid container</a> changes.
If the used width of the <a>grid container</a> is 200px, then the second column is 50px wide.
If the used width of the <a>grid container</a> is 100px, then the second column is 0px
and any content positioned in the column will overflow the <a>grid container</a>.
<pre>
#grid {
display: grid;
grid-template-columns: 150px 1fr; /* two columns */
grid-template-rows: 50px 1fr 50px; /* three rows */
}
</pre>
</div>
<h3 id="grid-area-concept">
Grid Areas</h3>
A <dfn export>grid area</dfn> is the logical space used to lay out one or more <a>grid items</a>.
A <a>grid area</a> consists of one or more adjacent <a>grid cells</a>.
It is bound by four <a>grid lines</a>, one on each side of the <a>grid area</a>,
and participates in the sizing of the <a>grid tracks</a> it intersects.
A <a>grid area</a> can be named explicitly using the 'grid-template-areas' property of the <a>grid container</a>,
or referenced implicitly by its bounding <a>grid lines</a>.
A <a>grid item</a> is assigned to a <a>grid area</a>
using the <a href="#placement">grid-placement properties</a>.
<div class="example">
<pre>
/* using the template syntax */
#grid {
display: grid;
grid-template-areas: ". a"
"b a"
". a";
grid-template-columns: 150px 1fr;
grid-template-rows: 50px 1fr 50px;
}
#item1 { grid-area: a }
#item2 { grid-area: b }
#item3 { grid-area: b }
/* Align items 2 and 3 at different points in the grid area "b". */
/* By default, grid items are stretched to fit their grid area */
/* and these items would layer one over the other. */
#item2 { align-self: start; }
#item3 { justify-self: end; align-self: end; }
</pre>
</div>
A <a>grid item</a>’s <a>grid area</a> forms the containing block into which it is laid out.
<a>Grid items</a> placed into the same <a>grid area</a> do not directly affect each other's layout.
Indirectly, however, a <a>grid item</a> occupying a <a>grid track</a> with an <a>intrinsic sizing function</a>
can affect the size of that track (and thus the positions of its bounding <a>grid lines</a>),
which in turn can affect the position or size of another <a>grid item</a>.
<h2 id="order-accessibility">
Reordering and Accessibility</h2>
Grid layout gives authors great powers of rearrangement over the document.
However, these are not a substitute for correct ordering of the document source.
The 'order' property and <a>grid placement</a>
<em>do not</em> affect ordering in non-visual media
(such as <a href="https://www.w3.org/TR/css3-speech/">speech</a>).
Likewise, rearranging grid items visually does not affect
the default traversal order of sequential navigation modes
(such as cycling through links, see e.g. <a href="https://www.w3.org/TR/html5/editing.html#sequential-focus-navigation-and-the-tabindex-attribute"><code>tabindex</code></a> [[HTML5]]).
Advisement:
Authors <em>must</em> use 'order' and the <a>grid-placement properties</a>
only for visual, not logical, reordering of content.
Style sheets that use these features to perform logical reordering are non-conforming.
Note: This is so that non-visual media and non-CSS UAs,
which typically present content linearly,
can rely on a logical source order,
while grid layout’s placement and ordering features are used to tailor the visual arrangement.
(Since visual perception is two-dimensional and non-linear,
the desired visual order is not always equivalent to the desired reading order.)
<div class='example'>
Many web pages have a similar shape in the markup,
with a header on top,
a footer on bottom,
and then a content area and one or two additional columns in the middle.
Generally,
it's desirable that the content come first in the page's source code,
before the additional columns.
However, this makes many common designs,
such as simply having the additional columns on the left and the content area on the right,
difficult to achieve.
This has been addressed in many ways over the years,
often going by the name "Holy Grail Layout" when there are two additional columns.
Grid Layout makes this example trivial.
For example, take the following sketch of a page's code and desired layout:
<div class='code-and-figure'>
<div>
<pre class="lang-markup">
&lt;!DOCTYPE html>
&lt;header>...&lt;/header>
&lt;article>...&lt;/article>
&lt;nav>...&lt;/nav>
&lt;aside>...&lt;/aside>
&lt;footer>...&lt;/footer>
</pre>
</div>
<div><img src="images/grid-order-page.svg" width=400 height=360 alt="In this page the header is at the top and the footer at the bottom, but the article is in the center, flanked by the nav on the right and the aside on the left."></div>
</div>
This layout can be easily achieved with grid layout:
<pre class="lang-css">
main { display: grid;
grid: "h h h"
"a b c"
"f f f";
grid-template-columns: auto 1fr 20%; }
article { grid-area: b; min-width: 12em; }
nav { grid-area: a; /* auto min-width */ }
aside { grid-area: c; min-width: 12em; }
</pre>
As an added bonus,
the columns will all be <a value for="align-self" lt="stretch">equal-height</a> by default,
and the main content will be as wide as necessary to fill the screen.
Additionally,
this can then be combined with media queries to switch to an all-vertical layout on narrow screens:
<pre class="lang-css">
@media all and (max-width: 60em) {
/* Too narrow to support three columns */
main { display: block; }
}
</pre>
</div>
In order to preserve the author's intended ordering in all presentation modes,
authoring tools&mdash;including WYSIWYG editors as well as Web-based authoring aids--
must reorder the underlying document source
and not use 'order' or <a>grid-placement properties</a> to perform reordering
unless the author has explicitly indicated that the underlying
document order (which determines speech and navigation order) should be
<em>out-of-sync</em> with the visual order.
<div class="example">
For example, a tool might offer both drag-and-drop arrangement of grid items
as well as handling of media queries for alternate layouts per screen size range.
Since most of the time, reordering should affect all screen ranges
as well as navigation and speech order,
the tool would match the resulting drag-and-drop visual arrangement
by simultaneously reordering the DOM layer.
In some cases, however, the author may want different visual arrangements per screen size.
The tool could offer this functionality
by using the <a>grid-placement properties</a> together with media queries,
but also tie the smallest screen size's arrangement to the underlying DOM order
(since this is most likely to be a logical linear presentation order)
while using <a>grid-placement properties</a>
to rearrange the visual presentation in other size ranges.
This tool would be conformant, whereas a tool that only ever used
the <a>grid-placement properties</a>
to handle drag-and-drop grid rearrangement
(however convenient it might be to implement it that way)
would be non-conformant.
</div>
<!--
████████ ████ ██████ ████████ ██ ███ ██ ██ ██ ██████ ████████ ████ ████████
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██████ ████████ ██ ██ ██ ██ ██ ████ ████████ ██ ██ ██
██ ██ ██ ██ ██ ██ █████████ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ██
████████ ████ ██████ ██ ████████ ██ ██ ██ ██ ██████ ██ ██ ████ ████████
-->
<h2 id="grid-model">
Grid Containers</h2>
<h3 id='grid-containers'>
Establishing Grid Containers: the ''display/grid'' and ''inline-grid'' 'display' values</h3>
<pre class="propdef">
Name: display
New values: grid | inline-grid
</pre>
<dl dfn-for="display" dfn-type=value>
<dt><dfn>grid</dfn>
<dd>
This value causes an element to generate a block-level <a>grid container</a> box.
<dt><dfn>inline-grid</dfn>
<dd>
This value causes an element to generate an inline-level <a>grid container</a> box.
</dl>
A <dfn export>grid container</dfn> establishes a new <dfn export>grid formatting context</dfn> for its contents.
This is the same as establishing a block formatting context,
except that grid layout is used instead of block layout:
floats do not intrude into the grid container,
and the grid container's margins do not collapse with the margins of its contents.
The contents of a <a>grid container</a> are laid out into a <a>grid</a>,
with <a>grid lines</a> forming the boundaries of each <a>grid items</a>’ containing block.
The 'overflow' property applies to <a>grid containers</a>.
Grid containers are not block containers,
and so some properties that were designed with the assumption of block layout
don't apply in the context of grid layout.
In particular:
<ul>
<li>
'float' and 'clear' have no effect on a <a>grid item</a>.
However, the 'float' property still affects the computed value of 'display' on children of a grid container,
as this occurs <em>before</em> <a>grid items</a> are determined.
<li>
'vertical-align' has no effect on a grid item.
<li>
the ''::first-line'' and ''::first-letter'' pseudo-elements do not apply to <a>grid containers</a>,
and <a>grid containers</a> do not contribute a first formatted line or first letter to their ancestors.
</ul>
If an element's specified 'display' is ''inline-grid''
and the element is floated or absolutely positioned,
the computed value of 'display' is <a value>grid</a>.
The table in <a href="https://www.w3.org/TR/CSS2/visuren.html#dis-pos-flo">CSS 2.1 Chapter 9.7</a> is thus amended
to contain an additional row,
with ''inline-grid'' in the "Specified Value" column
and ''grid'' in the "Computed Value" column.
<h3 id='intrinsic-sizes'>
Sizing Grid Containers</h3>
Note see [[!CSS3-SIZING]] for a definition of the terms in this section.
A <a>grid container</a> is sized
using the rules of the formatting context in which it participates:
<ul>
<li>
As a <a>block-level</a> box in a <a>block formatting context</a>,
it is sized like a <a>block box</a> that establishes a formatting context,
with an ''auto'' <a>inline size</a> calculated as for non-replaced block boxes.
<li>
As an inline-level box in an <a>inline formatting context</a>,
it is sized as an atomic inline-level box (such as an inline-block).
</ul>
In both inline and block formatting contexts,
the <a>grid container</a>’s ''auto'' <a>block size</a> is its max-content size.
<span class="note">The block layout spec should probably define this,
but it isn't written yet.</span>
The <a>max-content size</a> (<a>min-content size</a>) of a <a>grid container</a> is
the sum of the <a>grid container’s</a> track sizes (including gutters)
in the appropriate axis,
when the grid is sized under a <a>max-content constraint</a> (<a>min-content constraint</a>).
<!--
██████ ██ ███ ██ ██ ████████ ████ ██ ██ ██████
██ ██ ██ ██ ██ ███ ███ ██ ██ ██ ███ ██ ██ ██
██ ██ ██ ██ ████ ████ ██ ██ ██ ████ ██ ██
██ ██ ██ ██ ██ ███ ██ ████████ ██ ██ ██ ██ ██ ████
██ ██ █████████ ██ ██ ██ ██ ██ ████ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██
██████ ████████ ██ ██ ██ ██ ██ ████ ██ ██ ██████
-->
<h3 id="overlarge-grids">
Clamping Overly Large Grids</h3>
Since memory is limited,
UAs may clamp the possible size of the <a>grid</a>
to be within a UA-defined limit,
dropping all lines outside that limit.
If a grid item is placed outside this limit,
its grid area must be <a>clamped</a> to within this limited grid.
To <dfn local-lt=clamp>clamp a grid area</dfn>:
* If the <a>grid area</a> would <a>span</a> outside the limited grid,
its span is clamped to the last line of the limited <a>grid</a>.
* If the <a>grid area</a> would be placed completely outside the limited grid,
its span must be truncated to 1
and the area repositioned into the last <a>grid track</a> on that side of the grid.
<div class='example'>
For example, if a UA only supported grids with at most 1000 tracks in each dimension,
the following placement properties:
<pre class="lang-css">
.grid-item {
grid-row: 500 / 1500;
grid-column: 2000 / 3000;
}
</pre>
Would end up being equivalent to:
<pre class="lang-css">
.grid-item {
grid-row: 500 / 1001;
grid-column: 1000 / 1001;
}
</pre>
</div>
<!--
██████ ████████ ████ ████████ ████ ████████ ████████ ██ ██ ██████
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ███ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ████ ██
██ ████ ████████ ██ ██ ██ ██ ██ ██████ ██ ███ ██ ██████
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██████ ██ ██ ████ ████████ ████ ██ ████████ ██ ██ ██████
-->
<h2 id="grid-items">
Grid Items</h2>
Loosely speaking, the <dfn export id="grid-item" lt="grid item">grid items</dfn> of a <a>grid container</a>
are boxes representing its in-flow contents.
Each in-flow child of a <a>grid container</a>
becomes a <a>grid item</a>,
and each contiguous sequence of child <a>text runs</a>
is wrapped in an <a>anonymous</a> <a>block container</a> <a>grid item</a>.
However, if the entire sequence of child <a>text runs</a> contains only
<a href="https://www.w3.org/TR/CSS2/text.html#white-space-prop">white space</a>
(i.e. characters that can be affected by the 'white-space' property)
it is instead not rendered (just as if its <a>text nodes</a> were ''display:none'').
<div class="example">
<p>Examples of grid items:
<pre class="lang-markup">
&lt;div style="display: grid">
&lt;!-- grid item: block child -->
&lt;div id="item1">block&lt;/div>
&lt;!-- grid item: floated element; floating is ignored -->
&lt;div id="item2" style="float: left;">float&lt;/div>
&lt;!-- grid item: anonymous block box around inline content -->
anonymous item 3
View remainder of file in raw view