Title: CSS Grid Layout Module Level 3
Shortname: css-grid
Level: 3
Status: ED
Work Status: Exploring
Group: csswg
TR:  https://www.w3.org/TR/css-grid-3/
ED: https://drafts.csswg.org/css-grid-3/
Editor: Tab Atkins Jr., Google, http://www.xanthir.com/contact/, w3cid 42199
Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400
Former Editor: Mats Palmgren, Mozilla, mailto:mats@mozilla.com
Editor: Jen Simmons, Apple, http://jensimmons.com/, w3cid 52801
Editor: Brandon Stewart, Apple, https://brandonstewart.net, w3cid 138640
Abstract: This module introduces masonry layout as an additional layout mode for CSS Grid containers.
WPT Path Prefix: css/css-grid/masonry/tentative/
WPT Display: open
Markup Shorthands: css yes
Status Text: This specification represents two variations on the proposal for masonry layout. Feedback on the alternatives is welcome.

spec: css-align-3;
	type: value; for: align-content;
		text: center;
		text: stretch;
	type: dfn; text: alignment baseline;
spec: css-grid-2; type: dfn;
	text: auto-placement algorithm
	text: computed track list
	text: collapsed track
spec: css-flexbox-1; 
	type:property; 
		text: order
	type:dfn;
		text: order-modified document order

Introduction

Background and Motivation

Waterfall Layout with Auto-placed Items

The Pinterest search results page exemplifies this layout:

Here, each item has a different height (depending on the content and the width of the column), and inspecting the DOM reveals (as the visual content itself gives no indication of ordering) that each item has been placed into the column with the smallest height so far.

One-dimensional Grid Layout

This example by Douglas Graham uses explicit positioning to place each item into its assigned column; but there are no rows. Instead, items in each column stack one after the other. This layout can't be duplicated in [=grid layout=] because the “spanning” relationships among the items in adjacent columns is not fixed: it depends on their relative heights and whether the optional banner or advertisement items are included. It also can't be duplicated in [=flex layout=] because the source order of the items (which is used for reading, sequential navigation, and one-column mobile phone layout) goes back and forth between the two columns.

Alternative Syntax Proposals

Value Definitions

Masonry Layout Model

Establishing Masonry Containers

	Grid-integrated Syntax	Grid-independent Syntax	Description
Column Masonry	display: grid; grid-template-columns: 1fr 2fr 3fr; grid-template-rows: masonry;	display: masonry; masonry-tracks: 1fr 2fr 3fr; masonry-direction: column;
Row Masonry	display: grid; grid-template-rows: 1fr 2fr 3fr; grid-template-columns: masonry;	display: masonry; masonry-tracks: 1fr 2fr 3fr; masonry-direction: row;

Reordering and Accessibility

For example, in the following markup sample, the fourth item is a spanner that doesn't fit in the remaining empty column on the first line. It ends up positioned into the into the first column, which is the highest available space into which it will fit. The next few items, which have a span of 1, end up laying out “above” it in the empty column, violating the natural reading order. <section class=masonry> <div class=item>1</div> <div class=item>2</div> <div class="item tall">3</div> <div class="item wide">4</div> <div class=item>5</div> <div class=item>6/div> <div class=item>7</div> </section> <style> .masonry { display: masonry; masonry-tracks: repeat(5, auto); } .item { height: 50px; } .item.wide { masonry-track: span 3; } .item.tall { height: 90px; } </style>

