[css-grid-3][masonry] item-flow row vs. column in masonry layouts

[fantasai]

Following up on the adoption of item-flow in #11480 Unifying grid-auto-flow and flex-flow (see this WebKit blog post for an overview of item-flow if you want a refresher), one of the key questions was about the interpretation of its row and column values for masonry layout.

The core of this question is about whether the row and column values of item-flow represent the “shape” of the layout or the “flow” of the layout. In Flexbox, these two concepts coincide; and in Grid, the “shape of layout” is ambiguous while the keywords indicate the “flow” of the layout, so there's no conflict. But in masonry layout, they are opposite concepts. See this illustrated explanation of these concepts and how they apply to flex/grid/masonry.

This brings us to some concrete questions about the proposed CSS syntax for item-flow:

Question 1: For defining a masonry layout's orientation, should we:

• Use item-flow: column to represent waterfall layouts and item-flow: row to represent brick-wall layouts?
  • This would follow the “shape of layout” interpretation for these keywords, which is likely more obvious to most people at first glance.
  • In this case the initial value would differ between grid/flex (row) and masonry (column).
  • Switching a grid/flex layout to a similarly-flowing masonry layout or vice versa would mean inverting the item-flow value.
• Use item-flow: row to represent waterfall layouts and item-flow: column to represent brick-wall layouts?
  • This would follow the "flow of layout" interpretation for these keywords.
  • It creates a consistent "flow of layout" interpretation across grid/flex/masonry layouts, so switching between layout types (grid/flex/masonry) would maintain the overall direction of flow for a given value of item-flow.
  • But it breaks the expectation that row creates a visible “row” in the layout.
• Use item-flow: inline to represent waterfall layouts and item-flow: block to represent brick-wall layouts?
  • This would keep consistent a "flow of layout" interpretation across all three layout modes, while side-stepping the “shape of layout” expectation.
  • But the resulting keywords are inconsistent with the existing flex-flow and grid-auto-flow properties.
• Something else?

Question 2: If we go with the second or third approach, the item-flow longhands are very obviously item-direction and item-wrap, consistent with (and mapping directly to) flex-flow and grid-auto-flow. But if we go with the first approach (“shape of layout”):

• Does item-direction: row | column | row-reverse | column-reverse and item-wrap: wrap | wrap-reverse still make sense?
• What does item-direction: row-reverse or item-wrap: wrap-reverse mean in this case, i.e. which one reverses what?
• Do we need different names for these properties so that they make sense when shared across grid/flex and masonry? E.g. item-track and item-cross were proposed as a possibility. If so, is this inconsistency with the existing flex-flow longhands an acceptable cost?

Note that regardless, the default masonry layout will be a “waterfall” layout, i.e. the declared grid tracks are columns, and items are placed across and then down, so it's really only in the case of “brick-wall” layouts that a keyword would need to be specified.

There's some existing discussion on these questions in the previous issue but I wanted to pull out these questions to get thoughts from people other than me and Tab, particularly from our Invited Experts, others working as CSS authors and educators, and from people outside the CSSWG.

[alisonmaher]

For question 1, the first option makes the most intuitive sense to me.

For question 2, what does item-wrap: wrap-reverse mean in grid? I guess we essentially start filling the last track first, and then item-direction determines the order of items in each row?

In my mind, for masonry, item-direction: row-reverse meant reversing what direction we apply the auto placement cursor search in, which I suppose would have the same effect in masonry as filling the last track first as would be implied by item-wrap: wrap-reverse. So, I wonder if in masonry, these two would just result in the same behavior?

[fantasai]

@alisonmaher In Flexbox, row-reverse means place items in reverse order within the rows, and wrap-reverse means rows stack in reverse. So for English, row-reverse is right-to-left placement of items, and wrap-reverse is bottom-to-top stacking of rows. It would be the same in grid: row-reverse is right-to-left placement of items, and wrap-reverse is bottom-to-top stacking of rows.

In masonry, if we go with option 2, the behavior is exactly analogous: row-reverse places items right-to-left instead of left-to-right across the columns, and wrap-reverse stacks them up instead of down.

If we go with option 1, where column creates a waterfall layout, does column-reverse reverse the stacking order within the column, or reverse the placement order across columns? Whichever it does, wrap-reverse should presumably control the opposite axis. But also then starts to feel a bit confusing, imho...

[fantasai]

Oh! I also wanted to note one unexplored idea that came up in earlier discussions, which may or may not impact this discussion: potentially renaming item-flow to simply flow and the item-* directions to flow-*. E.g. flow-direction, flow-wrap, flow-tolerance, etc.

[tabatkins]

[re: indicating "waterfall" masonry using 'column'] Switching a grid/flex layout to a similarly-flowing masonry layout or vice versa would mean inverting the item-flow value.

I don't think this is a meaningful downside. A Flexbox, especially, won't look anything like a "similarly-flowing" Masonry - a row Flexbox and a "waterfall" masonry just look completely different from each other past the first few items. You'll need to do a lot more adjustments if you're swapping your page from one to the other, so having to change this value too isn't really a pain. You'll just be restyling from scratch regardless.

Not to mention, we wanted the initial value of this property to be an "auto" anyway, so Masonry could resolve that to vertical or horizontal depending on whether you'd set grid-template-columns or grid-template-rows. So you wouldn't necessarily have set the propery under Masonry anyway, only under Flex.

On the other hand...

[re: indicating "brick" masonry using 'column'] But it breaks the expectation that row creates a visible “row” in the layout.

Yeah, that's a pretty darn significant expectation to break, I think. A 'row' keyword should produce a row, a 'column' keyword should produce a column. If you set up a 'column' masonry, you should use 'grid-template-columns' to define the tracks, and 'grid-column' to set their spans or explicitly place them when needed. Anything else would be deeply, deeply confusing to authors.

---

Does item-direction: row | column | row-reverse | column-reverse and item-wrap: wrap | wrap-reverse still make sense?

I don't think it's great, no. Masonry simply doesn't have a reasonable 'wrap' concept; that's fine for the value space (we can just ignore the wrap-ness of the keywords), but having it expressed in the property name isn't great. This is why the spec has a different pair of words for that proposal.

There are other word pairs we could use; making the secondary property sufficiently generic without being just a nonsense word is kinda hard.

That said, I don't think it's the end of the world if we do end up using 'item-wrap'. It's not something you usually need to set. Especially if we use the suggested grammar, where wrap/nowrap is separated from the normal/reverse keyword, saying item-wrap: reverse in Masonry to indicate that they tie-break in the reverse direction (end to start) isn't terrible. We do end up with awkward naming sometimes, especially if there's an evocative mostly correct word that's nice and short, like wrap.

[alisonmaher]

If we go with option 1, where column creates a waterfall layout, does column-reverse reverse the stacking order within the column, or reverse the placement order across columns? Whichever it does, wrap-reverse should presumably control the opposite axis. But also then starts to feel a bit confusing, imho...

I was somewhat under the impression that we'd only ever want to reverse the placement across columns as opposed to within columns. If you allow items to be filled in from the bottom to the top, what happens if the masonry container has an indefinite size? Would we just keep normal ordering from top to bottom? And what happens if items overflow the container in that direction? Unlike flex, we wouldn't wrap to start a new column in that case, and it would be strange to me to overflow in the opposite direction.

Unless by "reverse the stacking order within the column" this means reverse the order that we process items in - that would be a possibility, as well, it just won't create the same effect as reversals in other layouts like flex.

[celestepan]

In masonry, if we go with option 2, the behavior is exactly analogous: row-reverse places items right-to-left instead of left-to-right across the columns, and wrap-reverse stacks them up instead of down.

Regardless of the naming, for implementations where we change the direction in which we're placing items across tracks (in columns, if we place items right-to-left, in rows, if we place items bottom-up), would we want to reverse the line names / line indices as well?

If we have 4 lines, would line 1 still be the left-most line, or would the right-most line become line 1?

[fantasai]

@celestepan That's a really good question, though a bit orthogonal to this one. Filed it as #12971.

[fantasai]

Slide deck illustrating this question: https://lists.w3.org/Archives/Public/www-archive/2025Oct/att-0013/CSSWG_2025_October_Masonry_Item_Flow.pdf