← Back to blog

Painting under Safari's floating toolbar

  • Okay
  • Test
iOS Safari paints the space around your page itself. Here's what it samples, and how to color the status bar and toolbar separately.

My homepage ends in a soft gradient, and on iOS Safari it kept ending in a hard white band under the new floating toolbar. Fixing it took a surprising number of wrong turns, so here's what I learned.

The page doesn't go under the toolbar

I plugged an iPhone into my Linux box and attached Safari's Web Inspector with pymobiledevice3. The numbers were clear:

  • innerHeight, 100svh and 100dvh were all 796pt, ending above the toolbar.

  • Every env(safe-area-*) value was 0, even with viewport-fit=cover.

  • 100lvh was 836pt. That extra 40pt only appears once the page scrolls and the toolbar shrinks.

So nothing I drew could reach that strip: not the gradient, not a box-shadow hanging off the last section, not fixed elements. Sizing the page to 100lvh just made it scroll. Safari paints that area itself.

What Safari samples

Safari colors the two edges independently:

  • Under the toolbar, it uses the body's background color.

  • Behind the status bar, it uses the background color of a position: fixed element touching the top edge, read when the page first paints. Without one, it falls back to the body color too.

A gradient on the body doesn't help (Safari picks one color for both edges), and neither does a theme-color meta tag.

The fix

Two CSS variables, --page-bg-top and --page-bg-bottom, both defaulting to the page background:

  • The body takes --page-bg-bottom, and the app's root element paints the page's real background on top.

  • A 6px fixed element at the end of the body takes --page-bg-top. Its styles are inline so Safari sees them before stylesheets load.

  • The homepage sets --page-bg-bottom to its gradient's end color.

Now the status bar stays white, the toolbar sits on the gradient's color, and the page doesn't scroll. The lesson: on iOS 26, test on a device and measure before trusting what the CSS should do.

Further reading