Why Does My Beautiful Dark Site Have White Bars on iPhone Safari?
Reading Time: 6 minutes TL;DR Summary: If your dark site looks great on desktop but shows ugly white bars or a light gradient at the top and bottom on iPhone Safari, it’s not your imagination. Safari is filling the browser chrome and “safe areas” with its default light color because you haven’t told it what to do. Fix it by: (1) giving html a dark background, (2) using viewport-fit=cover, and (3) setting a theme-color meta tag to match your design.
Table of Contents
- What You’re Seeing on iPhone Safari
- Why This Happens (Without Any Errors)
- The Three-Part Fix
- Example Code Snippet
- Optional Tweaks and Gotchas
- Glossary
What You’re Seeing on iPhone Safari
Here’s the situation:
- Your site has a nice dark background or gradient.
- On desktop, it looks perfect from top to bottom.
- On iPhone Safari, the middle of the page looks fine, but the very top and bottom have weird white or light gray areas. Sometimes it feels like a subtle gradient around the browser bars.
It feels broken, especially if you care about polish. One dark site looks “crisp and app-like,” another looks like Safari is trying to fade it into a white void. That’s exactly what’s happening: Safari is filling space you haven’t explicitly claimed.
This happened to me as I was building the OnYourMark.app game / website / web app. I kept seeing these white gradients and the top and bottom of the screen in Safari on my iPhone. The new CUE Broadcast website does this.
I then found another site that didn’t do that, so it got me wondering. Since On Your Mark is kind of dark mode type of design, the white gradients looked odd. I didn’t want them, and I figured out why. Read on to find out more.
Why This Happens (Without Any Errors)
There are three main moving parts here:
- Your page background (what
htmlandbodyare doing). - Safe areas on modern iPhones (notch, home indicator, overscroll bounce).
- Safari’s chrome (top and bottom bars) and its default color choices.
1. The body vs html background split
Many sites only set a background on body, like this:
body {
background: radial-gradient(circle at top, #0f172a 0, #020617 52%, #000000 100%);
}
That looks great in the main content area. But if the html element doesn’t have a background set, the browser can show something else (often light/white) in the overscroll area or around the safe regions at the very top and bottom.
On a dark site, that contrast is really obvious.
2. Safe areas and viewport-fit
Ever since the notch-era iPhones, you get “safe areas” at the top and bottom of the screen. By default, Safari plays it safe and doesn’t let your layout extend all the way into those zones unless you explicitly ask it to.
That’s what viewport-fit=cover is for:
<meta name="viewport"
content="width=device-width, initial-scale=1, viewport-fit=cover">
Without that, your layout is kind of boxed in and Safari handles the surrounding space using its own defaults, which often lean light.
3. Safari’s default chrome color
On mobile, browsers can tint their top and bottom bars to match the site using the theme-color meta tag. If you don’t set it, Safari picks its own color based on light/dark heuristics.
So if you have a dark gradient on body, but:
htmlhas no background, and- you don’t set
theme-color, and - you don’t use
viewport-fit=cover,
Safari fills the “extra” areas with white or a light gray. The result is those weird white bars or soft gradients at the top and bottom, even though your CSS looks fine at first glance.
The Three-Part Fix
The fix is simple and very copy-paste friendly. You just need to:
- Give
htmla solid dark background. - Tell Safari to use the full viewport with
viewport-fit=cover. - Set a
theme-colorthat matches your dark UI.
1. Darken the root background
In your main CSS file, right after your html, body reset, add a background color to html:
html, body {
margin: 0;
padding: 0;
height: 100%;
}
html {
background-color: #020617; /* or your main dark color */
}
Keep your existing gradient or background on body if you like. The key is that any extra space beyond the body (overscroll, safe-area zones, etc.) is now dark instead of white.
2. Use viewport-fit=cover
In your <head>, update your viewport meta tag:
<meta name="viewport"
content="width=device-width, initial-scale=1, viewport-fit=cover">
This tells iOS Safari: “Let my layout extend into the full screen. I’ll handle the safe areas myself.”
3. Set theme-color to match your design
Right after your viewport meta, add:
<meta name="theme-color" content="#020617">
This gives Safari a clear signal about how to tint its browser bars. On a dark site, this small line is the difference between “polished app-like UI” and “why is my beautiful dark site surrounded by white?”
Example Code Snippet
Here’s a minimal example you can adapt to your own site.
HTML <head> example
<head>
<meta charset="UTF-8">
<title>My Dark Site</title>
<meta name="viewport"
content="width=device-width, initial-scale=1, viewport-fit=cover">
<meta name="theme-color" content="#020617">
<link rel="stylesheet" href="/assets/css/app.css">
</head>
CSS example
html, body {
margin: 0;
padding: 0;
height: 100%;
}
html {
background-color: #020617;
}
body {
font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
background: radial-gradient(circle at top, #0f172a 0, #020617 52%, #000 100%);
color: #e5e7eb;
}
That combination usually fixes the white-bar problem on modern iPhones while keeping everything looking the same on desktop and other browsers.
Optional Tweaks and Gotchas
Light and dark mode support
If your site supports both light and dark themes, you can give mobile browsers different theme colors based on the user’s preference:
<meta name="theme-color"
content="#ffffff"
media="(prefers-color-scheme: light)">
<meta name="theme-color"
content="#020617"
media="(prefers-color-scheme: dark)">
That way the browser bars look right whether the user is in light or dark mode.
Don’t forget subpages and special layouts
It’s easy to fix the homepage and then forget:
- Admin pages
- Login screens
- Standalone “app-like” pages
If those use separate templates, make sure they also get the updated viewport and theme-color tags so they don’t fall back to the old behavior.
Test on a real device
Browser dev tools can simulate a lot, but the top/bottom bar behavior and overscroll color are things you really want to confirm on an actual iPhone if possible. Open the site, scroll, bounce a little, rotate the device. If everything stays dark and consistent, you’re in good shape.
Glossary of Terms Used in This Article
- Safe area
- The part of the screen that isn’t covered by the notch, sensor housing, or home indicator on modern phones. Browsers treat this differently unless you opt in with
viewport-fit=cover. - Browser chrome
- The UI around the web page itself: address bar, bottom toolbar, etc. On mobile, this can be tinted using
theme-color. theme-color- A meta tag that tells the browser what color to use for the top/bottom bars and sometimes other UI elements. Example:
<meta name="theme-color" content="#020617">. viewport-fit=cover- A viewport setting that allows your page to extend into the full screen area on iOS, including under the notch and home indicator. Without it, Safari keeps your layout inside a “safe” box and fills the rest with its own background.
- Root background
- The background of the
htmlelement. If you don’t set it, the browser may use a default color that doesn’t match your design.
If you’ve ever looked at your dark site on an iPhone and thought, “Why does it look washed out at the edges?”, you’re not alone. A couple small meta tags and one CSS rule are usually all it takes to make it feel like a proper, intentional mobile experience.
📄 Download a PDF of This Article
