---
[![Build Status][build-badge]][build]
[![Version][version-badge]][package]
[![MIT License][license-badge]][license]
## About
`@callstack/react-theme-provider` is a set of utilities that help you create your own theming system in few easy steps.
You can use it to customize colors, fonts, etc.
## Features
- works in **React** and **React Native**
- `ThemeProvider` - component
- `withTheme` - Higher Order Component
- `createTheming(defaultTheme)` - factory returns `ThemeProvider` component and `withTheme` HOC with default theme injected.
## Examples
- buildin example for web react - ['/examples/web'](/examples/web)
- [](https://codesandbox.io/s/v6o562k6l7)
## Getting started
### Instalation
```
npm install --save @callstack/react-theme-provider
```
or using yarn
```
yarn add @callstack/react-theme-provider
```
### Usage
To use, simply wrap your code into `ThemeProvider` component and pass your theme as a `theme` prop.
```js
```
You could access theme data inside every component by wraping it into `withTheme` HOC. Just like this:
```js
class App extends React.Component {
render() {
return (
Hello
);
}
}
export default withTheme(App);
```
## `ThemeProvider`
**type:**
```js
type ThemeProviderType = React.ComponentType<{
children?: any,
theme: T,
}>
```
Component you have to use to provide the theme to any component wrapped in `withTheme` HOC.
### props
-`theme` - your theme object
## `withTheme`
**type:**
```js
type WithThemeType = >(
Comp: C
) => C &
React.ComponentType<
$Diff, { theme: T }> & { theme?: S }
>;
```
Classic Higher Order Component which takes your component as an argument and injects `theme` prop into it.
### Example of usage
```js
const App = ({ theme }) => (
Hello
);
export withTheme(App);
```
### Injected props
It will inject the following props to the component:
- `theme` - our theme object.
- `getWrappedInstance` - exposed by some HOCs like react-redux's `connect`.
Use it to get the ref of the underlying element.
### Injecting theme by a direct prop
You can also override `theme` provided by `ThemeProvider` by setting `theme` prop on the component wrapped in `withTheme` HOC.
Just like this:
```js
const Button = withTheme(({ theme }) => (
Click me
));
const App = () => (
)
```
In this example Button will have green text.
## `createTheming`
**type:**
```js
(defaultTheme: T) => {
ThemeProvider: ThemeProviderType,
withTheme: WithThemeType,
}
```
This is more advanced replacement to classic importing `ThemeProvider` and `withTheme` directly from the library.
Thanks to it you can create your own ThemeProvider with any default theme.
Returns instance of `ThemeProvider` component and `withTheme` HOC.
You can use this factory to create a singleton with your instances of `ThemeProvider` and `withTheme`.
>**Note:** `ThemeProvider` and `withTheme` generated by `createTheming` always will use different context so make sure you are using matching `withTheme`!
If you acidentially import `withTheme` from `@callstack/react-theme-provider` instead of your theming instance it won't work.
### Arguments
- `defaultTheme` - default theme object
### Benefits
- Possibility to define `flow` types for your theme
- Possibility to pass default theme
- You can use multiple `ThemeProvider`s in your app without any conflicts.
### Example of usage
```js
// theming.js
import { createTheming } from '@callstack/react-theme-provider';
const { ThemeProvider, withTheme } = createTheming({
primaryColor: 'red',
secondaryColor: 'green',
});
export { ThemeProvider, withTheme };
//App.js
import { ThemeProvider, withTheme } from './theming';
```
## Applying a custom theme to a component
If you want to change the theme for a certain component, you can directly pass the theme prop to the component. The theme passed as the prop is merged with the theme from the Provider.
```js
import * as React from 'react';
import MyButton from './MyButton';
export default function ButtonExample() {
return (
Press me
);
}
```
## Gotchas
The `ThemeProvider` exposes the theme to the components via [React's context API](https://reactjs.org/docs/context.html),
which means that the component must be in the same tree as the `ThemeProvider`. Some React Native components will render a
different tree such as a `Modal`, in which case the components inside the `Modal` won't be able to access the theme. The work
around is to get the theme using the `withTheme` HOC and pass it down to the components as props, or expose it again with the
exported `ThemeProvider` component.
[build-badge]: https://img.shields.io/circleci/project/github/callstack/react-theme-provider/master.svg?style=flat-square
[build]: https://circleci.com/gh/callstack/react-theme-provider
[version-badge]: https://img.shields.io/npm/v/@callstack/react-theme-provider.svg?style=flat-square
[package]: https://www.npmjs.com/package/@callstack/react-theme-provider
[license-badge]: https://img.shields.io/npm/l/react-theme-provider.svg?style=flat-square
[license]: https://opensource.org/licenses/MIT
[chat-badge]: https://img.shields.io/badge/chat-slack-brightgreen.svg?style=flat-square&colorB=E01563
[chat]: https://slack.callstack.com/