Similarly, items explicitly placed into specific tracks can leave gaps behind them, into which subsequent auto-placed items can be placed visually out-of-order.

		Name: grid-template-columns, grid-template-rows
		New values: masonry
		Initial: none
		Applies to: [=grid containers=]
		Inherited: no
		Percentages: refer to corresponding dimension of the content area
		Computed value: the keyword ''grid-template-columns/none'' or the keyword ''grid-template-columns/masonry'' or a [[computed track list]]
		Animation type: see [[css-grid-2#track-sizing|CSS Grid Level 2]]
	

	Name: grid-auto-flow
	Value: [ row | column | row-reverse | column-reverse ] || dense || wrap-reverse
	Initial: row
	Applies to: grid containers
	Inherited: no
	Percentages: n/a
	Computed value: specified keyword(s)
	Animation type: discrete
	

	Name: display
	New values: masonry | inline-masonry
	

	Name: masonry-direction
	Value: row | column | row-reverse | column-reverse
	Initial: column
	Inherited: no
	Applies to: [=masonry containers=]
	Computed value: as specified
	Animation type: discrete
	

	Name: masonry-fill
	Value: normal | reverse
	Initial: normal
	Inherited: no
	Applies to: [=masonry containers=]
	Computed value: as specified
	Animation type: discrete
	

	Name: masonry-flow
	Value: <<'masonry-direction'>> || <<'masonry-fill'>>
	

Name: masonry
Value: <<'masonry-template-areas'>> || <<'masonry-template-tracks'>> || <<'masonry-direction'>> || <<'masonry-fill'>>

Masonry Track Specification

	Name: masonry-template-tracks
	Value: none | <> | <> | subgrid <>?
	Initial: repeat(auto-areas, auto)
	Applies to: [=masonry containers=]
	Inherited: no
	Percentages: refer to corresponding dimension of the content area
	Computed value: by computed value type per item in the [=computed track list=]
	Animation type: if list lengths match, by [=computed value=] type; otherwise, discrete
	

		<masonry-auto-track-list> = [ <>? [ <> | <> ] ]*
		                            <>? <> <>?
		                            [ [ <> | <> ] <>? ]*
	

	Name: masonry-template-areas
	Value: none | <>
	Initial: none
	Applies to: [=masonry containers=]
	Inherited: no
	Percentages: n/a
	Computed Value: the keyword ''masonry-template-values/none'' or a string
	Canonical Order: per grammar
	Animation type: discrete
	

	Name: masonry-auto-tracks
	Value: <<'grid-auto-columns'>>
	Initial: auto
	Applies to: grid containers
	Inherited: no
	Percentages: refer to corresponding dimension of the content area
	Computed value: a [=computed track list=]
	Canonical order: per grammar
	Animation type:	if the list lengths match, by computed value type per item; discrete otherwise
	

Subgrids

Grid-independent Syntax: ...the subgridded axis acts like ''grid-template/none''. In [=masonry layout=], auto-placed [=subgrids=] don't inherit any line names from their parent grid, because that would make the placement of the item dependent on layout results; but the subgrid's tracks are still aligned to the parent's tracks as usual.

Here's a subgrid example: ```css ``` ```html

1 2 3 subgrid.1 sub.2 s.3 4 5 6 7

```

Note how the subgrid's first item ("subgrid.1") contributes to the intrinsic size of the 2nd row in the parent grid. This is possible since the subgrid specified a definite position so we know which tracks it will occupy. Note also that trying to subgrid the parent's [=stacking axis=] results in the subgrid getting [=masonry layout=] in its [=inline axis=].

Track Repetition: the ''repeat()'' notation

repeat(auto-areas)

repeat(auto-fit)

Grid Axis Track Sizing

Subgrid Item Contributions

Optimized Track Sizing

1. Separate all the [=masonry items=] into item groups, according to the following properties: * the span of the item * the placement of the item, i.e. which tracks it is allowed to be placed in * the item's [=baseline-sharing group=] Note: For example, an item with span 2 placed in the second track will be in a different group than an item with span 2 that has an [=automatic grid position=].
2. For each [=item group=], synthesize a virtual masonry item that has the maximum of every intrinsic size contribution among the items in that group. If the items apply [=baseline alignment=], determine the baselines of the [=virtual masonry item=] by placing all of its items into a single hypothetical grid track and finding their shared baseline(s) and shims. Increase the group's intrinsic size contributions accordingly.
3. Place hypothetical copies of each [=virtual masonry item=] into the [=grid axis=] tracks in every position that the item could potentially occupy, and run the [[css-grid-2#algo-track-sizing|track sizing algorithm]] with those items. The resulting track sizes are the [=masonry container's=] track sizes.

Masonry Placement

Here's a masonry layout example demonstrating placed and spanning items:

ISSUE: Need a better example!!!

Placement Precision: the 'masonry-slack' property

	Name: masonry-slack
	Value: <> | infinite
	Initial: 1em
	Percentages: relative to the [=grid-axis=] [=content box=] size of the [=masonry container=]
	Inherited: no
	Applies to: [=masonry containers=]
	Computed value: a computed <> value
	Animation type: as length
	

: <> :: Specifies the tie threshold for the [=masonry container=]. Placement positions are considered to be equally good (“tied”) if they are within the specified distance from the shortest position. Note: The initial value is a “small” distance (''1em'') that is probably appropriate to represent “close enough”. : infinite :: Specifies an infinite [=tie threshold=]. This makes items distribute themselves strictly in order, without considering the length of the tracks at all. Note: This value can result in consecutive items being placed in dramatically different positions in the [=stacking axis=], which can be confusing to readers. If the initial value (`1em`) is too small, consider a larger value (such as `10em` or `50vh`) instead of `infinite`.

Masonry Layout and Placement Algorithm

1. If the item has a [=definite grid position=] in the [=grid axis=], use that placement. ISSUE: Should this also update the placement cursor? Otherwise, resolve its [=grid axis=] placement using these substeps:
   1. Starting at the first [=grid axis=] line in the [=implicit grid=], find the largest [=running position=] of the [=grid axis=] tracks that the item would span if it were placed at this line, and call this position max_pos.
   2. Repeat the previous step for each successive line number until the item would no longer fit inside the grid.
   3. Let |possible lines| be the line that resulted in the smallest max_pos, and all lines that result in a max_pos within the [=tie threshold=] of this max_pos.
   4. Choose the first line in |possible lines| greater than or equal to the [=auto-placement cursor=] as the item's position in the [=grid axis=]; or if there are none such, choose the first one.
   5. Update the [=auto-placement cursor=] to point to item's last line.
2. Place the item in its [=grid axis=] tracks at the maximum of the [=running position=]s of the tracks it spans.
3. Calculate the size of the item's containing block and then layout the item. Set the [=running position=] of the spanned [=grid axis=] tracks to max_pos + [=outer size=] + 'grid-gap'.

Containing Block

Placement and Writing Modes

Here's a simple example using ''direction: rtl'' in the [=grid axis=]: ```css ``` ```html

1 2 3 4

```

Here's a simple example using ''direction: rtl'' in the [=stacking axis=]: ```css ``` ```html

1 2 3 4

```

Sizing Grid Containers

Here's a simple example: ```css ``` ```html

1 2 3 4 5 6

```

Alignment and Spacing

Baseline Alignment in the stacking axis

Fragmentation

Fragmentation in the stacking axis

Fragmentation in the Grid Axis

Absolute Positioning

Graceful Degradation

Acknowledgements

Security Considerations

Privacy Considerations

Changes

Additions Since Level 2

• Added [=masonry layout=].
• Added ''*-reverse'' keywords to 'grid-auto-flow'.

Recent Changes