react-themed
A flexible library for styling React components. Intended for projects using global CSS, JSS, CSS Modules, or any other CSS in JS based library that compiles CSS classname objects.
Documentation
Features
- A higher-order React component for injecting and customizing styles.
- A provider component for supplying context themes.
- Tools for theme composition and transformation.
Installation
Install the stable version:
$ npm i --save react-themed
Terminology
theme
A plain object containing CSS classnames used by one or more React components.
theme composition
The merging of two or more theme objects, where values for overlapping keys are concatenated.
const theme1 = list: 'list' item: 'list-item' const theme2 = list: 'list-inline' // => { list: 'list list-inline', item: 'list-item' }
Basic Usage
The HOC provided by react-themed
can be used as a ES7 decorator, or a curried function. It allows you to inject themes into a React component (as a prop), customize themed components, and configure the wrapping component.
Use ES7 decorator
@ <button ...props className=themebutton />
Use curried function
const Button = <button ...props className=themebutton /> stylesButton
Configure wrapping component
@ <button ...props className=classesbutton />
Theme Composition
Themes can be composed in the following ways:
Compose theme objects
{} defaultStyles primaryStyles
Compose components
const Button = <button ...props className=themebutton /> const Default = Buttonconst Primary = Default
Compose during render
const buttonStyles = button: stylesbutton <form className=stylesform> <Button theme=buttonStyles>Submit</Button> </form>
Customize theme (e.g. for regular merging)
...prevStyles ...primaryStylesButton
Context Themes
While this library does not require a specific shape for context theme objects, the following tend to work well:
// Flatconst theme = Button: 'button' Button_primary: 'button-primary' // Nestedconst theme = Button: button: 'button' primary: 'button-primary'
Activate a context theme
const App = <ThemeProvider theme=propstheme /> propschildren </ThemeProvider>
Apply a context theme
const Button = <button ...props className=themeButton /> // select entire context themeButton // select single classname (or nested theme)Button // select multiple classnamesButton // select all classnames starting with "Button"Button
Customize context themes
@ <button ...props className=themebutton />
API Reference
<ThemeProvider theme [compose]>
Adds theme to a React component context, making it available to themed()
calls.
theme
(Object|Function): Can be either a theme object, or a function that receives a previously added theme, and is expected to return the final theme to use.compose
(Bool): Indicates whether the theme should be composed with previously added themes (does not apply to function themes). Defaults totrue
.
themed([theme], [options])
Creates a new HOC for generating a Themed
component.
theme
(Object|String|Array|Function): The theme to bind to the component. Can be either a plain object, a string/array for selecting context theme(s), or a function that receives the previously assigned theme (if any) and context theme (if any), and is expected to return the final theme to use.options
(Object): Configures the default options for theThemed
component.propName
(String): The name of the prop that receives the theme, defaults totheme
.pure
(Bool): Indicates the component should inherit fromPureComponent
.compose
(Func): Specifies the default function to use when composing themes.mergeProps(ownProps, themeProps): props
(Function): If specified, it is passed the parent props and theme props, and is expected to return a merged object to pass as props to the wrapped component.
themed.extend(options)
Creates a new themed
function that uses a customized set of default options when generating themed components.
options
(Object): The options to merge into the previous default options.
<Themed [theme] [childRef]>
The themed component created by the themed
decorator.
theme
(Object|String|Array|Function): A theme or context theme (selector) that should be composed with the previous theme, or a function that customizes the previous theme.childRef
(Function*): Specifies a ref callback function to pass to the wrapped component.
compose(target, ...themes)
Recursively merges theme objects by concatenating values for overlapping keys, and copies result into a target object.
License
MIT