HTML Background
Pull past the top of a dark page in Safari and a white strip can appear behind it. The app is dark, but the document canvas is still white.
The canvas is the surface the browser paints behind the page. Use the Scroll button below to reveal both versions at once.
Wrong
Acme
Right
Acme
The document canvas
A wrapper only paints its own box. When it moves during overscroll, the canvas shows through. Set the background on the root element to paint that surface too.
Browsers normally use the body background when html is transparent.
Setting it on html directly makes the intended canvas color clear and does
not rely on that behavior.
Other edges
- Theme color: The
theme-colormeta tag can tint supported browser UI to match the page. Keep it in sync when the theme changes. - Overscroll:
overscroll-behavior: nonecan remove the bounce and stop scroll chaining. Use it carefully. The bounce is a familiar part of the platform. - Both themes: The root background must follow the active theme, or the white flash can return in one mode.
Usage
<html class="bg-background">html {
background-color: var(--background);
}Use the same background token for the root and the app. If the theme changes, that token should change with it.
Resources
HTML vs Body in CSS - A practical look at how the root and body elements behave.
Canvas backgrounds - How browsers paint the document canvas from the root or body.
overscroll-behavior - Control what happens when scrolling reaches a boundary.