🏷️ JavaScript NPM CSS Dark Mode How To
👀

How To: Add Dark Mode to a Website 🌓

Love it or hate it, it seems that the dark mode fad is here to stay, especially now that more and more devices have OLED screens that display true blacks... which means that these trendsetters might go blind from your site's insanely white background if you're behind the curve and don't offer your own dark mode.

It is possible to use pure CSS3 media queries to do this by reading a user's system and/or browser preference, which might be enough if you're okay with only supporting the latest, cutting-edge browsers and OSes. But if you want your own button on your website that switches back and forth between the two modes, there's no avoiding getting your hands a little dirty with some JavaScript.

I've written a simple implementation below, which...

  • Defaults to a user's system preference, until they press your toggle to set it themselves
  • Listens for clicks on any element of your choosing — just set the class to dark-mode-toggle. For example:
<button class="dark-mode-toggle">💡 Switch Themes</button>
  • Remembers the visitor's preference between visits using the local storage of the their browser (not cookies, please don't use cookies!)
  • Switches your <body>'s class between light and dark...

...meaning that any CSS selectors beginning with body.dark or body.light will only apply when the respective mode is active. A good place to start is by separating any color rules — your background, text, links, etc. — into a different section of your CSS. Using SASS or SCSS makes this a whole lot easier with nesting but is not required; this was written with a KISS mentality.

A very barebones example is embedded above (view the source here, or open in a new window if your browser is blocking the frame) and you can try it out on this site by clicking the 💡 lightbulb in the upper right corner of this page. You'll notice that the dark theme sticks when refreshing this page, navigating between other pages, or if you were to return to this example weeks from now.

⚡ Update: Now Available on NPM!

I have cleaned up this code a bit, added a few features, and packaged it as an 📦 NPM module (zero dependencies and still only ~500 bytes minified and gzipped!). Here's a small snippet of the updated method for the browser (pulling the module from UNPKG), but definitely read the readme for much more detail on the API.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

<button class="dark-mode-toggle" style="visibility: hidden;">💡 Click to see the light... or not.</button>

<script src="https://unpkg.com/dark-mode-switcheroo/dist/dark-mode.min.js"></script>
<script>
  window.darkMode.init({
    toggle: document.querySelector(".dark-mode-toggle"),
    classes: {
      light: "light",
      dark: "dark",
    },
    default: "light",
    storageKey: "dark_mode_pref",
    onInit: function (toggle) {
      toggle.style.visibility = "visible"; // toggle appears now that we know JS is enabled
    },
    onChange: function (theme, toggle) {
      console.log("Theme is now " + theme);
    },
  });
</script>

You can also install it straight from NPM (npm install dark-mode-switcheroo or yarn add dark-mode-switcheroo) and simply include the ESM module, which works great when bundling using Webpack, Browserify, Parcel, esbuild, etc.

1
2
3
4
5

import { init } from "dark-mode-switcheroo";

init({
  // ...same options as browser code.
});

The example HTML and CSS below is still helpful for reference.

Minified JS (410 bytes gzipped! 📦):

1
2

/*! Dark mode switcheroo | MIT License | jrvs.io/darkmode */
(function(){var e=window,t=e.document,i=t.body.classList,a=localStorage,c="dark_mode_pref",d=a.getItem(c),n="dark",o="light",r=o,s=t.querySelector(".dark-mode-toggle"),m=r===n,l=function(e){i.remove(n,o);i.add(e);m=e===n};d===n&&l(n);d===o&&l(o);if(!d){var f=function(e){return"(prefers-color-scheme: "+e+")"};e.matchMedia(f(n)).matches?l(n):e.matchMedia(f(o)).matches?l(o):l(r);e.matchMedia(f(n)).addListener((function(e){e.matches&&l(n)}));e.matchMedia(f(o)).addListener((function(e){e.matches&&l(o)}))}if(s){s.style.visibility="visible";s.addEventListener("click",(function(){if(m){l(o);a.setItem(c,o)}else{l(n);a.setItem(c,n)}}),!0)}})();

Full JS:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

/*! Dark mode switcheroo | MIT License | jrvs.io/darkmode */

(function () {
  // improve variable mangling when minifying
  var win = window;
  var doc = win.document;
  var body = doc.body;
  var classes = body.classList;
  var storage = localStorage;

  // check for preset `dark_mode_pref` preference in local storage
  var pref_key = 'dark_mode_pref';
  var pref = storage.getItem(pref_key);

  // change CSS via these <body> classes:
  var dark = 'dark';
  var light = 'light';

  // which class is <body> set to initially?
  var default_theme = light;

  // use an element with class `dark-mode-toggle` to trigger swap when clicked
  var toggle = doc.querySelector('.dark-mode-toggle');

  // keep track of current state no matter how we got there
  var active = (default_theme === dark);

  // receives a class name and switches <body> to it
  var activateTheme = function (theme) {
    classes.remove(dark, light);
    classes.add(theme);
    active = (theme === dark);
  };

  // if user already explicitly toggled in the past, restore their preference
  if (pref === dark) activateTheme(dark);
  if (pref === light) activateTheme(light);

  // user has never clicked the button, so go by their OS preference until/if they do so
  if (!pref) {
    // returns media query selector syntax
    var prefers = function (theme) {
      return '(prefers-color-scheme: ' + theme + ')';
    };

    // check for OS dark/light mode preference and switch accordingly
    // default to `default_theme` set above if unsupported
    if (win.matchMedia(prefers(dark)).matches)
      activateTheme(dark);
    else if (win.matchMedia(prefers(light)).matches)
      activateTheme(light);
    else
      activateTheme(default_theme);

    // real-time switching if supported by OS/browser
    win.matchMedia(prefers(dark)).addListener(function (e) { if (e.matches) activateTheme(dark); });
    win.matchMedia(prefers(light)).addListener(function (e) { if (e.matches) activateTheme(light); });
  }

  // don't freak out if page happens not to have a toggle
  if (toggle) {
    // toggle re-appears now that we know user has JS enabled
    toggle.style.visibility = 'visible';

    // handle toggle click
    toggle.addEventListener('click', function () {
      // switch to the opposite theme & save preference in local storage
      if (active) {
        activateTheme(light);
        storage.setItem(pref_key, light);
      } else {
        activateTheme(dark);
        storage.setItem(pref_key, dark);
      }
    }, true);
  }
})();

HTML & CSS Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

<!doctype html>
<html>
<head>
  <style>
    /* rules that apply globally */
    body {
      font-family: system-ui, -apple-system, sans-serif;
      text-align: center;
    }
    a {
      text-decoration: none;
    }
    .dark-mode-toggle {
      cursor: pointer;
      padding: 1em;

      /* hide toggle until we're sure user has JS enabled */
      visibility: hidden;
    }

    /* theme-specific rules -- you probably only want color-related stuff here */
    /* SCSS makes this a whole lot easier by allowing nesting, but is not required */
    body.light {
      background-color: #fff;
      color: #222;
    }
    body.light a {
      color: #06f;
    }
    body.dark {
      background-color: #222;
      color: #fff;
    }
    body.dark a {
      color: #fe0;
    }
  </style>
</head>
<body class="light">
  <h1>Welcome to the dark side 🌓</h1>
  <p><a href="https://github.com/jakejarvis/dark-mode-example">View the source code.</a></p>

  <button class="dark-mode-toggle">💡 Click to see the light... or not.</button>

  <script src="dark-mode.min.js"></script>
</body>
</html>

Further reading: