@asphalt-react/theme-provider/README.md

Theme provider for Asphalt React

# ThemeProvider

![npm](https://img.shields.io/npm/dt/@asphalt-react/theme-provider?style=flat-square)
[![npm version](https://badge.fury.io/js/@asphalt-react%2Ftheme-provider.svg)](https://badge.fury.io/js/@asphalt-react%2Ftheme-provider)

ThemeProvider allows you to theme your app. You can even nest ThemeProviders to apply a theme on just a section of your app as well.

> ⚠️ ThemeProvider only works in [secure contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts)

## Usage

```jsx
import { ThemeProvider } from "@asphalt-react/theme-provider"
import { Button } from "@asphalt-react/button"

const customTheme = {
  // your theme tokens
}

function App() {
  return (
    <ThemeProvider theme={customTheme}>
      <Button>Click me</Button>
    </ThemeProvider>
  )
} 
```

## Available themes

Asphalt web support these themes:

1. Lyra - Default theme
2. [Aloha](https://www.npmjs.com/package/@gojek/theme-asphalt-web-aloha)
3. [Carina](https://www.npmjs.com/package/@gojek/theme-asphalt-web-carina)
4. [Draco](https://www.npmjs.com/package/@gojek/theme-asphalt-web-draco)
5. [Lynx](https://www.npmjs.com/package/@gojek/theme-asphalt-web-lynx)
6. [Vela](https://www.npmjs.com/package/@gojek/theme-asphalt-web-vela)

And here is how to use Asphalt web themes with Theme Provider

```jsx
import { ThemeProvider } from "@asphalt-react/theme-provider";
import { lynx } from "@gojek/theme-asphalt-web-lynx"; // import the theme here
import { Button } from "@asphalt-react/button";

export const App = () => {
  return (
    // add imported theme in the ThemeProvider theme prop
    <ThemeProvider theme={lynx}>
      <h2>Themed App</h2>
      <Button>Hello</Button>
    </ThemeProvider>
  );
};
```

## Responsive theme

`ThemeProvider` supports responsive theming. When `responsive` is set to `true` and the theme includes a `mobile` or `desktop` key, the theme values will be applied under a media query — `@media (max-width: 599px)` for mobile and `@media (min-width: 1280px)` for desktop.

```jsx
import { ThemeProvider } from "@asphalt-react/theme-provider"
import { Button } from "@asphalt-react/button"

const theme = {
  "--display-L": "700 2rem/1.618 Maison Neue Extended, Helvetica, Open Sans, sans-serif",
  "--heading-L": "600 1.25rem/1.30 Maison Neue, Helvetica, Open Sans, sans-serif",
  mobile: {
    "--display-L": "700 1.5rem/1.5 Maison Neue Extended, Helvetica, Open Sans, sans-serif",
    "--heading-L": "600 1.25rem/1.30 Maison Neue, Helvetica, Open Sans, sans-serif",
  }
}

function App() {
  return (
    <ThemeProvider theme={theme} responsive>
      <Button>Responsive</Button>
    </ThemeProvider>
  )
}
```

[comment]: # "ThemeProvider Props"

## Props

### children

React node or node tree to apply theme to.

| type | required | default |
| ---- | -------- | ------- |
| node | true     | N/A     |

### theme

Asphalt Theme object.

| type   | required | default |
| ------ | -------- | ------- |
| object | false    | null    |

### as

Html element/React component to render as container.

| type        | required | default |
| ----------- | -------- | ------- |
| elementType | false    | "div"   |

### wrap

Wrap children with a container element.
Set to false to apply globally.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

### responsive

Enables responsive theming. When true, theme will include mobile or desktop media queries if mobile or desktop keys are present in the theme object.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |