Manifest theme_color and background_color

In one line: theme_color tints the browser’s address-bar, title-bar, and OS task-switcher entry to match your brand; background_color fills the splash screen shown between launch and first paint. Together they eliminate the “blank white flash” on startup and make the installed app feel coherent from the moment it opens.

Syntax

{
  "theme_color": "#1a1a2e",
  "background_color": "#1a1a2e"
}

Both members accept any valid CSS color value: named colors, hex, rgb(), hsl(), oklch(). Transparent values are not supported and fall back to the browser default.

What each member controls

Member	Controls
`theme_color`	Address-bar / title-bar tint (Android Chrome, desktop Edge/Chrome); OS task-switcher card background; install dialog accent
`background_color`	Splash screen background from launch until the CSS is parsed; also used as a fallback for the status-bar background on some Android versions

Relationship with `<meta name="theme-color">`

Chrome and Edge also read <meta name="theme-color" content="..."> in the page <head>. When both are present:

The <meta> tag takes precedence after the page loads.
The manifest theme_color is used before the page loads (splash screen, install dialog).
On Android, the <meta> tag can change the address-bar color dynamically per page; the manifest value is the fallback when no <meta> tag is present.

Best practice: set theme_color in the manifest to your primary brand color and mirror it in the <meta> tag so the two are consistent.

Dark-mode considerations

The manifest does not natively support separate theme_color values per color scheme. To handle dark mode:

Use the <meta> tag with media="(prefers-color-scheme: dark)" for dynamic switching after load:

<meta name="theme-color" content="#1a1a2e" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="#0d0d1a" media="(prefers-color-scheme: dark)">

Set the manifest theme_color to the value that works best for your primary / default color scheme, since it governs the pre-load splash screen.

background_color and the splash screen

The splash screen is shown by the OS (not the browser) between when a user taps the icon and when the first paint is ready. It typically shows:

The background_color as the screen fill.
The app icon (from icons) centered on the background.
The name or short_name below the icon (platform-dependent).

Match background_color to the page background in your <body> CSS to prevent a color flash when the splash screen transitions to the loaded page.

Platform support

Platform	`theme_color`	`background_color`
Android (Chrome)	Address bar, task switcher	Splash screen
Android (Samsung Internet)	Address bar	Splash screen
Windows (Edge)	Title bar	Splash screen
macOS (Chrome/Edge)	Not applied	Splash screen
iOS (Safari)	Not supported	Used for the startup image background

iOS Safari does not honour theme_color. Use <meta name="apple-mobile-web-app-status-bar-style"> for status-bar styling on iOS.

Practical checklist

theme_color matches your primary brand color.
background_color matches your page background to avoid a color flash on launch.
The <meta name="theme-color"> tag mirrors the manifest theme_color.
If your app supports dark mode, you have separate <meta> tags with media queries.
You have tested the splash screen on Android by launching from the home screen.
background_color provides sufficient contrast with the icon to keep it legible on the splash screen.