|
| 1 | +# React use CSS custom properties & Utilities · |
| 2 | + |
| 3 | +> Get or set a css custom property value with a react hook |
| 4 | +
|
| 5 | +This is a [React Hook](https://reactjs.org/docs/hooks-overview.html) which can get or set a CSS variable aka (Custom property). |
| 6 | + |
| 7 | +<!-- START doctoc generated TOC please keep comment here to allow auto update --> |
| 8 | +<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> |
| 9 | + |
| 10 | +**Table of Contents** _generated with [DocToc](https://github.com/thlorenz/doctoc)_ |
| 11 | + |
| 12 | +- [React use CSS custom properties & Utilities ·](#react-use-css-custom-properties-amp-utilities-middot) |
| 13 | + - [Affiliate](#affiliate) |
| 14 | + - [🎯 Objective](#-objective) |
| 15 | + - [🚀 Installation](#-installation) |
| 16 | + - [Usage](#usage) |
| 17 | + - [API](#api) |
| 18 | + - [Parameters](#parameters) |
| 19 | + - [Return Values](#return-values) |
| 20 | + - [Contribute and Commands](#contribute-and-commands) |
| 21 | + - [Jest](#jest) |
| 22 | + - [TypeScript](#typescript) |
| 23 | + - [Continuous Integration](#continuous-integration) |
| 24 | + - [Contributors](#contributors) |
| 25 | + |
| 26 | +<!-- END doctoc generated TOC please keep comment here to allow auto update --> |
| 27 | + |
| 28 | +## Affiliate |
| 29 | + |
| 30 | +If you like to support my OSS work you could "buy me a coffee" or want to take a look on tools I recommend you could checkout. |
| 31 | + |
| 32 | +<table><tr><td align="center"><a href="https://www.buymeacoffee.com/jcofman" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/lato-yellow.png" alt="Buy Me A Coffee" width="201" height="51" ><br /><sub><b>Buy me a coffee</b></sub></a><br /> My personal patreon</a></td><td align="center"><a href="https://a.paddle.com/v2/click/49831/106566?link=1947" target="_blank"><img src="https://img.stackshare.io/service/6882/687474703a2f2f692e696d6775722e636f6d2f446d6d4a56335a2e706e67.png" alt="Buy Me A Coffee" width="50" height="50" ><br /><sub><b>Sizzy</b></sub></a><br /> A super useful App when developing for different screens</a></td></tr></table> |
| 33 | + |
| 34 | +## 🎯 Objective |
| 35 | + |
| 36 | +Sometimes you want to change or get a CSS custom property value inside you react application to use the value inside your js code. You may also want to set and overwrite a CSS custom property. |
| 37 | + |
| 38 | +## 🚀 Installation |
| 39 | + |
| 40 | +`npm i @jcofman/react-use-css-custom-property --save` or `yarn add @jcofman/react-use-css-custom-property` |
| 41 | + |
| 42 | +## Usage |
| 43 | + |
| 44 | +You can import and use the hook like the following example |
| 45 | + |
| 46 | +```js |
| 47 | +import 'react-app-polyfill/ie11'; |
| 48 | +import * as React from 'react'; |
| 49 | +import * as ReactDOM from 'react-dom'; |
| 50 | +import './index.css'; |
| 51 | +import useCSSCustomProperty from '@jcofman/react-use-css-custom-property'; |
| 52 | + |
| 53 | +const App = () => { |
| 54 | + const [firstColor, setFirstColor] = useCSSCustomProperty('--first-color'); |
| 55 | + const [secondColor, setSecondColor] = useCSSCustomProperty('--first-color'); |
| 56 | + return ( |
| 57 | + <div> |
| 58 | + <button onClick={() => setFirstColor('red')}> |
| 59 | + Set first color to red |
| 60 | + </button> |
| 61 | + <p id="firstParagraph"> |
| 62 | + This paragraph should have a {firstColor.propertyValue} background and |
| 63 | + {secondColor.propertyValue} |
| 64 | + </p> |
| 65 | + </div> |
| 66 | + ); |
| 67 | +}; |
| 68 | + |
| 69 | +ReactDOM.render(<App />, document.getElementById('root')); |
| 70 | +``` |
| 71 | + |
| 72 | +and your `index.css` file |
| 73 | + |
| 74 | +```css |
| 75 | +:root { |
| 76 | + --first-color: hotpink; |
| 77 | + --second-color: white; |
| 78 | +} |
| 79 | + |
| 80 | +#firstParagraph { |
| 81 | + background-color: var(--first-color); |
| 82 | + color: var(--second-color); |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +### API |
| 87 | + |
| 88 | +```js |
| 89 | +const [ |
| 90 | + { propertyValue, propertyName, selectedElement, error, status }, |
| 91 | + setCustomCSSProperty, |
| 92 | +] = useCSSCustomProperty(propertyName, query); |
| 93 | +``` |
| 94 | + |
| 95 | +#### Parameters |
| 96 | + |
| 97 | +propertyName: string, query?: string |
| 98 | + |
| 99 | +- `propertyName`: a string for the property name you want to get |
| 100 | +- `query`: (_optional_) a query to get properties from specific HTMLElements default is `:root` |
| 101 | + |
| 102 | +#### Return Values |
| 103 | + |
| 104 | +- `propertyValue`: the current custom prop value |
| 105 | +- `propertyName`: the current custom prop name |
| 106 | +- `selectedElement`: if there's a request or revalidation loading |
| 107 | +- `error`: A string which tells you what went wrong e.g. the CSS custom property does not exist |
| 108 | +- `status`: can have the following three states 'INIT | 'OK' | 'ERROR' |
| 109 | + |
| 110 | +- setCustomCSSProperty: function to mutate the custom property value |
| 111 | + |
| 112 | +## Contribute and Commands |
| 113 | + |
| 114 | +The recommended workflow is to run TSDX in one terminal: |
| 115 | + |
| 116 | +```bash |
| 117 | +npm start # or yarn start |
| 118 | +``` |
| 119 | + |
| 120 | +This builds to `/dist` and runs the project in watch mode so any edits you save inside `src` causes a rebuild to `/dist`. |
| 121 | + |
| 122 | +Then run the example inside another: |
| 123 | + |
| 124 | +```bash |
| 125 | +cd example |
| 126 | +npm i # or yarn to install dependencies |
| 127 | +npm start # or yarn start |
| 128 | +``` |
| 129 | + |
| 130 | +The default example imports and live reloads whatever is in `/dist`, so if you are seeing an out of date component, make sure TSDX is running in watch mode like we recommend above. **No symlinking required**, [we use Parcel's aliasing](https://github.com/palmerhq/tsdx/pull/88/files). |
| 131 | + |
| 132 | +To do a one-off build, use `npm run build` or `yarn build`. |
| 133 | + |
| 134 | +To run tests, use `npm test` or `yarn test`. |
| 135 | + |
| 136 | +### Jest |
| 137 | + |
| 138 | +Jest tests are set up to run with `npm test` or `yarn test`. This runs the test watcher (Jest) in an interactive mode. By default, runs tests related to files changed since the last commit. |
| 139 | + |
| 140 | +### TypeScript |
| 141 | + |
| 142 | +`tsconfig.json` is set up to interpret `dom` and `esnext` types, as well as `react` for `jsx`. Adjust according to your needs. |
| 143 | + |
| 144 | +## Continuous Integration |
| 145 | + |
| 146 | +## Contributors |
| 147 | + |
| 148 | +Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): |
| 149 | + |
| 150 | +<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> |
| 151 | +<!-- prettier-ignore --> |
| 152 | +<table><tr><td align="center"><a href="https://jcofman.de"><img src="https://avatars2.githubusercontent.com/u/2118956?v=4" width="100px;" alt="Jacob Cofman"/><br /><sub><b>Jacob Cofman</b></sub></a><br /><a href="https://github.com/JCofman/jc-website/commits?author=JCofman" title="Code">💻</a></td></tr></table> |
| 153 | + |
| 154 | +<!-- ALL-CONTRIBUTORS-LIST:END --> |
| 155 | + |
| 156 | +This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! |
0 commit comments