Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/postcss/postcss-dark-theme-class
PostCSS plugin to make dark/light theme switcher by copying styles from media query to special class
https://github.com/postcss/postcss-dark-theme-class
Last synced: about 1 month ago
JSON representation
PostCSS plugin to make dark/light theme switcher by copying styles from media query to special class
- Host: GitHub
- URL: https://github.com/postcss/postcss-dark-theme-class
- Owner: postcss
- License: mit
- Created: 2019-10-12T18:33:13.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2024-02-14T17:38:32.000Z (9 months ago)
- Last Synced: 2024-04-14T02:32:48.505Z (7 months ago)
- Language: JavaScript
- Homepage:
- Size: 628 KB
- Stars: 156
- Watchers: 10
- Forks: 14
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# PostCSS Dark Theme Class
CSS solution for light/dark/auto theme switcher for websites.
* It doesn’t have [FART] **flash of light theme** during JS initialization.
* **Pure CSS** solution. You need JS only to set HTML class, when user.
* **Automatic theme** provide better UX for users with theme switching
by subset/sunrise (all operating systems now have theme switching schedule).
[PostCSS] plugin to make switcher to force dark or light theme by copying styles
from media query or [`light-dark()`] to special class.
[PostCSS]: https://github.com/postcss/postcss
[FART]: https://css-tricks.com/flash-of-inaccurate-color-theme-fart/
[`light-dark()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark
```css
/* Input CSS */
@media (prefers-color-scheme: dark) {
html {
--text-color: white
}
body {
background: black
}
}
section {
background: light-dark(white, black);
}
```
```css
/* Output CSS */
@media (prefers-color-scheme: dark) {
html:where(:not(.is-light)) {
--text-color: white
}
:where(html:not(.is-light)) body {
background: black
}
}
html:where(.is-dark) {
--text-color: white
}
:where(html.is-dark) body {
background: black
}
@media (prefers-color-scheme: dark) {
:where(html:not(.is-light)) section {
background: black;
}
}
:where(html.is-dark) section {
background: black;
}
@media (prefers-color-scheme: light) {
:where(html:not(.is-dark)) section {
background: white;
}
}
:where(html.is-light) section {
background: white;
}
```
By default (without classes on `html`), website will use browser dark/light
theme. If user want to use dark theme, you set `html.is-dark` class.
If user want to force light theme, you use `html.is-light`.
## Usage
**Step 1:** Install plugin:
```sh
npm install --save-dev postcss postcss-dark-theme-class
```
**Step 2:** Check your project for existing PostCSS config: `postcss.config.js`
in the project root, `"postcss"` section in `package.json`
or `postcss` in bundle config.
If you do not use PostCSS, add it according to [official docs]
and set this plugin in settings.
**Step 3:** Add the plugin to plugins list:
```diff
module.exports = {
plugins: [
+ require('postcss-dark-theme-class'),
require('autoprefixer')
]
}
```
**Step 4:** Add theme switcher to UI. We recommend to have 3 states: light,
dark, and auto.
**Step 5:** Set `is-dark` and `is-light` classes to `` according
to switcher state:
```html
Auto
Light theme
Dark theme
```
```js
const html = document.documentElement
const themeSwitcher = document.getElementById('themeSwitcher')
themeSwitcher.addEventListener('change', () => {
if (themeSwitcher.value === 'auto') {
html.classList.remove('is-dark', 'is-light')
} else if (themeSwitcher.value === 'light') {
html.classList.add('is-light')
html.classList.remove('is-dark')
} else if (themeSwitcher.value === 'dark') {
html.classList.add('is-dark')
html.classList.remove('is-light')
}
})
```
**Step 6:** Save user’s choice in `localStorage`.
```diff
const html = document.documentElement
const themeSwitcher = document.getElementById('themeSwitcher')
themeSwitcher.addEventListener('change', () => {
+ localStorage.theme = themeSwitcher.value
if (themeSwitcher.value === 'auto') {
html.classList.remove('is-dark', 'is-light')
} else if (themeSwitcher.value === 'light') {
html.classList.add('is-light')
html.classList.remove('is-dark')
} else if (themeSwitcher.value === 'dark') {
html.classList.add('is-dark')
html.classList.remove('is-light')
}
})
+ if (localStorage.theme) {
+ themeSwitcher.value = localStorage.theme ?? "auto";
+ themeSwitcher.dispatchEvent(new Event("change"));
+ }
```
**Step 7:** Think of adding a small inline JS to prevent [FART] completely.
```html
if (localStorage.theme === 'light') {
html.classList.add('is-light')
} else if (localStorage.theme === 'dark') {
html.classList.add('is-dark')
}
```
[official docs]: https://github.com/postcss/postcss#usage
## Options
```js
module.exports = {
plugins: [
require('postcss-dark-theme-class')({
darkSelector: '.dark-theme',
lightSelector: '.light-theme'
})
]
}
```
### `darkSelector`
Type: `string`. Default: `.is-dark`.
Any CSS’s valid selector for `` (alias for `:root`), which will switch
dark theme. Use `darkSelector: '[data-theme="dark"]'` if you will switch theme
by setting ``
### `lightSelector`
Type: `string`. Default: `.is-light`.
Any CSS’s valid selector, which will switch light theme.
Use `lightSelector: '[data-theme="light"]'` if you will switch theme by setting
``
## `rootSelector`
Type: `string[]`, `string`. Default: `['html', ':root']`.
Selector for node for CSS Custom properties and dark/light theme classes.
## `useWhere`
Type: `boolean`. Default: `true`.
Should plugin wrap added selector to `:where()` to keep origin specificity.
## `removeMedia`
Type: `boolean`. Default: `false`.
Should plugin remove origin `@media` and keep only classes. It could be useful
when only JS is responsible for theme switching.
If you are using this option, don’t forget:
1. That theme should have 3 values: light, system, dark.
2. To subscribe for system theme switching in JS.
We do not recommend this option for most of the cases, because of light flash
when user visit your app with dark system theme and until JS will be loaded.