Brick by brick: Help us build CSS Masonry

Patrick Brosset

Alison Maher

Published: July 23, 2025

The Microsoft Edge and Google Chrome teams are excited to announce that CSS masonry is ready for early developer testing from Chrome and Edge 140.

With open issues surrounding the CSS masonry specification and syntax still remaining, your feedback is crucial to help us cement the final shape of the API. Try out the feature and let us know what you think.

Test CSS Masonry in Chromium today

To test CSS Masonry today:

Use Chrome or Edge 140 or later (or another Chromium-based browser with a matching version).
Go to about:flags in a new tab.
Search for "CSS Masonry Layout".
Enable the flag.
Restart the browser.

The entry for Masonry on the experiments page.

With the feature enabled, you can see it in action by checking out the Microsoft Edge demos (view the demos source code), or continue reading to learn more about the feature and the available syntax.

What is masonry?

CSS masonry is a layout mode that lets you create a brick-like arrangement of items, in a way that's not easily attainable with CSS grid, flexbox, or multi-column layout.

CSS masonry can be used to arrange items in a column or row format with items placed within those columns or rows in a collapsed manner.

Think of masonry as a motorway, where the only constraint is the number and the size of the different driving lanes. Within the lanes, vehicles can take any length they want, and they're always trying to be the closest they can to their destination, which is the start of the masonry layout.

Demo using vehicles queuing in lanes to demonstrate the layout.

Your layout items are only constrained in one direction and can freely breathe along the other, irrespective of other items that are close-by. masonry is different from grid in that its tracks are only defined in a single direction.

In masonry, the visual order of items is less important than the final design. Masonry lets you make the most of the available space, whatever items you have. This makes it a great choice for pages that are visually intensive, and where the visual order of the content doesn't matter as much as the final result.

One interesting aspect of masonry is that it also allows items to span multiple tracks, just like with grid. When that happens, items continue to be placed in a way that fills in as much of the available space as possible.

The image with vehicles, this time large vehicles span two columns.

This auto-placement behavior can lead to very interesting results, which web designers have tried to achieve for a long time. For an example, check out the New York City photo gallery demo, which shows how photos can be displayed in a compact way along multiple columns, while allowing certain items (the title in this example) to span across multiple columns:

A gallery where the title spans columns.

Here are a few other examples of what masonry can be used for.

A blog layout, showing each post's thumbnail and description.

A news site with masonry used for article cards. — View the blog demo here.

A news site, where articles appear in columns, with some articles being wider than others, and hero images span the entire width of the page.

A news site where some articles span columns. — View the news site demo here.

A collection of photos, with different column sizes, and certain photos spanning multiple columns.

A photography site masonry layout. — View the nature demo here.

Workarounds and their limitations

Implementing this design pattern on the web today requires you to use either JavaScript libraries or workarounds that use CSS grid, flexbox, or multi-column. However, doing this can come with downsides, including:

Poorer performance: Relying on JavaScript libraries or custom code to mimic CSS masonry comes with performance tradeoffs, which can lead to negative user experiences.
Higher code complexity:
- Guaranteeing the correct placement of items and distribution of space within CSS grid, flexbox, or multi-column in order to mimic a CSS masonry layout is difficult to achieve.
- Handling specific features such as items that span more than one column or row, custom ordering of items, or adjusting to the viewport can also lead to complexity and limitations.
Larger maintenance burden: complex custom CSS or JavaScript code is more difficult to maintain.

CSS grid is an amazing layout mode that's very flexible and lets you create many different styles of layouts, whether for an entire webpage, or a component, or just to align individual items. However, it doesn't have the same characteristics as masonry.

In CSS grid, the rows and columns are rigidly defined and items can only exist within the grid cells. If you're trying to pack items along one of the axes, but the items are not sized to fit their respective cells, you'll have to choose between leaving gaps between items or stretching them to fill the empty space.

Just like masonry, flexbox only cares about one direction, and lets items decide the space they want to occupy along the other direction. This means that you can get a layout that looks like a masonry layout using flexbox, as long as you are happy for the items to lay out in the block direction, a column at a time. The flex container will also need a defined block-size or height, to cause the items to wrap onto a new flex line, thus creating a new column.

