-
Notifications
You must be signed in to change notification settings - Fork 673
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
custom-properties: extend ThemeProvider to insert CSS Custom Props
- Loading branch information
Showing
5 changed files
with
165 additions
and
20 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,40 +1,116 @@ | ||
| # @theme-ui/custom-properties | ||
|
|
||
| Generate CSS custom properties for use with Theme UI. | ||
| Extend [ThemeUI](https://theme-ui.com)'s core functionality with CSS Custom Properties. | ||
|
|
||
| https://theme-ui.com | ||
|
|
||
| ## Installation | ||
|
|
||
| ``` | ||
| yarn add @theme-ui/custom-properties | ||
| ``` | ||
|
|
||
| ## API | ||
|
|
||
| ## Usage | ||
| ### toCustomProperties | ||
|
|
||
| Transform your Theme UI compliant theme config with the library: | ||
| Transform your Theme UI compliant theme to an object of CSS Custom Properties. | ||
|
|
||
| ```js | ||
| const toCustomProperties = require('@theme-ui/custom-properties') | ||
| const theme = require('../theme'); | ||
| **Type**: `Function` | ||
|
|
||
| module.exports = () => { | ||
| const customProperties = toCustomProperties(theme, '🍭'); | ||
| **Parameters**: | ||
| 1. theme - The theme ui specification object | ||
| 2. prefix - An optional string prefix for the css custom property (_optional_) | ||
|
|
||
| return customProperties; | ||
| **Returns**: `Object` | ||
| ```js | ||
| { | ||
| '--color-primary': '#2980b9', | ||
| '--color-secondary': '#f7df1e', | ||
| '--fontSize-0': 12, | ||
| ' -fontSize-1': 14, | ||
| '--fontSize-2': 16, | ||
| '--fontSize-3': 24, | ||
| '--fontSize-4': 32, | ||
| '--fontSize-5': 48, | ||
| '--fontSize-6': 64 | ||
| } | ||
| ``` | ||
|
|
||
| **Example**: | ||
| ```js | ||
| import { toCustomProperties } from '@theme-ui/custom-properties'; | ||
| import theme from '../theme'; | ||
|
|
||
| ## Parameters | ||
| const customProperties = toCustomProperties(theme, '🍭'); | ||
| console.log(customProperties); | ||
| ``` | ||
|
|
||
| The @theme-ui/custom-properties function takes two parameters: | ||
| ### withCustomProperties | ||
| Extend the base `ThemeProvider` to allow native styling by using CSS Custom Properties. | ||
|
|
||
| ```js | ||
| toCustomProperties( $theme, $prefix ); | ||
| **Type**: `Function` | ||
|
|
||
| **Parameters**: | ||
| 1. prefix - An optional string prefix for the css custom property (_optional_) | ||
|
|
||
| **Returns** a React Component which extends the default `ThemeProvider` by adding CSS Custom Properties to the wrapper element. | ||
|
|
||
| For example: | ||
|
|
||
| ```jsx | ||
| const ExtendedThemeProvider = withCustomProperties('app-name'); | ||
|
|
||
| ReactDOM.render( | ||
| <ExtendedThemeProvider theme={theme}> | ||
| <p> Hello world! </p> | ||
| </ExtendedThemeProvider>, | ||
| root | ||
| ); | ||
| ``` | ||
|
|
||
| 1. theme - The theme ui specification object | ||
| 1. prefix - An optional prefix for the css custom property _optional_ | ||
| Then in CSS we can do something like: | ||
|
|
||
| ```css | ||
| p { | ||
| color: var(--app-name-color-primary); | ||
| background: var(--app-name-color-secondary); | ||
| } | ||
| ``` | ||
|
|
||
| These CSS Custom Properties are in total sync with the theme. Also, sub-theming works as expected. | ||
|
|
||
| ```jsx | ||
| const theme = { | ||
| colors: { | ||
| primary: 'red', | ||
| secondary: 'blue' | ||
| } | ||
| }; | ||
|
|
||
| const subTheme = { | ||
| colors: { | ||
| primary: 'orange' | ||
| } | ||
| }; | ||
|
|
||
| const ExtendedThemeProvider = withCustomProperties('app-name'); | ||
|
|
||
| ReactDOM.render( | ||
| <ExtendedThemeProvider theme={theme}> | ||
| <p> Hello world! </p> // red on a blue background | ||
|
|
||
| <ExtendedThemeProvider theme={subTheme}> | ||
| <p> Hello Aliens! </p> // orange on a blue background | ||
| </ExtendedThemeProvider> | ||
|
|
||
| </ExtendedThemeProvider>, | ||
| root | ||
| ); | ||
| ``` | ||
|
|
||
| ```css | ||
| p { | ||
| color: var(--app-name-color-primary); | ||
| background: var(--app-name-color-secondary); | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters