Skip to content

Latest commit

 

History

History
249 lines (182 loc) · 5.95 KB

README.md

File metadata and controls

249 lines (182 loc) · 5.95 KB
Raw

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.

/* Input CSS */

@media (prefers-color-scheme: dark) {
  html {
    --text-color: white
  }
  body {
    background: black
  }
}

section {
  background: light-dark(white, black);
}
/* 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.

Sponsored by Evil Martians

Usage

Step 1: Install plugin:

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:

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 <html> according to switcher state:

<select name="themeSwitcher" id="themeSwitcher">
  <option value="auto">Auto</option>
  <option value="light">Light theme</option>
  <option value="dark">Dark theme</option>
</select>
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.

  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.

  <script>
    if (localStorage.theme === 'light') {
      html.classList.add('is-light')
    } else if (localStorage.theme === 'dark') {
      html.classList.add('is-dark')
    }
  </script>
</head>

Options

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 <html> (alias for :root), which will switch dark theme. Use darkSelector: '[data-theme="dark"]' if you will switch theme by setting <html data-theme=dark>

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 <html data-theme="light">

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.