Web App Manifest: theme_color / background_color

Web App Manifest: theme_color / background_color — The theme_color member sets the color an installed PWA’s surrounding UI (such as the title bar or task switcher) uses, and the background_color member sets the background color shown behind the page while it loads. Per the specification, the browser fetches and processes the manifest on every page load, and when processing succeeds it MAY apply the updated color to the current and future application contexts associated with the app — these members are not fixed once at install time.

Browser & ecosystem support

Support is not uniform across the two members on every engine. Per MDN’s browser-compat-data, Chrome, Edge, and Firefox for Android support both members, desktop Firefox supports neither, and Safari supports theme_color (macOS Safari 17, iOS Safari 15) but does not implement background_color at all.

• Legend
• Yes
• Partial
• Flag
• No
• Unknown

Browser / Platform	Support	Versions	Confidence	Source	Notes
Chrome (Desktop)	Yes	46	high	source	1
Chrome (Android)	Yes	46	high	source	23
Edge (Desktop)	Yes	79	high	source	45
Firefox (Desktop)	No	—	high	source	67
Firefox (Android)	Yes	79	high	source	8
Safari (macOS)	Yes	17	high	source	9
Safari (iOS)	Yes	15	high	source	10
Samsung Internet	Yes	5.0	high	source	1112
WebView (Android)	Yes	46	high	source	1314
Chrome (Desktop)	Yes	46	high	source	15
Chrome (Android)	Yes	46	high	source	1617
Edge (Desktop)	Yes	79	high	source	1819
Firefox (Desktop)	No	—	high	source	2021
Firefox (Android)	Yes	79	high	source	22
Safari (macOS)	No	—	high	source	2324
Safari (iOS)	No	—	high	source	252627
Samsung Internet	Yes	5.0	high	source	2829
WebView (Android)	Yes	46	high	source	3031

1. Covers the `theme_color` entry.
2. Covers the `theme_color` entry.
3. Derived by browser-compat-data mirroring from Chrome.
4. Covers the `theme_color` entry.
5. Derived by browser-compat-data mirroring from Chrome.
6. Covers the `theme_color` entry.
7. No Firefox support is recorded in browser-compat-data.
8. Covers the `theme_color` entry.
9. Covers the `theme_color` entry.
10. Covers the `theme_color` entry.
11. Covers the `theme_color` entry.
12. Derived by browser-compat-data mirroring from Chrome Android.
13. Covers the `theme_color` entry.
14. Derived by browser-compat-data mirroring from Chrome Android.
15. Covers the `background_color` entry.
16. Covers the `background_color` entry.
17. Derived by browser-compat-data mirroring from Chrome.
18. Covers the `background_color` entry.
19. Derived by browser-compat-data mirroring from Chrome.
20. Covers the `background_color` entry.
21. No Firefox support is recorded in browser-compat-data.
22. Covers the `background_color` entry.
23. Covers the `background_color` entry.
24. No Safari support is recorded in browser-compat-data.
25. Covers the `background_color` entry.
26. No Safari on iOS support is recorded in browser-compat-data.
27. Derived by browser-compat-data mirroring from Safari.
28. Covers the `background_color` entry.
29. Derived by browser-compat-data mirroring from Chrome Android.
30. Covers the `background_color` entry.
31. Derived by browser-compat-data mirroring from Chrome Android.

Source data: /compatibility/manifest-theme-background-color.json · Global usage: 83 % (StatCounter 2026-05)

Source: spec · MDN · Last verified 2026-10-03 · Confidence: high (computed from sources)

How to use it

{
  "name": "Example PWA",
  "theme_color": "#317EFB",
  "background_color": "#ffffff"
}

Declaring theme_color as progressive enhancement, not feature detection

The specification and MDN document theme_color and background_color as manifest declarations. For theme_color, MDN documents a <meta name="theme-color"> element as a separate, per-document way to set the same UI color. Declaring both the manifest member and the meta tag is a progressive-enhancement pairing: it doesn’t detect anything, but it gives engines that don’t read theme_color from the manifest another way to pick up the same value if they support the meta tag.

The specification and MDN state that a user agent may override the manifest’s background_color to support prefers-color-scheme. Engines that don’t implement it fall back to their own user-agent-defined behavior for the loading/splash background rather than any behavior defined by the manifest spec.

function ensureThemeColorMeta(color) {
  const existing = document.querySelector('meta[name="theme-color"]');
  if (existing?.content) {
    // A meta tag is already present — leave it as the source of truth.
    return;
  }
  // Declare the meta tag as a progressive-enhancement pairing with the
  // manifest's theme_color member. This does not confirm any engine will
  // apply either one — see the compatibility table above for per-engine
  // support.
  const meta = document.createElement('meta');
  meta.name = 'theme-color';
  meta.content = color;
  document.head.appendChild(meta);
}

Practical checklist

• Per MDN, a <meta name="theme-color"> element (optionally combined with a prefers-color-scheme media query) overrides the manifest’s theme_color for that document — the manifest value is only the default.
• Per MDN, background_color is a temporary color shown before the page’s stylesheet loads (and for some splash screens); once the stylesheet loads, its background takes over.
• Per the manifest spec, both members must be a CSS <color> value that parses and resolves to a color convertible to sRGB — this permits lab(), color(display-p3 …), and other predefined color spaces, not only legacy hex/RGB/named colors. CSS custom properties and gradients are not <color> values and are not valid here.
• Per MDN, theme_color’s alpha channel may be ignored by the browser, so don’t rely on a semi-transparent theme_color actually rendering as transparent; MDN does not document the same alpha restriction for background_color.
• Safari does not implement background_color at all, so do not rely on it there even though theme_color is supported.

Where to go next

• Web App Manifest: display
• Web App Manifest: icons

← Back to the Compatibility explorer.