Multi-column can also create a layout that looks like masonry, again arranging the items in columns. In addition, multi-column doesn't let you size each of the columns differently. They're all the same size, whereas masonry provides a lot of flexibility when it comes to defining the tracks within which the items are packed.

The point to remember here isn't that grid, flexbox, or multi-column are worse layouts than masonry. They're great types of layouts that have a lot of use cases. The point is: if what you want is a masonry layout, then CSS masonry is what will give it to you.

The state of CSS masonry

The CSS Working Group is drafting masonry in the CSS Grid Level 3 specification. The specification is still under construction and temporarily includes two different proposed syntaxes. The first of these uses a new keyword for the display property, while in the second masonry is directly integrated into CSS grid layout.

Use `display: masonry`

This syntax introduces CSS masonry as its own display type. More of the details around the approach and its motivation can be found in the blog post Feedback needed: How should we define CSS masonry? from the Google Chrome team, as well as in the remaining section of this post. The current prototype in Chromium is based on this proposal.

`display: grid; grid-template-*: masonry;`

In this syntax, CSS masonry is directly integrated into CSS grid. The masonry mode is triggered by applying the keyword masonry to the grid-template-columns definition in the case of a row-based masonry layout, or to the grid-template-rows definition in the case of a column-based masonry layout.

More details on this proposal and its motivation can be found in the WebKit post Help us choose the final syntax for Masonry in CSS.

Note that an alternative to this proposal is the item-pack property and the collapse keyword, which would trigger CSS masonry instead of using one of the two grid template properties.

Since the publication of posts by the Chrome and WebKit teams, the CSSWG has continued discussions around the overall syntax to move forward with. Your feedback can help inform further development within these forums.

For more details on the current status of the discussions, see issue 11593, which outlines the current set of masonry syntax discussion topics, and issue 11243 for a summary of the syntax debate so far.

Create your own CSS masonry layout

Let's have some fun and create a CSS masonry layout.

Although the syntax for CSS masonry is still under discussion, our implementation of the feature can be tested in Chromium today by enabling the CSS Masonry Layout flag as explained in Test CSS Masonry today. The following examples demonstrate what's available in the developer trial.

Create a masonry container

To create your first column-based masonry container, use display:masonry and define your column sizes by using grid-template-columns. Since masonry-direction defaults to column, setting this property is optional.

.masonry {
  display: masonry;
  grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
  gap: 10px;
}

Masonry layout where all columns are the same size. — View the same size columns demo here

For a row-based masonry container instead, use display:masonry, define your row sizes using grid-template-rows, and then set masonry-direction:row.

.masonry {
 display: masonry;
 masonry-direction: row;
 grid-template-rows: repeat(auto-fit, minmax(160px, 1fr));
 gap: 10px;
}

Masonry layout where all rows are the same size. — View the same size rows demo here

As you may have noticed, this syntax diverges slightly from the original proposal from Google. Regardless of the trigger used for CSS Masonry, the CSS Working Group resolved to reuse the grid template sizing and placement properties within CSS Masonry layout.

Although this allows for greater property reuse between layout types, you might find it confusing, and we'd love to hear from you on the subject. We may explore creating more generic aliases for properties like grid-template-columns and grid-template-rows, such as template-columns or template-rows, which could be used for both grid and masonry.

Use the default track size

With a new display type comes an opportunity to rethink property defaults.

In grid, grid-template-columns and grid-template-rows default to none which, as currently defined, normally results in a single column or row. For masonry, this default would, more often than not, result in an undesirable layout.

The implementation in Chromium adds the newly proposed definition for none, which will replace the default track size in CSS masonry. This new default track size is the repeat(auto-fill, auto) value. This value creates a nice masonry layout without having to define track sizes at all:

.masonry {
  display: masonry;
  gap: 10px;
}

Masonry layout with auto-sized columns. — View the default track size demo here

As shown in the image, the masonry container creates as many auto-sized columns as will fit into the available space.

With CSS grid, all items are placed before the tracks are sized, which means that this track auto sizing definition is not possible. However, with CSS masonry, this restriction no longer applies, as placement and sizing are intertwined and simplified. With this restriction lifted, this allows us to supply a more useful track default size for masonry layouts.

