Introduction

Background and Motivation

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.

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;

		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'>>
	

Masonry Track Specification

	Name: masonry-template-tracks
	Value: <<'grid-template-columns'>>
	Initial: repeat(auto-areas, auto)
	Applies to: [=masonry containers=]
	Inherited: no
	Percentages: refer to correspodning 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
	

	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 correspodning 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 [=masonry 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: <>
	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 length
	Animation type: discrete
	

: <> :: 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”.

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. Increment the line number and repeat step 2 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 [=masonry 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 Masonry Axis

Fragmentation

Fragmentation in the Masonry Axis

Fragmentation in the Grid Axis

Absolute Positioning

Performance Notes

Graceful Degradation

Acknowledgements