Paul BradleySolutions Architect & Software Developer


Implementing a Dark Theme for your web site using CSS Media Queries

Support your users preference to use a dark theme by implementing a dark theme colour scheme using CSS Media Queries

midjourney ai - A samurai with pitch black skin standing in front of a deserted city

Table of Contents
  1. Introduction
  2. Determining if enough users prefer a dark theme
  3. Implementing a dark theme
  4. Handling Images


All the major web browsers have a feature that allows users to choose their preferred colour scheme for web sites. Users can choose between automatic, light or dark themes.

If a user prefers to have a dark theme then as web developers we should honour their preference and adjust our sites colour scheme to match. This article covers explains how to use CSS media queries to implement a dark theme.

Determining if enough users prefer a dark theme

You might decide you want to monitor how many of your visitor/users have a preference for a dark theme, before committing to implementing one.

The CSS (Cascading Style Sheet) snippet below uses @supports to check if the visitors browser supports colour schemes. If the browser does support colour schemes then it uses a media query to see if prefers-color-scheme is set to dark.

@supports (color-scheme: dark light) {
    @media screen and (prefers-color-scheme: dark) {
        body {
            background-image: url('');

If the dark preference is set then add a background image to the document body. The file darktheme.svg is a transparent SVG file which makes no visual difference to the website, but as the file is being requested from the web server it will show up within your web logs. Using your log analyzer of choice, I prefer GoAccess, you’ll be able to see how many people have dark theme as their preference.

The content of the darktheme.svg file is the minimal amount of code required to be a valid SVG file.

<svg xmlns=''/>

The SVG example was taken from this cool repository which aims to collect the smallest possible syntactically valid files in different programming/scripting/markup languages.

Implementing a dark theme

To implement a dark theme your going to be focussing on redefining the colour used within your web pages. At the very least you’ll need to change the background and foreground colours of the body tag. You’ll also want to change the colour of all the links within your pages.

Like in the snippet below for the class .banner, you might decide the page element doesn’t transition well to a dark theme and choose to hide it by switching the display property to none.

@supports (color-scheme: dark light) {
    @media screen and (prefers-color-scheme: dark) {

        .banner {
            display: none;

        body {
            background-color: #242323;
            color: rgb(231, 233, 234);

        a {
            border-bottom:1px dotted rgb(29, 155, 240);
            color:rgb(29, 155, 240);

        a:visited {
            color: rgb(46, 161, 237);

        a:hover {
            border-bottom:1px dotted rgb(231, 233, 234);
            color:rgb(231, 233, 234)

Handling Images

Images can pose a problem. If you’re able to produce different imagery for the different colour themes then you can use the picture tag to show the correct version of the image, see below for an example.

If you can’t retrospectively generate a dark theme suitable image then you can use the following CSS snippet to turn you light theme imagery into a greyscale version with a slight reduced opacity. This should make the images less glaring within a dark theme. These rules are applied to every image that isn’t an SVG file. So it’s applied to all my JPG and PNG images.

img:not([src*=".svg"]) {
    border: 2px solid rgb(113, 118, 123);
    filter: grayscale(100%);
    opacity: 90%;

In my opinion piece, Using SQLite on EFS I took the time to prepare two versions of the architectural diagram. I’ll cover how I did that in another article.

The HTML snippet below shows how to use the picture tag to set different source images based on the media queries.

    <source srcset="../svg/diagram-dark.svg"  media="(prefers-color-scheme: dark)" />
    <source srcset="../svg/diagram-light.svg" media="(prefers-color-scheme: light),
        (prefers-color-scheme: no-preference)" />

    <img decoding="async"
         alt="AWS Architecture Diagram" />