Try the `masonry` shorthand property

As mentioned before, the current implementation in Chromium relies on the grid-template-* properties to define the masonry track in your layout. However, because masonry has one dimension only, we've also implemented the masonry shorthand property, which you can use to define both the masonry direction and the track definition in one go, without the confusing grid- prefixed property.

For example, the following two code snippets will create equivalent CSS masonry containers.

.masonry {
 display: masonry;
 masonry: "a a b" 50px 100px 200px row;
}

.masonry {
  display: masonry;
  masonry-direction: row;
  grid-template-rows: 50px 100px 200px;
  grid-template-areas: "a" "a" "b"
}

Masonry layout with three rows that get progressively larger. — View the masonry shorthand demo here

The masonry shorthand is still under discussion by the CSS Working Group. Give it a try today and let us know what you think.

Go with custom track sizes

When it comes to defining track sizes, masonry is as flexible as grid in letting you fine tune the number and sizes of the layout tracks. Masonry tracks don't all have to be the same size either, for example:

.masonry {
 display: masonry;
 masonry: repeat(2, 3rem) repeat(auto-fit, 5rem) 12rem;
}

Masonry layout with various different track sizes. — View the custom track sizes demo here

In this example, we're defining two first 3rem tracks, followed by a varying number of 5rem tracks, followed by a single 12rem track.

Span multiple tracks

In masonry, items don't have to be constrained to the tracks they're placed in as they can span multiple tracks if needed. This can be very useful when some items are more important than others and require more room.

For example:

.masonry {
  display: masonry;
  masonry: repeat(auto-fill, minmax(12rem, 1fr));
}

.important-item {
  grid-column: span 2;
}

Masonry layout with items spanning multiple tracks. — View the span multiple tracks demo here

You can also use this ability to span multiple tracks to make certain items the entire length of the container:

.masonry {
 display: masonry;
 masonry: repeat(auto-fill, minmax(12rem, 1fr));
}

.full-bleed {
 grid-column: 1 / -1;
}

This is what the news site demo uses to display the subscription ad within the articles.

News site layout with a banner spanning the whole area.

Fine tuning masonry item placement

In CSS Masonry, items are placed in the column or row that has the shortest running position.

Imagine a two column masonry container. If the container has a 110px high item in the first column and a 100px high item in the second column, then a third item would be placed in the second column, where it would be 10px closer to the start of the masonry direction.

If you consider a 10px difference in running position to be small enough for your case, and prefer the third item to be placed in the first column instead, to better match source order, use the item-tolerance property.

The new item-tolerance property controls the sensitivity in item placement.

In the preceding example, you can apply item-tolerance: 10px; to your container to customize the variability in item placement:

.masonry {
  display: masonry;
  masonry: 200px 200px;
  gap: 10px;
  item-tolerance: 10px;
}

Note that the draft specification calls this property item-slack. The CSS Working Group recently resolved to use item-tolerance as the name instead, and the spec will be updated soon.

Other available properties

You can use the same template sizing and placement properties to size and place items in the grid axis of a masonry container as you can with CSS Grid, such as grid-row, grid-column, grid-area, grid-template-areas, or order. Experience the full power of CSS grid when creating your masonry layout.

Call for feedback

We can't wait for you to explore CSS masonry, get creative, and discover the new capabilities it can help you unlock. A great way to get started is to check our demos and their source code and start building your own examples in Chromium (remember to enable the flag first).

Your feedback is important in helping us shape the API and check that it's designed to meet your needs on the web. Give masonry a try and let us know what you think!

If you have thoughts or feedback on the shape of the API, let us know by commenting on Issue 11243 or, if you prefer to write a post on your own blog or on social media, be sure to let us know on X or LinkedIn.

CSS masonry is still being implemented in Chromium. If you do test it, be aware that we're still actively working on it and that you may encounter cases where it doesn't behave as expected. Some of the current limitations include dense packing, reverse placement, subgrid support, out-of-flow support, baseline support, DevTools support, fragmentation support, gap decoration support, among others.

If you find a bug while testing out the feature, share your feedback by opening a new Chromium bug.

Brick by brick: Help us build CSS Masonry Stay organized with collections Save and categorize content based on your preferences.