# `` Element [![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/dark-mode-toggle) A custom element that allows you to easily put a _Dark Mode 🌒_ toggle or switch on your site, so you can initially adhere to your users' preferences according to [`prefers-color-scheme`](https://drafts.csswg.org/mediaqueries-5/#prefers-color-scheme), but also allow them to (optionally permanently) override their system setting for just your site. 📚 Read all(!) about dark mode in the related article [Hello Darkness, My Old Friend](https://web.dev/prefers-color-scheme/). ## Installation Install from npm: ```bash npm install --save dark-mode-toggle ``` Or, alternatively, use a ` ``` ![Dark mode toggle live coding sample.](https://user-images.githubusercontent.com/145676/94532333-0466b580-023e-11eb-947e-f73044a7cd63.gif) (See the [original HD version](https://youtu.be/qfsvoPhx-bE) so you can pause.) ## Usage There are three ways how you can use ``: ### ① Using different stylesheets per color scheme that are conditionally loaded The custom element assumes that you have organized your CSS in different files that you load conditionally based on the **`media`** attribute in the stylesheet's corresponding `link` element. This is a great performance pattern, as you don't force people to download CSS that they don't need based on their current theme preference, yet non-matching stylesheets still get loaded, but don't compete for bandwidth in the critical rendering path. You can also have more than one file per theme. The example below illustrates the principle. ```html

Hi there

Sitting cat in front of a tree

Check out the dark mode toggle in the upper right corner!

``` The above method might cause flashing ([#77](https://github.com/GoogleChromeLabs/dark-mode-toggle/issues/77)) when the page loads, as the dark mode toggle module is loaded after the page is rendered. A loader script can be used to apply the saved theme before the page is rendered. Wrap the stylesheet tags with `` and add the loader script as follows: ```html ``` ### ② Using a CSS class that you toggle If you prefer to not split your CSS in different files based on the color scheme, you can instead work with a class that you toggle, for example `class="dark"`. You can see this in action in [this demo](https://googlechrome.github.io/samples/dark-mode-class-toggle/). ```js import * as DarkModeToggle from 'https://googlechromelabs.github.io/dark-mode-toggle/src/dark-mode-toggle.mjs'; const toggle = document.querySelector('dark-mode-toggle'); const body = document.body; // Set or remove the `dark` class the first time. toggle.mode === 'dark' ? body.classList.add('dark') : body.classList.remove('dark'); // Listen for toggle changes (which includes `prefers-color-scheme` changes) // and toggle the `dark` class accordingly. toggle.addEventListener('colorschemechange', () => { body.classList.toggle('dark', toggle.mode === 'dark'); }); ``` ### ③ Using internal stylesheets for each color scheme This approach allows you to define styles directly within your HTML using ` ``` ## Demo See the custom element in action in the [interactive demo](https://googlechromelabs.github.io/dark-mode-toggle/demo/index.html). It shows four different kinds of synchronized ``s. If you use Chrome on an Android device, pay attention to the address bar's theme color, and also note how the favicon changes. Dark Light ## Properties Properties can be set directly on the custom element at creation time, or dynamically via JavaScript. 👉 Note that the dark and light **icons** are set via CSS variables, see [Style Customization](#style-customization) below. | Name | Required | Values | Default | Description | | ------------ | -------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `mode` | No | Any of `"dark"` or `"light"` | Defaults to whatever the user's preferred color scheme is according to `prefers-color-scheme`, or `"light"` if the user's browser doesn't support the media query. | If set overrides the user's preferred color scheme. | | `appearance` | No | Any of `"toggle"` or `"switch"` | Defaults to `"toggle"`. | The `"switch"` appearance conveys the idea of a theme switcher (light/dark), whereas `"toggle"` conveys the idea of a dark mode toggle (on/off). | | `permanent` | No | `true` if present | Defaults to not remember the last choice. | If present remembers the last selected mode (`"dark"` or `"light"`), which allows the user to permanently override their usual preferred color scheme. | | `legend` | No | Any string | Defaults to no legend. | Any string value that represents the legend for the toggle or switch. | | `light` | No | Any string | Defaults to no label. | Any string value that represents the label for the `"light"` mode. | | `dark` | No | Any string | Defaults to no label. | Any string value that represents the label for the `"dark"` mode. | | `remember` | No | Any string | Defaults to no label. | Any string value that represents the label for the "remember the last selected mode" functionality. | ## Events - `colorschemechange`: Fired when the color scheme gets changed. - `permanentcolorscheme`: Fired when the color scheme should be permanently remembered or not. ## Complete Example Interacting with the custom element: ```js /* On the page */ const darkModeToggle = document.querySelector('dark-mode-toggle'); // Set the mode to dark darkModeToggle.mode = 'dark'; // Set the mode to light darkModeToggle.mode = 'light'; // Set the legend to "Dark Mode" darkModeToggle.legend = 'Dark Mode'; // Set the light label to "off" darkModeToggle.light = 'off'; // Set the dark label to "on" darkModeToggle.dark = 'on'; // Set the appearance to resemble a switch (theme: light/dark) darkModeToggle.appearance = 'switch'; // Set the appearance to resemble a toggle (dark mode: on/off) darkModeToggle.appearance = 'toggle'; // Set a "remember the last selected mode" label darkModeToggle.remember = 'Remember this'; // Remember the user's last color scheme choice darkModeToggle.setAttribute('permanent', ''); // Forget the user's last color scheme choice darkModeToggle.removeAttribute('permanent'); ``` Reacting on color scheme changes: ```js /* On the page */ document.addEventListener('colorschemechange', (e) => { console.log(`Color scheme changed to ${e.detail.colorScheme}.`); }); ``` Reacting on "remember the last selected mode" functionality changes: ```js /* On the page */ document.addEventListener('permanentcolorscheme', (e) => { console.log( `${e.detail.permanent ? 'R' : 'Not r'}emembering the last selected mode.`, ); }); ``` ## Style Customization You can style the custom element with [`::part()`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part). See the demo's [CSS source code](https://github.com/GoogleChromeLabs/dark-mode-toggle/blob/master/demo/common.css) for some concrete examples. The exposed parts and their names can be seen below: ```html
``` Additionally, you can use a number of exposed CSS variables, as listed in the following: | CSS Variable Name | Default | Description | | ------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--dark-mode-toggle-light-icon` | No icon | The icon for the light state in `background-image:` notation. | | `--dark-mode-toggle-dark-icon` | No icon | The icon for the dark state in `background-image:` notation. | | `--dark-mode-toggle-icon-size` | 1rem | The icon size in CSS length data type notation. | | `--dark-mode-toggle-remember-icon-checked` | No icon | The icon for the checked "remember the last selected mode" functionality in `background-image:` notation. | | `--dark-mode-toggle-remember-icon-unchecked` | No icon | The icon for the unchecked "remember the last selected mode" functionality in `background-image:` notation. | | `--dark-mode-toggle-color` | User-Agent stylesheet text color | The main text color in `color:` notation. | | `--dark-mode-toggle-background-color` | User-Agent stylesheet background color | The main background color in `background-color:` notation. | | `--dark-mode-toggle-legend-font` | User-Agent `` font | The font of the legend in shorthand `font:` notation. | | `--dark-mode-toggle-label-font` | User-Agent `