0x0: Introduction#

When I was working on the Trackmaker project, the overflow behaviour of grid kept biting me. I had a side panel that was supposed to scroll, and instead it kept stretching the whole page. I added overflow-y: auto in a few places, nothing happened, and I started guessing.

The fix turned out to be one line on a wrapper, not on the panel. This note is what I wish I had at the time.

CSS is awesome! link

The short version: overflow needs a box with a bounded size. Grid and flex items have a content-based minimum that can stop that from happening. Setting overflow on the item itself removes that minimum, so min-width: 0 and min-height: 0 are usually for the non-scrolling wrappers around the scroller, not for the scroller itself.

0x1: The box model and what overflow means#

An element is made up of content, padding, border, and margin.

From “The box model”, mdn web docs. link

width and height set the size of the content box by default. With box-sizing: border-box they set the size up to the border instead, so padding eats into the room left for content. Either way, once that size is fixed, content can still be larger.

overflow does not change whether content is too big. It only changes what the browser does with the extra part:

• visible paints it outside the box.
• hidden clips it. It also makes the box a scroll container, so you can still scroll it with script, focus, or scrollIntoView.
• scroll clips it and always shows a scrollbar. On platforms with overlay scrollbars, the scrollbar may only appear while you scroll.
• auto clips it and shows a scrollbar only when needed.
• clip clips it without making the box scrollable. That difference matters when grid or flex sizing is involved.

0x2: How the browser decides something has overflowed#

It helps to think of layout as two passes.

First the browser works out how big each box is. For a plain block this comes from width, height, and the parent. For flex and grid it comes from flex sizing or track sizing, plus min-width, max-width, min-height, max-height.

Then it lays out the children and builds what the spec calls the scrollable overflow area. Roughly, that is the union of the box’s own content and anything sticking out of it: long words, wide images, absolutely positioned descendants whose containing block is the box or a descendant of it, text with white-space: nowrap, and so on. Each child contributes its border box plus some extra cases like text shadows and floats.

The scrollable overflow area can be larger than the padding box even when overflow is visible.

If that overflow area is larger than the padding box, the box overflows. That is true even with overflow: visible. The property kicks in after the fact. It picks between painting the extra part, clipping it, or turning the box into a scroll container.

This is why overflow: auto sometimes looks broken. You added the scrollbar rule, but the box grew to fit the content, so from the browser’s point of view nothing overflowed. If nothing overflows, no scrollbar appears.

A few things that tend to make the content side larger than people expect:

• white-space: nowrap stops text from wrapping, so the min content size becomes one very long line.
• Replaced elements like img or video keep an intrinsic width unless you constrain them with max-width: 100%.
• A block with width: auto fills the space it is given, but when it is a grid or flex item, its minimum size comes from its contents. A long unbreakable string or a wide nested grid can push that minimum up.

1
.card {
2
  width: 200px;
3
  height: 100px;
4
  overflow: hidden;
5
}

1
.card {
2
  width: auto;
3
  height: auto;
4
  overflow: visible;
5
}

In the first block the box stays 200 by 100 and extra content gets clipped. In the second the box grows with content, so nothing counts as overflow.

0x3: The automatic minimum in grid and flex#

Flex items and grid items default to min-width: auto and min-height: auto. In practice, auto here means “no smaller than my content.” The browser takes the min-content size of what is inside (the longest word, the image width, the nested track) and uses it as a floor.

There is an exception that the usual explanations skip: a scroll container’s automatic minimum is 0. In flexbox this applies to the main axis; in grid it applies on both axes. So an item with overflow: hidden, auto, or scroll on itself already has no content floor. It can shrink, and the overflow rule then clips or scrolls what does not fit.

That is why the common advice sounds contradictory. min-width: 0 is not needed on the element that has overflow: auto. It is needed on a non-scrolling wrapper whose overflow is still visible, so that a scroller inside it gets a bounded box.

overflow: clip is the odd one out. It clips, but it does not create a scroll container, so it does not remove the content floor. A grid item with overflow: clip can still grow its track. If you want clipping and shrinking without a scroll container, pair clip with min-width: 0 or min-height: 0.

When the automatic minimum is content-based, the item can grow its track or container.

Grid adds one more twist. 1fr is shorthand for minmax(auto, 1fr). That leading auto is the same automatic minimum. So a track written as 1fr will not go narrower than the content of the items placed in it, unless you tell it otherwise or the item is a scroll container.

Say you have this:

1
.grid-container {
2
  display: grid;
3
  grid-template-columns: 200px 1fr;
4
}
5

6
.grid-item {
7
  /* overflow: visible by default */
8
}

If the second column holds a long URL or a wide table, the item reports a large min-content size. The 1fr track stretches to honor it. The page gets a horizontal scrollbar instead of the column getting one.

If the item itself should scroll, overflow is enough:

1
.grid-item {
2
  overflow-x: auto;
3
}

The item becomes a scroll container, its automatic minimum becomes 0, and the track stays at its share of the width. No min-width: 0 needed.

If the scroller is a child of the item, the item keeps its content floor and needs the override:

1
.grid-item {
2
  min-width: 0;
3
}
4

5
.grid-item .scroller {
6
  overflow-x: auto;
7
}

Same story vertically:

1
.app {
2
  display: grid;
3
  grid-template-rows: auto 1fr;
4
  height: 100dvh;
5
}
6

7
.panel {
8
  /* overflow: visible by default */
9
}
10

11
.list {
12
  overflow-y: auto;
13
}

If the row is auto sized, it grows with the content by design. If it is a 1fr row but the panel has its automatic minimum intact, the panel grows the row instead of letting the list scroll. Put the zero minimum on the panel:

1
.panel {
2
  min-height: 0;
3
}

Or let the panel itself be the scroller:

1
.panel {
2
  overflow-y: auto;
3
}

Then min-height: 0 is redundant.

Flex behaves the same way, with one precision: the automatic minimum is special on the main axis. In a row, min-width: auto is the content floor; min-height: auto is not. A flex item with flex: 1 and an inner scroller needs min-width: 0:

1
.flex-container {
2
  display: flex;
3
  width: 300px;
4
}
5

6
.flex-item {
7
  flex: 1;
8
  min-width: 0;
9
}
10

11
.flex-item .scroller {
12
  overflow-x: auto;
13
}

If .flex-item itself has overflow-x: auto, it is a scroll container and the min-width: 0 is unnecessary.

Other sizing knobs still apply. flex-basis sets the starting size before growing and shrinking. min-width and max-width win over it. Content-based tracks like auto, min-content, and max-content grow with content by design, so expect overflow there to paint outward unless you clip it:

1
.grid-container {
2
  display: grid;
3
  grid-template-columns: max-content;
4
}
5

6
.grid-item {
7
  overflow: visible; /* content paints outside the grid area */
8
}

Nested layouts stack the problem. A grid inside a flex item, or a flex column inside a grid row, carries its own automatic minimum at each level:

1
.app {
2
  display: grid;
3
  grid-template-rows: auto 1fr;
4
  height: 100dvh;
5
}
6

7
.middle {
8
  /* overflow: visible, and no min-height: 0 */
9
}
10

11
.inner-grid {
12
  display: grid;
13
  grid-template-rows: auto 1fr;
14
  height: 100%;
15
}
16

17
.list {
18
  overflow-y: auto;
19
}

Without min-height: 0 on .middle, the middle box grows to its content height. The inner grid never gets a bounded height, so the list never scrolls. If any non-scrolling ancestor in the chain refuses to shrink, the inner scroller never sees a bounded box.

0x4: Where min-width: 0 and min-height: 0 actually go#

Setting min-width: 0 or min-height: 0 removes the content-based floor on a box that is not already a scroll container. The box may now be narrower or shorter than its contents. On its own, that only bounds the box; the content still paints outside unless the box also has overflow set to clip or scroll.

It helps to separate the two jobs:

• min-width: 0 or min-height: 0 removes the floor.
• overflow: auto, hidden, scroll, or clip decides what happens to the content that no longer fits.

The scroller does both jobs with overflow alone. A wrapper only does the first job.

Here is the horizontal case with the scroller inside the item:

1
.grid-container {
2
  display: grid;
3
  grid-template-columns: 1fr 1fr;
4
  width: 200px;
5
}
6

7
.grid-item {
8
  min-width: 0;
9
}
10

11
.grid-item .scroller {
12
  overflow: hidden;
13
}

Without min-width: 0, a long word forces the track wider than 200px. With it, the item stays in its cell and the inner scroller clips the extra text.

If the item itself is the scroller, the same markup needs one rule, not two:

1
.grid-item {
2
  overflow: hidden;
3
}

overflow: hidden makes the item a scroll container, so its automatic minimum is already 0, and it clips the content. Adding min-width: 0 here is harmless but redundant. That is the part I had backwards for a while.

The vertical case is where I got stuck in Trackmaker. I had a full height app shell, a header plus a 1fr row, and a list inside that row that should scroll:

1
.app {
2
  display: grid;
3
  grid-template-rows: auto 1fr;
4
  height: 100dvh;
5
}
6

7
.panel {
8
  /* overflow: visible */
9
}
10

11
.list {
12
  overflow-y: auto;
13
}

height: 100dvh bounds the grid. 1fr gives the second row the leftover space. But the panel reports its full content height as its minimum, the row grows past the viewport, and the page scrolls. With min-height: 0 on the panel, it accepts the row height, the list gets a bounded box, and overflow-y: auto scrolls inside:

1
.panel {
2
  min-height: 0;
3
}

If the panel itself has overflow-y: auto, the min-height: 0 is unnecessary. The panel is a scroll container, so its minimum is already zero. The version that actually bit me had the overflow on the list, with the panel still overflow: visible.

The zero minimum belongs on the non-scrolling wrapper, not on the scroller.

Two details I keep forgetting:

First, every non-scrolling wrapper between the bounded height and the scroller needs the override. If .panel contains another grid and the list is one more level down, that middle wrapper also needs min-height: 0. One stubborn ancestor is enough to stretch the whole chain.

Second, minmax(0, 1fr) on the track does the same job from the other side. grid-template-columns: minmax(0, 1fr) minmax(0, 1fr) replaces the implicit auto minimum with 0, so items in those tracks may shrink even if they still say min-width: auto. I put min-w-0 on each wrapper that contains the scroller, and use minmax(0, 1fr) when the whole track should be allowed to shrink.

In flex the fix reads the same:

1
.container {
2
  display: flex;
3
  width: 200px;
4
}
5

6
.item {
7
  flex: 1;
8
  min-width: 0;
9
}
10

11
.item .scroller {
12
  overflow: hidden;
13
}

Leave out min-width: 0 and the item pushes past 200px to fit its content. Put it back and the item holds at 200px and the inner scroller clips. If the item itself has overflow: hidden, the item is already a scroll container and the min-width: 0 is redundant.

So the rule I use: overflow needs a box with a bounded size to work against. In grid and flex, min-width: 0 or min-height: 0 keeps that bound intact on the boxes that are not scrolling. If the box that scrolls is the same box, overflow already does it.

0x5: The pattern I use now#

For a scrollable pane inside a grid cell, I write three things:

1. A bounded ancestor: a fixed height, h-screen, h-dvh, or a 1fr row inside one.
2. overflow-y: auto or overflow-x: auto on the element that should scroll.
3. min-height: 0 or min-width: 0 on every non-scrolling wrapper between the two.

In Tailwind that is usually min-h-0 on the wrappers and overflow-y-auto on the scroller. If the scroller is the direct child of the grid, overflow-y-auto alone is enough; min-h-0 on the same element is redundant.

Tailwind’s grid-cols-* utilities already generate repeat(n, minmax(0, 1fr)), so grid children rarely blow out in Tailwind. Flex children still need min-w-0 when the scroller is nested, because flex: 1 keeps the content-based minimum on the main axis.

If it still does not scroll, I walk up the tree and look for the ancestor that grew. It is almost always a wrapper with overflow: visible and no min-h-0 one level up.

0x6: Related behaviours worth knowing#

1
const el = document.querySelector(".panel");
2
console.log(el.scrollHeight > el.clientHeight); // is it overflowing?
3
console.log(getComputedStyle(el).minHeight); // what floor is in play?

0x7: Symptoms and fixes#

If the pane still does not scroll, the box that grew is the one to fix. It is usually one level above the scroller, with overflow: visible and no min-height: 0.