Flexbox Masonry Layout (Explained with Math)

We’re going to get into building a somewhat unusual layout. It’s going to be multiple rows of differently sized elements, each with a known aspect ratio (like images), which span the full and exact width of the container.

We’re going to do this with flexbox in CSS and have a deep and very mathematical look at how it works.

How Does Flexbox Distribute Space?

It will be first useful to understand flexbox itself and how the different properties affect how the space is used.

.container {
  display: flex;
}Code language: CSS (css)

Flex Properties

Certain things go on the flex container itself.

.container {
  display: flex;
  flex-direction: row; /* Default. Could be "column" */
  gap: 1rem; /* size of the space between items */
  flex-wrap: wrap; /* Allows items to wrap. Default is "nowrap" */
}Code language: CSS (css)

Some important properties get applied to the items inside the container. These are a bit trickier to understand and use.

.container {
  ...

  > .item {
     flex-basis: 100px; /* The size of the item before growing or shrinking happens. */
     flex-grow: 1; /* Factor that decides how much of the remaining space the item receives. */
     flex-shrink: 1; /* Factor that decides how much of the exceeding space the item loses. */
  }
}Code language: CSS (css)

Assumptions and Simplifications

The full flexbox algorithm defined in the specification is more complex than the model we’re about to get into. Layout is complicated! I want to focus specifically on space distribution here, so to keep things focused, were going to ignore a few aspects of flexbox layout for now.

The things we’re ignoring are:

The min-width and max-width (or height, or the logical property equivalents) on items.
The algorithm is described as a single distribution step, while the specification says it may redistribute when items reach size limits.
We’re only considering a flex container with flex-direction: row and where the main axis is horizontal.

Conceptual Model

The process for distributing space in the row works as follows.

Initial Free Space

The first step is to determine how much space is available or unavailable in the row. The initial free space is the flex container width minus the sum of the flex-basis of all items in the row and minus the gaps between them.

Positive Initial Free Space (Growing)

If the initial free space is positive, items grow to fill the container:

If the sum of the flex-grow of all items in the row is less than 1, the free space is scaled by this sum. This means less of the total free space will be distributed, and items will not fill the container.
The free space is distributed among items, proportional to their flex-grow values.

Negative Free Space (Shrinking)

If the initial free space is negative, items shrink to fit the container:

If the sum of the flex-shrink of all items in the row is less than 1, the free space is scaled by this sum. This means less of the total free space will be distributed, and items will overflow the container.
Each item has a scaled-flex-shrink, calculated as flex-shrink multiplied by flex-basis. This ensures smaller items aren’t reduced to zero before larger ones shrink noticeably.
The negative free space is distributed among items, proportional to their scaled flex-shrink values. Items with larger scaled-flex-shrink receive more of the negative space and therefore shrink more.

What About Wrapping?

Without wrapping, all items remain in a single row.
With wrapping enabled, each row contains as many items as fit, including gaps. Items that don’t fit move to the next row. The grow or shrink distribution described above is applied independently to each row.

Mathematical Model

Now let’s formalize what we described conceptually, in mathematical terms. We first define the variables:

w_i \quad \text{final width of item } i

FB_i \quad \text{flex-basis of item } i

FG_i \quad \text{flex-grow of item } i

FSH_i \quad \text{flex-shrink of item } i

IFS \quad \text{initial free space}

n \quad \text{number of items in a row}

Initial free space is:

IFS = ContainerWidth – \sum_{i=1}^{n} FB_i – GapWidth \cdot (n – 1)

If initial free space is positive, the item width is:

w_i = FB_i + IFS \cdot \frac{FG_i}{\sum_{k=1}^{n} FG_k} \cdot \min\left(1, \sum_{k=1}^{n} FG_k\right)

If initial free space is negative, the item width is:

w_i = FB_i + IFS \cdot \frac{FSH_i \cdot FB_i}{\sum_{k=1}^{n} FSH_k \cdot FB_k} \cdot \min\left(1, \sum_{k=1}^{n} FSH_k\right)

Again, what about Wrapping?

Without wrapping, n is just the number of items. With wrapping enabled, the number of items in a row is the maximum n such that:

\sum_{i=1}^{n} FB_i + GapWidth \cdot (n – 1) \leq ContainerWidth

And that’s a wrap! Now we can more or less grasp how flexbox actually works.

The Masonry Layout

Now that we know how flexbox works, we can come back to our objective: a layout consisting of items, each with a known aspect ratio, disposed in rows, with items in the same row sharing the same height, and each row spanning the full width of the container.

Layout Constraints

A. Each item having an aspect ratio:

AR_i = \frac{w_i}{h_i}

Which can be rewritten as:

w_i = AR_i \cdot h_i \qquad \text{or} \qquad h_i = \frac{w_i}{AR_i}

B. Each row spanning the full width of the container:

\sum_{i=1}^{n} w_i = ContainerWidth

C. Each item in the same row sharing the same height:

h_i = H \quad \text{for every } i

