{"id":22476986,"url":"https://github.com/felixtellmann/use-color-theme","last_synced_at":"2025-12-30T23:22:34.769Z","repository":{"id":57158286,"uuid":"296401380","full_name":"FelixTellmann/use-color-theme","owner":"FelixTellmann","description":"A custom React Hook to help you implement a theming classes for your application. Allows you to add as many color themes as you wish.","archived":false,"fork":false,"pushed_at":"2020-10-06T07:38:27.000Z","size":250,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-18T15:46:33.818Z","etag":null,"topics":["css","dark-mode","dark-theme","hooks","light-theme","react"],"latest_commit_sha":null,"homepage":"https://github.com/FelixTellmann/use-color-theme","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/FelixTellmann.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":"2020-09-17T17:50:38.000Z","updated_at":"2021-03-15T05:23:34.000Z","dependencies_parsed_at":"2022-09-02T14:00:53.952Z","dependency_job_id":null,"html_url":"https://github.com/FelixTellmann/use-color-theme","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FelixTellmann%2Fuse-color-theme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FelixTellmann%2Fuse-color-theme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FelixTellmann%2Fuse-color-theme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FelixTellmann%2Fuse-color-theme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FelixTellmann","download_url":"https://codeload.github.com/FelixTellmann/use-color-theme/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245897208,"owners_count":20690438,"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":["css","dark-mode","dark-theme","hooks","light-theme","react"],"created_at":"2024-12-06T14:09:12.821Z","updated_at":"2025-12-30T23:22:34.726Z","avatar_url":"https://github.com/FelixTellmann.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# use-color-theme\n\nA custom [React Hook](https://reactjs.org/docs/hooks-overview.html) to help you implement a \"theming\" classes for your application.\nThe user setting persists to `localStorage` and allows you to add as many color themes as you wish.\n\n`useColorTheme` 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 color theme.\n\n    ```css\n    body.light-theme {\n      background-color: #fff;\n      color: #333;\n      transition: background-color 0.3s ease;\n      --color-text: #242424;\n    }\n    body.dark-theme {\n      background-color: #1a1919;\n      color: #999;\n      --color-text: #ffffff;\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 themee yourself.\n\n- Support for Server Side Rendering (SSR) in version 2.2 and above.\n\n## Requirement\n\nTo use `use-color-theme`, you must use `react@16.8.0` or greater which includes Hooks.\n\n## Installation\n\n```sh\n$ npm i use-color-theme\n```\n\n## Usage\n\n```js\nconst colorTheme = useColorTheme(initialState, colorThemeConfig);\n```\n\n### Parameters\n\nYou pass `useColorTheme` an `initialState` (a `string` specifying to define the default className, defaults to `light-theme`) and an optional `colorThemeConfig` object. The configuration object may contain the following keys.\n\n| Key               | Description                                                                                                                                                                                                                                                                                                               |\n| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `classNames`      | The classes to apply. Default = [`'light-theme'`,`'dark-theme'`].                                                                                                                                                                                                                                                                             |\n| `element`         | The element to apply the class name. Default = `document.body`.                                                                                                                                                                                                                                                           |\n| `onChange`        | A function that will be called when the color theme value changes and it is safe to access the DOM (i.e. it is called from within a `useEffect`). If you specify `onChange` then `classNames`, 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 themee value. If you specify a value of `null`, nothing will be persisted. Default = `colorTheme`.                                                                                                                                                                                                                   |\n| `storageProvider` | A storage provider. Default = `localStorage`. You will generally never need to change this value.                                                                                                                                                                                                                       |\n\n### Return object\n\nA `colorTheme` object is returned with the following properties.\n\n| Key         | Description                                             |\n| :---------- | :------------------------------------------------------ |\n| `value`     | The string containing the current state className.    |\n| `set('value')`  | A function that allows you to set color theme to to `'value'`.  |\n| `toggle()`  | A function that allows you to toggle dark themee, iterating over all provided theme classes.         |\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 `useColorTheme` to provide a color theme toggle control.\nIf color theme is selected, the CSS class `color-theme` is applied to `document.body` and is removed\nwhen de-selected.\n\n```jsx\nimport React from 'react';\nimport useColorTheme from 'use-color-theme';\n\nimport Toggle from './Toggle';\n\nconst colorThemeToggle = () =\u003e {\n  const colorTheme = useColorTheme(false);\n\n  return (\n    \u003cdiv\u003e\n      \u003cbutton type=\"button\" onClick={colorTheme.set('light-theme')}\u003e\n        ☀\n      \u003c/button\u003e\n      \u003cToggle checked={colorTheme.value} onChange={colorTheme.toggle} /\u003e\n      \u003cbutton type=\"button\" onClick={colorTheme.set('dark-theme')}\u003e\n        ☾\n      \u003c/button\u003e\n    \u003c/div\u003e\n  );\n};\n\nexport default colorThemeToggle;\n```\n\n## That flash!\n\nIf your CSS is setup to default to light-theme, but the user selects color theme,\nthe next time they visit your app, they will be in color theme.\nHowever, the user will see a flash of light-theme before the app is spun up\nand `useColorTheme` 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`\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 `classNames` for example—the `noflash.js` file will need to be modified with the same values.\n\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## License\n\n**[MIT](LICENSE)** Licensed\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelixtellmann%2Fuse-color-theme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffelixtellmann%2Fuse-color-theme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelixtellmann%2Fuse-color-theme/lists"}