{"id":13450899,"url":"https://github.com/donavon/use-dark-mode","last_synced_at":"2025-05-14T23:06:13.910Z","repository":{"id":37561932,"uuid":"165658820","full_name":"donavon/use-dark-mode","owner":"donavon","description":"A custom React Hook to help you implement a \"dark mode\" component.","archived":false,"fork":false,"pushed_at":"2023-01-03T15:59:16.000Z","size":557,"stargazers_count":1289,"open_issues_count":48,"forks_count":98,"subscribers_count":5,"default_branch":"develop","last_synced_at":"2025-05-14T23:05:47.635Z","etag":null,"topics":["dark-mode","dark-theme","hooks","react"],"latest_commit_sha":null,"homepage":null,"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/donavon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-14T12:36:43.000Z","updated_at":"2025-05-12T21:54:14.000Z","dependencies_parsed_at":"2023-02-01T07:25:11.561Z","dependency_job_id":null,"html_url":"https://github.com/donavon/use-dark-mode","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donavon%2Fuse-dark-mode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donavon%2Fuse-dark-mode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donavon%2Fuse-dark-mode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donavon%2Fuse-dark-mode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/donavon","download_url":"https://codeload.github.com/donavon/use-dark-mode/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254243360,"owners_count":22038046,"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":["dark-mode","dark-theme","hooks","react"],"created_at":"2024-07-31T07:00:39.986Z","updated_at":"2025-05-14T23:06:08.886Z","avatar_url":"https://github.com/donavon.png","language":"JavaScript","funding_links":[],"categories":["Packages","JavaScript"],"sub_categories":[],"readme":"# use-dark-mode\n\nA custom [React Hook](https://reactjs.org/docs/hooks-overview.html) to help you implement a \"dark mode\" component for your application.\nThe user setting persists to `localStorage`.\n\n❤️ it? ⭐️ it on [GitHub](https://github.com/donavon/use-dark-mode/stargazers)\nor [Tweet](https://twitter.com/intent/tweet?text=Check%20out%20the%20useDarkMode%20custom%20React%20Hook%20that%20simplifies%20adding%20a%20persistent%20dark%20mode%20setting%20to%20your%20app.\u0026url=https%3A%2F%2Fgithub.com%2Fdonavon%2Fuse-dark-mode\u0026via=donavon\u0026hashtags=reactjs,hooks,darkmode)\nabout it.\n\n[![npm version](https://badge.fury.io/js/use-dark-mode.svg)](https://badge.fury.io/js/use-dark-mode) [![Build Status](https://travis-ci.com/donavon/use-dark-mode.svg?branch=master)](https://travis-ci.com/donavon/use-dark-mode) [![All Contributors](https://img.shields.io/badge/all_contributors-6-orange.svg?style=flat-square)](#contributors)\n[![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Check%20out%20the%20useDarkMode%20custom%20React%20Hook%20that%20simplifies%20adding%20a%20persistent%20dark%20mode%20setting%20to%20your%20app.\u0026url=https%3A%2F%2Fgithub.com%2Fdonavon%2Fuse-dark-mode\u0026via=donavon\u0026hashtags=reactjs,hooks,darkmode)\n\n![usedarkmode-small](https://user-images.githubusercontent.com/887639/51113468-079ee100-17d0-11e9-8a35-e29b12b74740.gif)\n\n`useDarkMode` works in one of two ways:\n\n1.  By toggling a CSS class on whatever element you specify (defaults to `document.body`).\n    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.\n\n    ```css\n    body.light-mode {\n      background-color: #fff;\n      color: #333;\n      transition: background-color 0.3s ease;\n    }\n    body.dark-mode {\n      background-color: #1a1919;\n      color: #999;\n    }\n    ```\n\n2.  If you don't use global classes, you can specify an `onChange` handler and take care of the implementation of switching to dark mode yourself.\n\n## New in Version 2.x\n\n- `useDarkMode` now persists between sessions. It stores the user setting in\n  `localStorage`.\n\n- It shares dark mode state with all other `useDarkMode` components on the page.\n\n- It shares dark mode state with all other tabs/browser windows.\n\n- The initial dark mode is queried from the system. Note: this requires a browser that supports the `prefers-color-scheme: dark` media query\n  ([currently Chrome, Firefox, Safari and Edge](https://caniuse.com/#search=prefers-color-scheme))\n  and a system that supports dark mode, such as macOS Mojave.\n\n- Changing the system dark mode state will also change the state of `useDarkMode`\n  (i.e, change to light mode in the system will change to light mode in your app).\n\n- Support for Server Side Rendering (SSR) in version 2.2 and above.\n\n## Requirement\n\nTo use `use-dark-mode`, you must use `react@16.8.0` or greater which includes Hooks.\n\n## Installation\n\n```sh\n$ npm i use-dark-mode\n```\n\n## Usage\n\n```js\nconst darkMode = useDarkMode(initialState, darkModeConfig);\n```\n\n### Parameters\n\nYou pass `useDarkMode` an `initialState` (a boolean specifying whether it should be in dark mode\nby default) and an optional `darkModeConfig` object. The configuration object may contain the following keys.\n\n| Key               | Description                                                                                                                                                                                                                                                                                                               |\n| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `classNameDark`   | The class to apply. Default = `dark-mode`.                                                                                                                                                                                                                                                                                |\n| `classNameLight`  | The class to apply. Default = `light-mode`.                                                                                                                                                                                                                                                                               |\n| `element`         | The element to apply the class name. Default = `document.body`.                                                                                                                                                                                                                                                           |\n| `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! |\n| `storageKey`      | A string that will be used by the `storageProvider` to persist the dark mode value. If you specify a value of `null`, nothing will be persisted. Default = `darkMode`.                                                                                                                                                                                                                   |\n| `storageProvider` | A storage provider. Default = `localStorage`. You will generally never need to change this value.                                                                                                                                                                                                                       |\n\n### Return object\n\nA `darkMode` object is returned with the following properties.\n\n| Key         | Description                                             |\n| :---------- | :------------------------------------------------------ |\n| `value`     | A boolean containing the current state of dark mode.    |\n| `enable()`  | A function that allows you to set dark mode to `true`.  |\n| `disable()` | A function that allows you to set dark mode to `false`. |\n| `toggle()`  | A function that allows you to toggle dark mode.         |\n\nNote that because the methods don't require any parameters, you can call them\ndirecly from an `onClick` handler from a button, for example\n(i.e., no lambda function is required).\n\n## Example\n\nHere is a simple component that uses `useDarkMode` to provide a dark mode toggle control.\nIf dark mode is selected, the CSS class `dark-mode` is applied to `document.body` and is removed\nwhen de-selected.\n\n```jsx\nimport React from 'react';\nimport useDarkMode from 'use-dark-mode';\n\nimport Toggle from './Toggle';\n\nconst DarkModeToggle = () =\u003e {\n  const darkMode = useDarkMode(false);\n\n  return (\n    \u003cdiv\u003e\n      \u003cbutton type=\"button\" onClick={darkMode.disable}\u003e\n        ☀\n      \u003c/button\u003e\n      \u003cToggle checked={darkMode.value} onChange={darkMode.toggle} /\u003e\n      \u003cbutton type=\"button\" onClick={darkMode.enable}\u003e\n        ☾\n      \u003c/button\u003e\n    \u003c/div\u003e\n  );\n};\n\nexport default DarkModeToggle;\n```\n\n## That flash!\n\nIf your CSS is setup to default to light mode, but the user selects dark mode,\nthe next time they visit your app, they will be in dark mode.\nHowever, the user will see a flash of light mode before the app is spun up\nand `useDarkMode` is called.\n\nTo prevent this, I've included some vanilla JavaScript that you can insert in your\n`index.html` just after the `\u003cbody\u003e` tag. It is in a file named [noflash.js.txt](https://github.com/donavon/use-dark-mode/blob/develop/noflash.js.txt).\nYou can either insert the contents of this file in a `\u003cscript\u003e` tag or automate the\nstep in your build process.\n\nNote that if you change any of the default—such as `storageKey` or `classNameDark` for example—the `noflash.js` file will need to be modified with the same values.\n\n### Gatsby\n\nGatsby users may leverage [`gatsby-plugin-use-dark-mode`](https://github.com/wKovacs64/gatsby-plugin-use-dark-mode#readme) to inject `noflash.js` for you.\n\n### Next.js\n\nFor next.js uses copy the `noflash.js.txt` to your `public` folder (`public/noflash.js`) and then create a `_document.js` and include the script **before** `\u003cMain /\u003e`.\n\n```js\nimport Document, { Html, Head, Main, NextScript } from 'next/document';\n\nclass MyDocument extends Document {\n  render() {\n    return (\n      \u003cHtml\u003e\n        \u003cHead /\u003e\n        \u003cbody\u003e\n          \u003cscript src=\"noflash.js\" /\u003e\n          \u003cMain /\u003e\n          \u003cNextScript /\u003e\n        \u003c/body\u003e\n      \u003c/Html\u003e\n    );\n  }\n}\n\nexport default MyDocument;\n```\n\n## Sample Apps\n\nHere is a list of apps build with `use-dark-mode`.\nIf you have an app you would like to include on this list, open a PR.\n\n* [Demo App on CodeSandbox](https://codesandbox.io/s/mzj64x80ny) - by [@donavon](https://twitter.com/donavon)\n\n## License\n\n**[MIT](LICENSE)** Licensed\n\n## Contributors\n\nThanks goes to these wonderful people ([emoji key](https://github.com/all-contributors/all-contributors#emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://donavon.com\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/887639?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eDonavon West\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#infra-donavon\" title=\"Infrastructure (Hosting, Build-Tools, etc)\"\u003e🚇\u003c/a\u003e \u003ca href=\"https://github.com/donavon/use-dark-mode/commits?author=donavon\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"#example-donavon\" title=\"Examples\"\u003e💡\u003c/a\u003e \u003ca href=\"#ideas-donavon\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"#maintenance-donavon\" title=\"Maintenance\"\u003e🚧\u003c/a\u003e \u003ca href=\"https://github.com/donavon/use-dark-mode/pulls?q=is%3Apr+reviewed-by%3Adonavon\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e \u003ca href=\"#tool-donavon\" title=\"Tools\"\u003e🔧\u003c/a\u003e \u003ca href=\"https://github.com/donavon/use-dark-mode/commits?author=donavon\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/revelcw\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/29359616?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eRevel Carlberg West\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#ideas-revelcw\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/Andarist\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/9800850?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMateusz Burzyński\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/donavon/use-dark-mode/commits?author=Andarist\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/wKovacs64\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/1288694?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJustin Hall\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/donavon/use-dark-mode/commits?author=wKovacs64\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/fxbabys\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/24556921?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJeremy\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#userTesting-fxbabys\" title=\"User Testing\"\u003e📓\u003c/a\u003e \u003ca href=\"https://github.com/donavon/use-dark-mode/issues?q=author%3Afxbabys\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://janosh.io\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/30958850?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJanosh Riebesell\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/donavon/use-dark-mode/commits?author=janosh\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://hipstersmoothie.com\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/1192452?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAndrew Lisowski\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/donavon/use-dark-mode/commits?author=hipstersmoothie\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://jorgegonzalez.io\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/12901172?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJorge Gonzalez\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/donavon/use-dark-mode/commits?author=jorgegonzalez\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-enable --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonavon%2Fuse-dark-mode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdonavon%2Fuse-dark-mode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonavon%2Fuse-dark-mode/lists"}