{"id":13825462,"url":"https://github.com/postcss/postcss-dark-theme-class","last_synced_at":"2025-04-04T18:09:54.195Z","repository":{"id":35162127,"uuid":"214696315","full_name":"postcss/postcss-dark-theme-class","owner":"postcss","description":"PostCSS plugin to make dark/light theme switcher by copying styles from media query to special class","archived":false,"fork":false,"pushed_at":"2024-07-18T14:28:08.000Z","size":807,"stargazers_count":160,"open_issues_count":2,"forks_count":16,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-10-29T14:38:28.803Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/postcss.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"postcss","github":"ai"}},"created_at":"2019-10-12T18:33:13.000Z","updated_at":"2024-10-04T17:24:36.000Z","dependencies_parsed_at":"2024-01-18T03:43:52.935Z","dependency_job_id":"217a60c8-e165-4302-8785-d28994c5b44b","html_url":"https://github.com/postcss/postcss-dark-theme-class","commit_stats":{"total_commits":134,"total_committers":13,"mean_commits":"10.307692307692308","dds":"0.23880597014925375","last_synced_commit":"b3cf8e0ffb5dee5f243a75133b0cd3a303f9ffcf"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postcss%2Fpostcss-dark-theme-class","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postcss%2Fpostcss-dark-theme-class/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postcss%2Fpostcss-dark-theme-class/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postcss%2Fpostcss-dark-theme-class/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/postcss","download_url":"https://codeload.github.com/postcss/postcss-dark-theme-class/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246935165,"owners_count":20857347,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T09:01:21.471Z","updated_at":"2025-04-04T18:09:54.162Z","avatar_url":"https://github.com/postcss.png","language":"JavaScript","readme":"# PostCSS Dark Theme Class\n\n\u003cimg align=\"right\" width=\"135\" height=\"95\"\n     title=\"Philosopher’s stone, logo of PostCSS\"\n     src=\"https://postcss.org/logo-leftp.svg\"\u003e\n\nCSS solution for light/dark/auto theme switcher for websites.\n\n* It doesn’t have [FART] **flash of light theme** during JS initialization.\n* **Pure CSS** solution. You need JS only to set HTML class, when user.\n* **Automatic theme** provide better UX for users with theme switching\n  by subset/sunrise (all operating systems now have theme switching schedule).\n\n[PostCSS] plugin to make switcher to force dark or light theme by copying styles\nfrom media query or [`light-dark()`] to special class.\n\n[PostCSS]: https://github.com/postcss/postcss\n[FART]: https://css-tricks.com/flash-of-inaccurate-color-theme-fart/\n[`light-dark()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark\n\n```css\n/* Input CSS */\n\n@media (prefers-color-scheme: dark) {\n  html {\n    --text-color: white\n  }\n  body {\n    background: black\n  }\n}\n\nsection {\n  background: light-dark(white, black);\n}\n```\n\n```css\n/* Output CSS */\n\n@media (prefers-color-scheme: dark) {\n  html:where(:not(.is-light)) {\n    --text-color: white\n  }\n  :where(html:not(.is-light)) body {\n    background: black\n  }\n}\nhtml:where(.is-dark) {\n  --text-color: white\n}\n:where(html.is-dark) body {\n  background: black\n}\n\n@media (prefers-color-scheme: dark) {\n  :where(html:not(.is-light)) section {\n    background: black;\n  }\n}\n:where(html.is-dark) section {\n  background: black;\n}\n@media (prefers-color-scheme: light) {\n  :where(html:not(.is-dark)) section {\n    background: white;\n  }\n}\n:where(html.is-light) section {\n  background: white;\n}\n```\n\nBy default (without classes on `html`), website will use browser dark/light\ntheme. If user want to use dark theme, you set `html.is-dark` class.\nIf user want to force light theme, you use `html.is-light`.\n\n\u003ca href=\"https://evilmartians.com/?utm_source=postcss-dark-theme-class\"\u003e\n  \u003cimg src=\"https://evilmartians.com/badges/sponsored-by-evil-martians.svg\"\n       alt=\"Sponsored by Evil Martians\" width=\"236\" height=\"54\"\u003e\n\u003c/a\u003e\n\n\n## Usage\n\n**Step 1:** Install plugin:\n\n```sh\nnpm install --save-dev postcss postcss-dark-theme-class\n```\n\n**Step 2:** Check your project for existing PostCSS config: `postcss.config.js`\nin the project root, `\"postcss\"` section in `package.json`\nor `postcss` in bundle config.\n\nIf you do not use PostCSS, add it according to [official docs]\nand set this plugin in settings.\n\n**Step 3:** Add the plugin to plugins list:\n\n```diff\nmodule.exports = {\n  plugins: [\n+   require('postcss-dark-theme-class'),\n    require('autoprefixer')\n  ]\n}\n```\n\n**Step 4:** Add theme switcher to UI. We recommend to have 3 states: light,\ndark, and auto.\n\n**Step 5:** Set `is-dark` and `is-light` classes to `\u003chtml\u003e` according\nto switcher state:\n\n```html\n\u003cselect name=\"themeSwitcher\" id=\"themeSwitcher\"\u003e\n  \u003coption value=\"auto\"\u003eAuto\u003c/option\u003e\n  \u003coption value=\"light\"\u003eLight theme\u003c/option\u003e\n  \u003coption value=\"dark\"\u003eDark theme\u003c/option\u003e\n\u003c/select\u003e\n```\n\n```js\nconst html = document.documentElement\nconst themeSwitcher = document.getElementById('themeSwitcher')\n\nthemeSwitcher.addEventListener('change', () =\u003e {\n\n  if (themeSwitcher.value === 'auto') {\n    html.classList.remove('is-dark', 'is-light')\n\n  } else if (themeSwitcher.value === 'light') {\n    html.classList.add('is-light')\n    html.classList.remove('is-dark')\n\n  } else if (themeSwitcher.value === 'dark') {\n    html.classList.add('is-dark')\n    html.classList.remove('is-light')\n\n  }\n})\n```\n\n**Step 6:** Save user’s choice in `localStorage`.\n\n\n```diff\n  const html = document.documentElement\n  const themeSwitcher = document.getElementById('themeSwitcher')\n\n  themeSwitcher.addEventListener('change', () =\u003e {\n+   localStorage.theme = themeSwitcher.value\n\n    if (themeSwitcher.value === 'auto') {\n      html.classList.remove('is-dark', 'is-light')\n\n    } else if (themeSwitcher.value === 'light') {\n      html.classList.add('is-light')\n      html.classList.remove('is-dark')\n\n    } else if (themeSwitcher.value === 'dark') {\n      html.classList.add('is-dark')\n      html.classList.remove('is-light')\n\n    }\n  })\n\n+ if (localStorage.theme) {\n+   themeSwitcher.value = localStorage.theme ?? \"auto\";\n+   themeSwitcher.dispatchEvent(new Event(\"change\"));\n+ }\n```\n\n**Step 7:** Think of adding a small inline JS to prevent [FART] completely.\n\n```html\n  \u003cscript\u003e\n    if (localStorage.theme === 'light') {\n      html.classList.add('is-light')\n    } else if (localStorage.theme === 'dark') {\n      html.classList.add('is-dark')\n    }\n  \u003c/script\u003e\n\u003c/head\u003e\n```\n\n[official docs]: https://github.com/postcss/postcss#usage\n\n\n## Options\n\n```js\nmodule.exports = {\n  plugins: [\n    require('postcss-dark-theme-class')({\n      darkSelector: '.dark-theme',\n      lightSelector: '.light-theme'\n    })\n  ]\n}\n```\n\n\n### `darkSelector`\n\nType: `string`. Default: `.is-dark`.\n\nAny CSS’s valid selector for `\u003chtml\u003e` (alias for `:root`), which will switch\ndark theme. Use `darkSelector: '[data-theme=\"dark\"]'` if you will switch theme\nby setting `\u003chtml data-theme=dark\u003e`\n\n\n### `lightSelector`\n\nType: `string`. Default: `.is-light`.\n\nAny CSS’s valid selector, which will switch light theme.\nUse `lightSelector: '[data-theme=\"light\"]'` if you will switch theme by setting\n`\u003chtml data-theme=\"light\"\u003e`\n\n\n## `rootSelector`\n\nType: `string[]`, `string`. Default: `['html', ':root']`.\n\nSelector for node for CSS Custom properties and dark/light theme classes.\n\n\n## `useWhere`\n\nType: `boolean`. Default: `true`.\n\nShould plugin wrap added selector to `:where()` to keep origin specificity.\n\n\n## `removeMedia`\n\nType: `boolean`. Default: `false`.\n\nShould plugin remove origin `@media` and keep only classes. It could be useful\nwhen only JS is responsible for theme switching.\n\nIf you are using this option, don’t forget:\n1. That theme should have 3 values: light, system, dark.\n2. To subscribe for system theme switching in JS.\n\nWe do not recommend this option for most of the cases, because of light flash\nwhen user visit your app with dark system theme and until JS will be loaded.\n","funding_links":["https://opencollective.com/postcss","https://github.com/sponsors/ai"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostcss%2Fpostcss-dark-theme-class","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpostcss%2Fpostcss-dark-theme-class","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostcss%2Fpostcss-dark-theme-class/lists"}