Overview.bs

<pre class='metadata'>
Title: CSS Grid Layout Module Level 2
Shortname: css-grid
Level: 2
Status: UD
Group: csswg
Work Status: exploring
ED: https://drafts.csswg.org/css-grid-2/
Editor: Tab Atkins Jr., Google, http://www.xanthir.com/contact/
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Rossen Atanassov, Microsoft, ratan@microsoft.com
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.
</pre>

Introduction {#intro}
=====================

This level is currently maintained as a diff spec over the level 1 module [[!CSS-GRID-1]].


<h2 id="grid-model">
Grid Containers</h2>

<h3 id='grid-containers'>
Establishing Grid Containers: the ''subgrid'' 'display' value</h3>

	<a>Subgrids</a> provide the ability to pass grid parameters down through nested elements,
	and content-based sizing information back up to their parent grid.

	<pre class="propdef">
	Name: display
	New values: subgrid
	</pre>

	<dl dfn-for="display" dfn-type=value>
		<dt><dfn>subgrid</dfn>
		<dd>
			If the element is a <a>grid item</a>
			(i.e. it is in-flow and its parent is a <a>grid container</a>),
			this value makes the element a <a>subgrid</a>
			(which is a special type of <a>grid container</a> box, see [[#subgrids]])
			and consequently ignores its 'grid-template-*' and 'grid-*-gap' properties
			in favor of adopting the parent grid tracks that it spans.

			Otherwise,
			it behaves as ''grid''.
	</dl>

<!--
 ██████  ██     ██ ████████   ██████   ████████  ████ ████████
██    ██ ██     ██ ██     ██ ██    ██  ██     ██  ██  ██     ██
██       ██     ██ ██     ██ ██        ██     ██  ██  ██     ██
 ██████  ██     ██ ████████  ██   ████ ████████   ██  ██     ██
      ██ ██     ██ ██     ██ ██    ██  ██   ██    ██  ██     ██
██    ██ ██     ██ ██     ██ ██    ██  ██    ██   ██  ██     ██
 ██████   ███████  ████████   ██████   ██     ██ ████ ████████
-->

<h2 id="subgrids">
Subgrids</h2>

	A <a>grid item</a> can itself be a <a>grid container</a> by giving it ''display: grid'';
	in this case the layout of its contents will be independent of the layout of the grid it participates in.

	In some cases it might be necessary for the contents of multiple <a>grid items</a> to align to each other.
	A <a>grid container</a> that is itself a <a>grid item</a>
	can defer the definition of its rows and columns to its parent <a>grid container</a>
	by using ''display: subgrid'',
	making it a <dfn export>subgrid</dfn>.
	In this case, the <a>grid items</a> of the <a>subgrid</a>
	participate in sizing the <a>grid</a> of the parent <a>grid container</a>,
	allowing the contents of both grids to align.

	<div class="example">
		For example, suppose we have a form consisting of a list of inputs with labels:

		<pre class="lang-html">
			&lt;ul>
				&lt;li>&lt;label>Name:&lt;/label> &lt;input name=fn>
				&lt;li>&lt;label>Address:&lt;/label> &lt;input name=address>
				&lt;li>&lt;label>Phone:&lt;/label> &lt;input name=phone>
			&lt;/ul>
		</pre>

		We want the labels and inputs to align, and we want to style each list item with a border.
		This can be accomplished with subgrid layout:

		<pre>
			ul {
				display: grid;
				grid: auto-flow / auto 1fr;
			}
			li {
				display: subgrid;
				grid-column: span 2;
				margin: 0.5em;
				border: solid;
				padding: 0.5em;
			}
			label {
				grid-column: 1;
			}
			input {
				grid-column: 2;
			}
		</pre>
	</div>

	A <a>subgrid</a> behaves just like a normal <a>grid container</a> except that:

	<ul style="list-style-type: lower-alpha">
		<li>
			The number of explicit tracks is given by its <a>grid span</a>,
			rather than by 'grid-template-rows'/'grid-template-columns'.

		<li>
			The <a>grid-placement properties</a> of the <a>subgrid</a>’s <a>grid items</a>
			are scoped to the lines covered by the subgrid.
			E.g., numeric indices count starting from the first line of the subgrid
			rather than the first line of the parent grid.

		<li>
			The <a>subgrid</a> itself lays out as an ordinary <a>grid item</a> in its parent grid,
			but acts as if it was completely empty for sizing purposes.

			The <a>subgrid</a>'s own <a>grid items</a> participate in the sizing of its parent grid and are aligned to it.
			In this process, the sum of the <a>subgrid</a>'s margin, padding, and borders at each edge
			are applied as an extra layer of margin to the items at those edges.

			<div class="example">
				For example, if we have a 3&times;3 grid with the following tracks:

				<pre>#parent-grid { grid-template-columns: 300px auto 300px; }</pre>

				If a subgrid covers the last two tracks,
				its first two columns correspond to the parent grid's last two columns,
				and any items positioned into those tracks participate in sizing the parent grid.
				Specifically, an item positioned in the first track of the subgrid
				influences the auto-sizing of the parent grid's middle track.

				<pre>
					#subgrid { grid-column: 2 / span 2; } /* cover parent's 2nd and 3rd tracks */
					#subgrid > :first-child { grid-column: 1; } /* subgrid's 1st track, parent grid's 2nd track */
				</pre>

				If the subgrid has margins/borders/padding,
				the size of those margins/borders/padding also influences sizing.
				For example, if the subgrid has 100px padding:

				<pre>#subgrid { padding: 100px; }</pre>

				Then a <a>grid item</a> in the <a>subgrid's</a> first track
				acts as if it has an additional ''100px'' of top, left, and bottom margin
				influencing the sizing of the parent grid's tracks
				and the <a>grid item's</a> own position.
			</div>

		<li>
			The 'grid-gap' properties do not apply to subgrids.
			(Their items are instead spaced by the 'grid-gap' of their parent grid,
			since they are laid out in the parent grid.)

		<li>
			The <a>subgrid</a> does not have any <a>implicit grid tracks</a>;
			every <a>grid area</a> within it is <a>clamped</a> to its <a>explicit grid</a>.

			<div class="example">
				For example, if a ''span 1'' subgrid has a <a>grid item</a> with ''grid-column: 2 / span 3;'',
				then that item is instead forced into (and limited to) the first (only) track in the subgrid.
			</div>

		<li>
			The <a>subgrid</a> is always stretched in both dimensions:
			the 'align-self'/'justify-self' properties on it are ignored,
			as are any specified width/height constraints.

		<li>
			Layoutwise, the <a>subgrid</a>’s <a>explicit grid</a>
			is always aligned with the corresponding section of the parent <a>grid</a>;
			the 'align-content'/'justify-content' properties on it are also ignored.

		<li>
			The UA <em>may</em> apply 'overflow' to <a>subgrids</a>
			so the contents of the subgrid can be scrolled aside.
			(Note: the act of scrolling does not affect layout.)
			Overflow must otherwise be treated as ''visible''.

		<li>
			Since <a>subgrids</a> can be placed before their contents are placed,
			their lines automatically receive the line names specified on the parent <a>grid</a>.
	</ul>

<!--
██     ██    ███     ██████   ███████  ██    ██ ████████  ██    ██
███   ███   ██ ██   ██    ██ ██     ██ ███   ██ ██     ██  ██  ██ 
████ ████  ██   ██  ██       ██     ██ ████  ██ ██     ██   ████  
██ ███ ██ ██     ██  ██████  ██     ██ ██ ██ ██ ████████     ██   
██     ██ █████████       ██ ██     ██ ██  ████ ██   ██      ██   
██     ██ ██     ██ ██    ██ ██     ██ ██   ███ ██    ██     ██   
██     ██ ██     ██  ██████   ███████  ██    ██ ██     ██    ██   
-->

<h2 id=masonry>
Masonry Layout</h2>

<div class=issue>
	People have been trying to use CSS for <a href="https://github.com/w3c/csswg-drafts/issues/1009#issuecomment-278095001">masonry layouts</a> for over a decade,
	and it doesn't seem to have slowed,
	so it's probably not just a layout fad.
	Would probably be worthwhile to address officially.

	As far as I can tell,
	this is best done as a Grid feature;
	some of the features I've seen in masonry libraries
	(like large items spanning multiple masonry tracks)
	make Flexbox inappropriate.
	This also would reuse *so many* Grid features
	that it would be a shame to put together a brand new layout spec for it.

	No clue what it would look like yet, tho.
	In handwavey terms, it's a grid that's only gridded
	"in one dimension",
	and free-flows in the other,
	with auto-flow.

	Note that this is actually 100% possibly with Grid today,
	if your items are of known height,
	by making thousands of 1px tall rows,
	and setting the items' row-span to be equal to their height in px.
	(Or some lower-res multiple, like 10px rows.)
	Dense row auto-flow then magically makes Masonry happen.
	This is just a terrible hack that runs into memory/CPU issues
	due to the large number of rows.
	It suggests, tho,
	that making it work properly
	is mostly a matter of relaxing some constraints,
	rather than adding entirely new behavior.
</div>