Theme color meta tag - MetricSpot docs

Q: What happens on browsers that don't support it?

Nothing. Browsers that don't understand ignore it silently. There's no performance penalty and no broken layout — it's an additive enhancement.

What this check does

Scans the document <head> for one or more <meta name="theme-color"> tags. The check passes when at least one is present with a valid CSS color. It also recognises media-query variants (media="(prefers-color-scheme: light)" and media="(prefers-color-scheme: dark)") so you don’t get penalised for shipping a proper light/dark pair.

Why it matters

theme-color colors UI surfaces the browser controls on your behalf:

Chrome on Android tints the address bar and the status bar above it.
Safari on iOS (15.4+) tints the top of the viewport when the page scrolls beneath the notch.
Installed PWAs use it for the title bar on Android and the splash screen background.
Edge on desktop uses it for the tab strip when the site is in a Progressive Web App window.
Slack, Discord, and some chat clients read it when rendering link previews for installed-app contexts.

This isn’t a ranking signal and it doesn’t affect Lighthouse performance. It’s a polish signal — a site that ships it looks intentional, and a site that doesn’t looks like a default WordPress install. The fix takes thirty seconds.

It pairs naturally with the rest of the social and identity module: apple-touch-icon, favicon, and Open Graph core tags. Same theme: how the site presents itself outside the browser viewport.

How to fix it

Static value — pick your dominant brand color and put it in the document head:

<meta name="theme-color" content="#0a3d62">

Use a hex value (#0a3d62), rgb(), or any valid CSS color. Test it against both white and black text — Android renders the system clock and battery icons on top of your color, and a mid-saturation color usually works best.

Light + dark variants — modern browsers respect media-query overrides, so you can ship a pair that follows the user’s system theme:

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

This is the right default for any site that already supports a dark mode. Safari 15.4+ and Chrome 93+ honour it; older browsers ignore the variants and fall back to whichever tag comes first without a media attribute, so put your default last as a safety net:

<meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff">
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#0a0a0a">
<meta name="theme-color" content="#0a3d62">

Sync with your web app manifest. If you ship a manifest.webmanifest (any installable PWA does), keep its theme_color field in sync with the meta tag — installed apps prefer the manifest:

{
  "name": "Example",
  "theme_color": "#0a3d62",
  "background_color": "#ffffff",
  "display": "standalone"
}

Astro — add it once in your base layout src/layouts/Base.astro:

<head>
  <meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff">
  <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#0a0a0a">
</head>

Next.js (App Router) — use the metadata API in app/layout.tsx:

export const metadata = {
  themeColor: [
    { media: "(prefers-color-scheme: light)", color: "#ffffff" },
    { media: "(prefers-color-scheme: dark)", color: "#0a0a0a" },
  ],
};

WordPress — add it via wp_head:

add_action('wp_head', function () {
  echo '<meta name="theme-color" content="#0a3d62">';
});

Audit it:

curl -s https://yourdomain.com/ | grep -i 'theme-color'

Then open the site on an Android Chrome device (or use Chrome DevTools → Device Mode → mobile preset) and look at the address bar — it should reflect your color.

Frequently asked questions

Does theme-color affect SEO or rankings?

No. Google doesn’t use it as a ranking signal. It’s purely a presentation cue picked up by mobile browsers and PWA hosts. The rule lives in MetricSpot’s Social module because it’s part of “how your site looks when consumed outside the viewport” — same family as Open Graph images and favicons.

What happens on browsers that don’t support it?

Nothing. Browsers that don’t understand <meta name="theme-color"> ignore it silently. There’s no performance penalty and no broken layout — it’s an additive enhancement.

Can I change theme-color from JavaScript?

Yes, and it’s animated on the fly by Chrome and Safari. Useful for sites with section-specific colors:

document.querySelector('meta[name="theme-color"]')
  .setAttribute('content', '#ff0066');

Be tasteful — flipping the color on every scroll event is dizzying. Section-level changes (hero vs. content vs. footer) work well; per-scroll changes don’t.