A custom React Hook to help you implement a "dark mode" component for your application.
useDarkMode works in one of two ways:
-
By toggling a CSS class on whatever element you specify (defaults to
document.body). You then setup your CSS to display different views based on the presence of the selector. For example, the following CSS is used in the demo app to ease the background color in/out of dark mode.body { background-color: #fff; color: #333; transition: background-color 0.3s ease; } body.dark-mode { background-color: #1a1919; color: #999; }
-
If you don't use global classes, you can specify an
onChangehandler and take care of the implementation of switching to dark mode yourself.
-
useDarkModenow persists between sessions. It stores the user setting inlocalStorage. -
It shares dark mode state with all other
useDarkModecomponents on the page. -
It shares dark mode state with all other tabs/browser windows.
-
The initial dark mode is queried from the system. Note: this requires a browser that supports the
prefers-color-scheme: darkmedia query (currently only Safari Technology Preview) and a system that supports dark mode, such as macOS Mojave. -
Changing the system dark mode state will also change the state of
useDarkMode(i.e, change to light mode in the system will change to light mode in your app).
To use use-dark-mode, you must use react@16.8.0 or greater which includes Hooks.
$ npm i use-dark-modeconst darkMode = useDarkMode(initialState, optionalConfigObject);You pass useDarkMode an initialState (a boolean specifying whether it should be in dark mode
by default) and an optional configuration object. The configuration object contains the following.
| Key | Description |
|---|---|
classNameDark |
The class to apply. Default = dark-mode. |
classNameLight |
The class to apply. Default = light-mode. |
element |
The element to apply the class name. Default = document.body. |
onChange |
A function that will be called when the dark mode value changes and it is safe to access the DOM (i.e. it is called from within a useEffect). If you specify onChange then classNameDark, classNameLight, and element are ignored (i.e. no classes are automatically placed on the DOM). You have full control! |
A darkMode object is returned with the following properties.
| Key | Description |
|---|---|
value |
A boolean containing the current state of dark mode. |
enable() |
A function that allows you to set dark mode to true. |
disable() |
A function that allows you to set dark mode to false. |
toggle() |
A function that allows you to toggle dark mode. |
Here is a simple component that uses useDarkMode to provide a dark mode toggle control.
If dark mode is selected, the CSS class dark-mode is applied to document.body and is removed
when de-selected.
import React from 'react';
import Toggle from './Toggle';
import useDarkMode from 'use-dark-mode';
const DarkModeToggle = () => {
const darkMode = useDarkMode(false);
return (
<div>
<button type="button" onClick={darkMode.disable}>
☀
</button>
<Toggle checked={darkMode.value} onChange={darkMode.toggle} />
<button type="button" onClick={darkMode.enable}>
☾
</button>
</div>
);
};
export default DarkModeToggle;If your CSS is setup to default to light mode, but the user selects dark mode,
the next time they visit your app, they will be in dark mode.
However, the user will see a flash of light mode before the app is spun up
and useDarkMode is called.
To prevent this, I've included some vanilla JavaScript that you can insert in your
index.html just after the <body> tag. It is in a file named noflash.js.txt.
You can either insert the contents of this file in a <script> tag or automate the
step in your build process.
You can view/edit a dark mode demo app on CodeSandbox.
MIT Licensed
A special thanks to @revelcw for his help and inspiration on this package.