Combining the constraints — plug C into A:

w_i = AR_i \cdot H

Plug the above into B:

\sum_{i=1}^{n} AR_i \cdot H = ContainerWidth

H can be taken outside the summation:

H \cdot \sum_{i=1}^{n} AR_i = ContainerWidth

Divide by:

\sum_{i=1}^{n} AR_i

H = \frac{ContainerWidth}{\sum_{i=1}^{n} AR_i}

Voilà, this last expression tells us that an H always exists such that it respects the layout constraints.

Plugging the Constraints into the Flexbox Model

A. Because each item has an aspect ratio:

h_i = \frac{w_i}{AR_i}

B. For each row to span the full width of the container we need:

\min\left(1, \sum_{j=1}^{n} FG_j\right) = 1 \qquad \text{and} \qquad \min\left(1, \sum_{j=1}^{n} FSH_j\right) = 1

We can guarantee that by putting:

FG_i \geq 1 \qquad \text{and} \qquad FSH_i \geq 1 \quad \text{for every } i

We use the first two constraints: apply B to the flexbox item final widths and plug that into A.

h_i = \frac{FB_i}{AR_i} + IFS \cdot \frac{FG_i}{AR_i \cdot \sum_{k=1}^{n} FG_k} \qquad \text{and} \qquad h_i = \frac{FB_i}{AR_i} + IFS \cdot \frac{FSH_i \cdot FB_i}{AR_i \cdot \sum_{k=1}^{n} FSH_k \cdot FB_k}

Now only the last constraint remains, each item in the same row sharing the same height.

The approach here will be to try to make each term constant independently of the item.

\frac{FB_i}{AR_i}

That is the first term. We can put ${FB}_{i}$ equal to ${AR}_{i}$ so it simplifies with the denominator. Additionally, we can multiply it by a constant α:

FB_i = AR_i \cdot \alpha

Plug the just-defined FB_i into the first term:

\frac{AR_i \cdot \alpha}{AR_i} = \alpha

Because ${FB}_{i}$ is the width of the item before growing and shrinking happens, and because w_i = ${AR}_{i}$ • h_i (from constraint A), we can see that α is the height of the item before growing and shrinking happens. And because it is the same for every item, we can conclude that for our layout to work, all the items must start at the same height.

Rename α to $CB$ (cross-basis) so:

FB_i = AR_i \cdot CB

$IFS$ is the second term. If we think about it or look back at its expression, we can see that it’s already constant for items in a row.

After plugging the just defined ${FB}_{i}$ into the third term, it becomes:

\frac{F G_i}{A R_i \cdot \sum_{k=1}^n F G_k} \quad \text { or } \quad \frac{F S H_i \cdot A R_i \cdot C B}{A R_i \cdot \sum_{k=1}^n F S H_k \cdot A R_k \cdot C B}=\frac{F S H_i}{\sum_{k=1}^n F S H_k \cdot A R_k} \quad(\text { for } C B>0)

Depending on if $IFS$ is positive or negative respectively.

For positive ${FB}_{i}$ , we can put ${FG}_{i}$ equal to ${AR}_{i}$ • β, with β being a constant of choice.

FG_i = AR_i \cdot \beta

Plug the just defined ${FG}_{i}$ into the third term:

\frac{AR_i \cdot \beta}{AR_i \cdot \sum_{k=1}^{n} AR_k \cdot \beta} = \frac{1}{\sum_{k=1}^{n} AR_k}

We can see that β simplify away, and only remains 1 divided by the sum of aspect ratio, which is constant.

In constraint B we put ${FG}_{i}$ ≥ 1, that now translates to choosing a β big enough such that ${AR}_{i}$ • β ≥ 1 for every item.

For negative $IFS$ , we can push ${FSH}_{i}$ = 1 so it’s constant and respects constraint B ( ${FSH}_{i}$ ≥ 1).

The third term becomes:

\frac{1}{\sum_{k=1}^{n} AR_k}

Results

That’s it! We found some simple enough solutions. So to keep going here, for both positive and negative $IFS$ :

h_i = H = CB + \frac{IFS}{\sum_{k=1}^{n} AR_k}

w_i = FB_i + IFS \cdot \frac{AR_i}{\sum_{k=1}^{n} AR_k}

FG_i = AR_i \cdot \beta \quad \text{such that} \quad FG_i \geq 1 \text{ for every } i

FSH_i = 1

FB_i = AR_i \cdot CB \quad

$CB$ is a constant of choice, representing the cross-basis, meaning the height of the item before growing or shrinking happens.

The Intuition

All items start at the same height thanks to flex-basis.

When flex-grow is tied to an items aspect ratio, wider items expand more in width than narrower ones. On the flip side, with flex-shrink set to 1, items shrink in proportion to their width, so wider items lose more space than narrow ones.

Even though widths change at different rates, the height of all items changes evenly.

The result is that no matter the aspect ratio of the items, they end up the same height.

Demos

No wrapping:

With wrapping:

With limits:

With images: