---
title: ""
category: foundations
status: recommended
url: https://specification.website/spec/foundations/theme-color/
updated: "2026-05-29"
sources:
- title: "MDN — "
url: "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name/theme-color"
publisher: "MDN"
- title: "HTML Living Standard — Other metadata names: theme-color"
url: "https://html.spec.whatwg.org/multipage/semantics.html#meta-theme-color"
publisher: "WHATWG"
- title: "W3C — Web App Manifest, theme_color"
url: "https://www.w3.org/TR/appmanifest/#theme_color-member"
publisher: "W3C"
source_repo: https://github.com/jdevalk/specification.website
licence: CC-BY-4.0
---
#
> Tints the browser chrome and OS surfaces to match your brand. Use the media attribute to ship one colour for light mode and another for dark mode.
## What it is
`theme-color` suggests a colour for the browser or OS to use when rendering surfaces around the page — the address bar on mobile, the title bar of an installed PWA, the task switcher card, and notification accents.
```html
```
The value is any valid CSS colour: hex, `rgb()`, `hsl()`, or a named colour.
## Why it matters
Mobile browsers render a thin strip above the page — the URL bar in Safari and Chrome on iOS and Android. By default it is grey or white. With `theme-color`, that strip can match your brand, so the page and the chrome around it look like one continuous surface.
The same value is used by:
- **iOS Safari** to tint the status bar area when scrolled.
- **Chrome on Android** for the address bar and the task switcher card.
- **PWAs and installed web apps** for the system title bar.
- **macOS Safari 15+** to tint the tab bar of the focused tab.
A page without `theme-color` is not broken, but the visual seam between page content and browser chrome is more obvious. With it, the page feels polished and "native-ish" on mobile.
## How to implement
Set one value for light mode and one for dark mode using the `media` attribute:
```html
```
Browsers pick the value whose `media` query matches the user's current colour scheme. If only one tag is present, it is used in every mode — fine for sites with a single fixed palette.
Pick colours that match the **edges** of your page, not the centre. The strip sits flush against your `` background; if your header is dark and the rest of the page is light, the theme colour should match the header.
For an installed PWA, the manifest's `theme_color` and `background_color` are used at launch. Set both for a smooth splash:
```json
{
"name": "The Website Specification",
"theme_color": "#0b1020",
"background_color": "#0b1020"
}
```
The manifest value is used once at install/launch time; the meta tag is consulted on every page load. They can differ if you want a different colour during the splash than during normal browsing, but matching them avoids a visible jump.
If your site updates colour scheme based on user choice (a theme switcher independent of OS), update the meta tag dynamically:
```js
document.querySelector('meta[name="theme-color"]').setAttribute('content', '#0b1020');
```
Some browsers re-read the tag on change; others cache it per navigation. Either way, server-rendering the correct initial value is the most reliable approach.
## Common mistakes
- A theme colour with low contrast against the address-bar text. Safari and Chrome render the URL in dark or light text based on the luminance of `theme-color`; an unreadable URL is a real bug.
- Setting only the dark-mode value, so light-mode users see the default grey.
- Forgetting to update the value when redesigning. The address bar starts looking off-brand months before anyone notices.
- Animating it on scroll. It is metadata, not a paint surface — leave it static.
- Putting hex values with alpha (`#0b1020aa`). Browsers ignore the alpha channel; use an opaque colour.
## Verification
- Open the site on iOS Safari or Chrome on Android. The address bar should be tinted to match your site.
- Toggle the OS between light and dark mode. The strip should change.
- Install the site as a PWA and check the title bar and splash screen colours.
- In DevTools, run `document.querySelector('meta[name="theme-color"]').content` and confirm the value.