preact-context-provider
Version:
A generic <Provider /> for preact to put props into context
185 lines (132 loc) • 6.32 kB
Markdown
# preact-context-provider
[](http://npm.im/preact-context-provider)
[](https://travis-ci.org/synacor/preact-context-provider)
A generic `<Provider />` for preact. It exposes any props you pass it into context. Also provides a merging variant `<MergingProvider />`, and utility functions `provide` and `mergingProvide`
## Usage
Install it via npm:
```sh
npm install --save preact-context-provider
# or, for Preact X support
npm install --save preact-context-provider@preactx
```
Then import it and use:
```js
import Provider from 'preact-context-provider';
let OBJ = { a: 'b' };
const App = (props, context) => {
// now it's exposed to context!
console.log(context.obj === OBJ) // true
};
render(
<Provider obj={OBJ}>
<App />
</Provider>
);
```
## Preact Version Support
By default, the `master` branch of this repo supports preact 9 and below, and is published in normal patch/minor/major releases to the `latest` tag in npm. Support for preact X (versions 10+ of preact) is handled in the `preactX` branch and are always published to the `preactx` tag in npm. When preact X obtains widespread adoption, the `master` branch of this project will support preact X and a new major version under `latest` tag will be published to in npm.
## API
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
#### Table of Contents
- [Provider](#provider)
- [Parameters](#parameters)
- [Examples](#examples)
- [MergingProvider](#mergingprovider)
- [Parameters](#parameters-1)
- [Examples](#examples-1)
- [provide](#provide)
- [Parameters](#parameters-2)
- [Examples](#examples-2)
- [mergingProvide](#mergingprovide)
- [Parameters](#parameters-3)
- [Examples](#examples-3)
### Provider
Adds all passed `props`, `children` into `context`, making them available to all descendants.
To learn about `context`, see the [React Docs](https://facebook.github.io/react/docs/context.html).
#### Parameters
- `props` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** All props are exposed as properties in `context`, except children
#### Examples
```javascript
const Demo = (props, context) => {
console.log(context); // "{ a: 'b' }"
};
render(
<Provider a="b">
<Demo />
</Provider>
);
// "{ a: 'b' }"
// lower-level providers override higher providers for any keys that they define
render(
<Provider a={key1: 'foo'} b={key2: 'bar'}>
<Provider a={key3: 'buz'} >
<Demo />
</Provider>
</Provider>
);
// "{ a: { key3: 'buz' }, b: { key2: 'bar' } }"
```
### MergingProvider
Similar to [Provider](#provider), but allows a special `mergeProps` prop to allow parent supplied context keys with the same name as those
provided by the current `MergingProvider` to be deep merged, instead of replaced.
To learn about `context`, see the [React Docs](https://facebook.github.io/react/docs/context.html).
#### Parameters
- `props` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** All props are exposed as properties in `context`, except `children` and `mergeProps`
- `props.mergeProps` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** If not supplied, all supplied props will be merged with keys already in context. If supplied as an array of strings,
it will deep merge any prop names that are present in the array, and missing prop names be overriden by the child like [Provider](#provider).
#### Examples
```javascript
import Provider, { MergingProvider } from 'preact-context-provider';
const Demo = (props, context) => {
console.log(context); // "{ a: 'b' }"
};
// with mergeProps unspecified, all parent context keys are merged with the ones presently supplied, parent values taking precedence
render(
<Provider a={key1: 'foo'}>
<MergingProvider a={key2: 'bar'}>
<Demo />
</MergingProvider>
</Provider>
);
// "{ a: { key1: 'foo', key2: 'bar' } }"
// when mergeProps is an array, only specified keys are merged, non-specified keys get their value from current node
// in this example, only the 'a' context key is merged. 'b' is overwritten by the lower node
render(
<Provider a={key1: 'foo'} b={key2: 'bar'}>
<MergingProvider mergeProps={['a']} a={key3: 'baz'} b={key4: 'buz'}>
<Demo />
</MergingProvider>
</Provider>
);
// "{ a: { key1: 'foo', key3: 'baz' }, b: {key4: 'buz'} }"
```
### provide
Higher Order Component that wraps components in a [Provider](#provider) for the given context.
#### Parameters
- `ctx` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Properties to pass into context (passed to [Provider](#provider))
#### Examples
```javascript
import {provide} from 'preact-context-provider';
const Demo = (props, context) => {
console.log(context.a); // "b"
};
const ProvidedDemo = provide({a: "b"})(Demo);
ProvidedDemo.getWrappedComponent() === Demo; // true
render( <ProvidedDemo /> );
```
Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** A function that, given a Child component, wraps it in a Provider component for the given context.
### mergingProvide
Higher Order Component that wraps components in a [MergingProvider](#mergingprovider) for the given context.
#### Parameters
- `ctx` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Properties to pass into context (passed to [MergingProvider](#mergingprovider))
#### Examples
```javascript
import {mergingProvide} from 'preact-context-provider';
const Demo = (props, context) => {
console.log(context.a);
};
const ProvidedDemo = mergingProvide({a: "b"})(Demo);
ProvidedDemo.getWrappedComponent() === Demo; // true
render( <ProvidedDemo /> ); // "b"
```
Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** A function that, given a Child component, wraps it in a [MergingProvider](#mergingprovider) component for the given context.