Do you really need to set a theme color to color Safari's UI?

When it was announced that websites can change the color of Safari’s UI, I was eager to try it out. Seemed like an interesting new way to apply branding! And then I learned that several Android browsers had been supporting this for a while already—pretty nice!

Safari windows with UIs matching the colors of the websites they're showing.

The syntax to apply a theme color to a site and make the browser’s UI change is rather self explanatory. This is what I use in this site’s <head>:

<meta name="theme-color" content="#D3DADF" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="#232B32" media="(prefers-color-scheme: dark)">
<meta name="theme-color" content="#D3DADF">

Simple as it may be, getting the right colors on the right pages in all situations has some big development implications. More about those below.

But here’s the thing: you probably don’t need to set a theme color to color Safari’s UI! Without the setting, Safari automatically picks a color—usually based on the page’s background color. And on most sites, that will probably look just like you want it. That said, although the biggest Android browsers have been supporting theme colors for years, they don’t automatically pick a color!

Design considerations

Here are a few reasons why you could want to set theme colors yourself and not depend on browsers being smart enough about it:

  • The top section of your page has a background color that is different from the rest of it
  • The page has a background image and you want a color matching that
  • You want to take the opportunity to do some quirky branding and use a color different from the background of the site
A split screenshot of Safari showing a website with a very light green Safari UI on the left and a darker green that matches the pages's first section on the right.
On the ForTomorrow homepage, rather than making the theme-color match the page’s background (left), I made the theme color match the top section (right).

Just like it’s not mandatory to use the page’s background color as a theme color, you don’t have to use your brand’s main color either. After all, the purpose of the colored UI is to draw attention away from the browser UI to the content. Every time a visitor thinks ‘hey that’s a fine theme color the designer picked there’ (haha, as if), they’re not thinking about the content and are distracted from whatever goal you have for that page.

Every time I’m on Smashing Magazine, I feel like I’m in a call (because then iOS colors the status bar in a similar color).

You may have noticed that Safari uses the theme color for the scroll overshoot area that you see when bouncy-scrolling up beyond the top of the page. If you care about that kind of thing too, you should know that Chrome on desktop ignores the name="theme-color" meta tag. Instead it uses the <html> tag’s background color for the overshoot. So while you’re at it, you may want to apply the theme color to that too. By applying the pages’ current background colors to the <body> background, the pages will (sidenote: Provided that the body is at least as tall as the viewport, of course. ) look the same.

Technical considerations

As usual, CSS-Tricks provides details on options and syntax, like color support. The section about modifying the theme color with JavaScript is especially interesting. If you really want to go all-in on coloring the browser UI, you can make it depend on the scrolling position and the corresponding background color of the sections on a page.

Transitioning the theme color tag

About that situation where the UI should change to the background color of the section that a user has scrolled to—I’d prefer the UI to transition between the colors with a quick fade. To do that, of course you could write a script that calculates the transition colors and set a bunch of time outs to update the tag’s value at 60 fps. That seems like a lot of work for such a detail to me. I found a shortcut:

  1. With JS, remove (!) the theme color tag from the <head>.
  2. In CSS, add something like html{transition: background-color linear 150ms}.
  3. Using JS again, make the html node’s background match whatever section the user has scrolled to.

Admittedly, that doesn’t work for the biggest Android browsers though. But who knows, maybe it won’t be long before they also apply the same behavior that Safari has now.

Theme colors and theming

As mentioned before, if your site has themes the user can set themselves, the theme color should (sidenote: Upon publishing this post, I haven’t updated the theming script of this site yet. The reason being that I only have a dark and light theme and I no longer think it’s necessary to have a button for switching themes now that browser and OS support handles that for most visitors. So I will soon remove the button altogether. ) match that.

Define the theme color per layout

On a more general level, I recommend making the theme color depend on the page layout and avoid setting it for each page, as getting that into a CMS can get messy. Unless the CMS’s page editor already supports a color picker with a predefined colors, it will be difficult to provide authors with a palette limited to your brand’s colors. Anyway, in my experience, content authors tend not to care about such details and likely won’t properly use such a feature.

Managing colors in HTML, CSS and JS

Depending on the way your site is built, applying theme colors means you will have colors defined in HTML, CSS (+ custom properties, SCSS) and JavaScript. To reduce errors and inconsistencies, consider making a table that’s accessible by the build systems of all three. For my small projects, I find that a bit too much for such a detail and really, how often do you change a site’s color palette? Instead I made tables for each and added code comments saying that changes in one place should be copied to the others.

So … do you really need to set a theme color?

I looked at a lot of sites to see what colors Safari picked as a UI color for those. Among the top 20 most visited websites, only two made the UI not black or (near) white. Only one of those (WhatsApp) used a color that wasn’t the page’s main background color (although it’s close to it).

Via Lapa I also looked at a bunch of sites that get a disproportionate amount of design love. Although more of those sites colored the UI something else than white or black, very few used a color different from the page’s background.

This may not say much about how many of these sites actually have a theme color meta tag. But it does show that a non-white or black UI can be somewhat surprising and thus distracting—even when people have used a browser applying the theme color for a while.

To finally answer the question in the title: you only need to set the theme color if you care about the color of the UI of Android browsers. Changing Safari’s UI color is much easier done by setting the html tag’s background color in CSS.