{"id":13802156,"url":"https://github.com/cssinjs/theming","last_synced_at":"2026-02-15T22:05:10.796Z","repository":{"id":41300838,"uuid":"89290601","full_name":"cssinjs/theming","owner":"cssinjs","description":"Unified CSSinJS theming solution for React","archived":false,"fork":false,"pushed_at":"2022-12-06T17:13:28.000Z","size":1271,"stargazers_count":303,"open_issues_count":15,"forks_count":35,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-10T08:46:30.028Z","etag":null,"topics":["css-in-js","cssinjs","react","theme"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cssinjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-24T21:53:51.000Z","updated_at":"2025-02-11T19:56:44.000Z","dependencies_parsed_at":"2023-01-24T10:15:57.582Z","dependency_job_id":null,"html_url":"https://github.com/cssinjs/theming","commit_stats":null,"previous_names":["iamstarkov/theming"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssinjs%2Ftheming","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssinjs%2Ftheming/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssinjs%2Ftheming/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssinjs%2Ftheming/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cssinjs","download_url":"https://codeload.github.com/cssinjs/theming/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248429062,"owners_count":21101780,"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-in-js","cssinjs","react","theme"],"created_at":"2024-08-04T00:01:37.620Z","updated_at":"2026-02-15T22:05:05.754Z","avatar_url":"https://github.com/cssinjs.png","language":"JavaScript","readme":"# Theming\n\n[![NPM version][npm-image]][npm-url]\n[![Build][travis-image]][travis-url]\n[![Coveralls Status][coveralls-image]][coveralls-url]\n[![Dependency Status][depstat-image]][depstat-url]\n\n## Unified CSSinJS theming solution for React\n\n* `ThemeProvider` allows you to pass, update, merge and augment `theme` through context down react tree.\n* `withTheme` allows you to receive theme and its updates in your components as a `theme` prop.\n* `createTheming` allows you to integrate `theming` into your CSSinJS library with custom `channel` (if you need custom one).\n\nSee [Motivation](#motivation) for details.\n\n\n## Table of Contents\n\n* [Install](#install)\n* [Usage](#usage)\n* [Playground demo](#playground-demo)\n* [Motivation](#motivation)\n* [API](#api)\n  * [ThemeProvider](#themeprovider)\n  * [withTheme](#withthemecomponent)\n  * [useTheme](#usetheme)\n  * [createTheming](#createthemingcustomchannel)\n* [Credits](#credits)\n* [License](#license)\n\n\n## Install\n\n    npm install --save theming\n    # or\n    yarn add theming\n\n\n## Usage\n\nIn your components\n\nNote: this component is used to show what theme you receive.\n\n```jsx\nimport React from 'react';\nimport { withTheme } from 'theming';\n\nconst DemoBox = props =\u003e {\n  console.log(props.theme);\n  return (\u003cdiv /\u003e);\n}\n\nexport default withTheme(DemoBox);\n```\n\nIn your app\n\n```jsx\nimport React from 'react';\nimport { ThemeProvider } from 'theming';\nimport DemoBox from './components/DemoBox'\n\nconst theme = {\n  color: 'black',\n  background: 'white',\n};\n\nconst App = () =\u003e (\n  \u003cThemeProvider theme={theme}\u003e\n    \u003cDemoBox /\u003e {/* { color: 'black', background: 'white' } */}\n  \u003c/ThemeProvider\u003e\n)\n\nexport default App;\n```\n\n## Playground demo\n\nBe our guest, play with `theming` in codesandbox:\n[https://codesandbox.io/s/jvwzkkxrp5](https://codesandbox.io/s/jvwzkkxrp5)\n\n![theming playground demo](https://user-images.githubusercontent.com/559321/27082371-ba194816-5044-11e7-8f06-6cbdbdefb602.gif)\n\n## Motivation\n\nThese components are enabling seamless theming for your react applications. So as far as you don't want to pass the theme object to every component. That's why you want to use context. However, as far context feature is _experimental API and it is likely to break in future releases of React_ you don't want to use it directly. Here `theming` comes to play.\n\n\u003e If you insist on using context despite these warnings, try to isolate your use of context to a small area and avoid using the context API directly when possible so that it's easier to upgrade when the API changes.\n\u003e\n\u003e If you insist on using context despite these warnings, try to isolate your use of context to a small area and avoid using the context API directly when possible so that it's easier to upgrade when the API changes.\n\u003e — [Context, React documentation](https://facebook.github.io/react/docs/context.html)\n\nRegarding _isolation your use of context to a small area_ and _small areas__ in particular our very own react prophet Dan Abramov have a thing to say:\n\n\u003e Should I use React unstable “context” feature?\n\u003e \u003cimg src=\"https://pbs.twimg.com/media/CmeGPNcVYAAM7TR.jpg\" alt=\"![context application areas]\" height=\"300\" /\u003e\n\u003e — [Dan Abramov @dan_abramov on Twitter](https://twitter.com/dan_abramov/status/749715530454622208?lang=en)\n\nSo you are okay to use context for theming. `theming` package provides everything you need to do that:\n* The `ThemeProvider` allows you to pass and update your theme through context down the react tree.\n* `withTheme` allows you to receive theme and its updates in your components as a `theme` prop.\n* `createTheming` allows you to integrate `theming` into your CSSinJS library with a custom `context` (if you need custom one).\n\n\n## API\n\n### ThemeProvider\n\nReact High-Order component, which passes theme object down the react tree by context.\n\n```jsx\nimport { ThemeProvider } from 'theming';\nconst theme = { /*…*/ };\n\n\u003cThemeProvider theme={theme}\u003e\n  \u003cApp /\u003e\n\u003c/ThemeProvider\u003e\n```\n\n#### props\n\n##### props.theme\n\n*Required*\nType: `Object`, `Function`\n\nIf its `Object` and its root `ThemeProvider` then it's intact and being passed down the react tree.\n\n```jsx\nconst theme = { themed: true };\n\n\u003cThemeProvider theme={theme}\u003e\n  \u003cDemoBox /\u003e {/* { themed: true } */}\n\u003c/ThemeProvider\u003e\n```\n\nIf its `Object` and its nested `ThemeProvider` then it is being merged with the theme from the parent `ThemeProvider` and passed down to the react tree.\n\n```jsx\nconst theme = { themed: true };\nconst patch = { merged: true };\n\n\u003cThemeProvider theme={theme}\u003e\n  \u003cThemeProvider theme={patch}\u003e\n    \u003cDemoBox /\u003e {/* { themed: true, merged: true } */}\n  \u003c/ThemeProvider\u003e\n\u003c/ThemeProvider\u003e\n```\n\nIf its `Function` and its nested `ThemeProvider` then it's being applied to the theme from parent `ThemeProvider`. If the result is an `Object` it's passed down to the react tree, throws otherwise.\n\n```jsx\nconst theme = { themed: true };\nconst augment = outerTheme =\u003e\n  Object.assign({}, outerTheme, { augmented: true });\n\n\u003cThemeProvider theme={theme}\u003e\n  \u003cThemeProvider theme={augment}\u003e\n    \u003cDemoBox /\u003e {/* { themed: true, augmented: true } */}\n  \u003c/ThemeProvider\u003e\n\u003c/ThemeProvider\u003e\n```\n\n##### props.children\n\n*Required*\nType: `PropTypes.element`\n\n### withTheme(component)\n\nReact High-Order component, which maps context to theme prop.\n\n#### component\n\n*Required*\nType: `ComponentType`\n\nYou need to have `ThemeProvider` with a theme somewhere upper the react tree after that wrap your component in `withTheme` and your component gets the theme as a prop. `withTheme`  handles the initial theme object as well as theme updates.\n\nPS. It doesn't break if you have `PureComponent` somewhere in between your `ThemeProvider` and `withTheme`.\n\nUsage with Component:\n\n```jsx\nimport React from 'react';\nimport { withTheme } from 'theming';\n\nconst DemoBox = props =\u003e {\n  console.log(props.theme);\n  return (\u003cdiv /\u003e);\n}\n\nexport default withTheme(DemoBox);\n```\n\nIn the app:\n\n```jsx\nimport React from 'react';\nimport { ThemeProvider } from 'theming';\nimport DemoBox from './components/DemoBox'\n\nconst theme = {\n  color: 'black',\n  background: 'white',\n};\n\nconst App = () =\u003e (\n  \u003cThemeProvider theme={theme}\u003e\n    \u003cDemoBox /\u003e {/* { color: 'black', background: 'white' } */}\n  \u003c/ThemeProvider\u003e\n)\n\nexport default App;\n```\n\n#### Access inner component instance\n\nThe `withTheme` HOC supports the new React forwardRef API so you can use the regular ref prop.\n\n### useTheme\n\nWhen you are on React 16.8 higher you will be able to use the `useTheme` hook which will return the theme object.\n\nUsage with Component:\n\n```jsx\nimport React from 'react';\nimport { useTheme } from 'theming';\n\nconst DemoBox = () =\u003e {\n  const theme = useTheme();\n  console.log(theme);\n  return (\u003cdiv /\u003e);\n}\n\nexport default Demobox;\n```\n\n### createTheming(context)\n\nFunction to create `ThemeProvider` and `withTheme` with custom context.\nThe context you pass in is used.\n\n#### context\n\nType: `Object`\nResult: `Object { withTheme, ThemeProvider, useTheme }`\n\n`withTheme`, `ThemeProvider` and `useTheme` will use the context passed to `createTheming`.\n\nNote: You will only be able to use `useTheme` when you are on React version 16.8 or higher.\n\n```js\nimport { createTheming } from 'theming';\nimport React from 'react';\n\nconst context = React.createContext({});\nconst theming = createTheming(context);\n\nconst { withTheme, ThemeProvider, useTheme } = theming;\n\nexport default {\n  withTheme,\n  ThemeProvider,\n  useTheme,\n};\n```\n\n## ThemeContext\n\nWe export the default ThemeContext so you can use it with the new `static contextType` with classes or even the new React Hooks API.\nThis is the context which also the exported `withTheme` and `ThemeProvider` use.\n\n```js\nimport { ThemeContext } from 'theming';\n```\n\n## Credits\n\n* Thanks to [jss][jss] creator [Oleg Slobodskoi @kof][kof] for immersive help, support and code review.\n* Thanks to [styled-components][sc] creator [Max Stoiber @mxstbr][mxstbr] for initial and battle tested implementation of theming support in [styled-components][sc] as well as help and code review.\n* Thanks to [styled-components'][sc] core team member [Phil Plückthun @philpl][philpl] for help and code review.\n* Thanks to [glamorous][glamorous] creator [Kent C. Dodds @kentcdodds][kentcdodds] for help, support and code review.\n* Thanks to [glamorous's][glamorous] core team member [Alessandro Arnodo @vesparny][vesparny] for improved theming support in [glamorous][glamorous] and [brcast][brcast].\n* Thanks to [Gert Sallaerts @gertt][gertt] for the [playground][playground] demo.\n\n[kof]: https://github.com/kof\n[mxstbr]: https://github.com/mxstbr\n[philpl]: https://github.com/philpl\n[kentcdodds]: https://github.com/kentcdodds\n[vesparny]: https://github.com/vesparny\n[gertt]: https://github.com/gertt\n\n[jss]: https://github.com/cssinjs/jss\n[sc]: https://github.com/styled-components/styled-components\n[glamorous]: https://github.com/paypal/glamorous\n[brcast]: https://github.com/vesparny/brcast\n[playground]: https://codesandbox.io/s/jvwzkkxrp5\n\n## License\n\nMIT © [Vladimir Starkov](https://iamstarkov.com)\n\n[npm-url]: https://npmjs.org/package/theming\n[npm-image]: https://img.shields.io/npm/v/theming.svg?style=flat-square\n\n[travis-url]: https://travis-ci.org/iamstarkov/theming\n[travis-image]: https://img.shields.io/travis/iamstarkov/theming.svg?style=flat-square\n\n[coveralls-url]: https://coveralls.io/r/iamstarkov/theming\n[coveralls-image]: https://img.shields.io/coveralls/iamstarkov/theming.svg?style=flat-square\n\n[depstat-url]: https://david-dm.org/iamstarkov/theming\n[depstat-image]: https://david-dm.org/nordnet/grid.svg?style=flat-square\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcssinjs%2Ftheming","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcssinjs%2Ftheming","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcssinjs%2Ftheming/lists"}