# @toggles/react-experiment

A React component to load Toggles experiments and render active or inactive children.

## Install

Install with [npm](https://www.npmjs.com/).

```sh
$ npm i @toggles/experiments @toggles/react-experiment
```

Please note the peer dependency, `@toggles/experiments`, which will allow you to load experiments from the Toggles API.

## Usage
Please visit the [Toggles app online](https://toggles.app/). There, you can create an account and an experiment, configure specific users who should see the experiment, or specify a percent of users who should see the experiment.

Once this is complete, you can add an experiment provider to your app:

```jsx
import React from 'react'
import Experiment from '@toggles/react-experiment'

const MyApp = () => <div>
  <Experiment.Provider
    apiKey="KEY"
    context={{uniqueId: "test.user@toggles.app"}}
    rapidAPIKey="KEY"
  >
    <SomeComponent />
  </Experiment.Provider>
</div>
```

The `apiKey` prop will be the API key from the settings tab in the Toggles app.

Next, copy an experiment id from an experiment card in the Toggles app. Add the following component, with that experiment id, in your app:

```jsx
import React from 'react'
import Experiment from '@toggles/react-experiment'

export const AlwaysBlue = () => <div>
  <Experiment
    alwaysRenderInactive={false}
    experimentId="ID">
    <Experiment.Active>
      <span red>JK, I'm red!</span>
    </Experiment.Active>
    <Experiment.Inactive>
      <span blue>I'm blue! Huzzah!</span>
    </Experiment.Inactive>
  </Experiment>
</div>

export default AlwaysBlue
```

**NOTE**: No children passed to the `Experiment` component besides `Active` or `Inactive` will be rendered.

If you need access to raw experiments, you may use the `withExperiments` connector:

```jsx
import React from 'react'
import {withExperiments} from '@toggles/react-experiment'

export const AlwaysBlue = withExperiments({experiments}) => {
  return <div>
    {experiment['ID'].active ? 'JK, I’m red!' : 'I’m blue! Huzzah!'}
  </div>
})

export default AlwaysBlue
```

Experiments will be made available with name, description, uuid, and active/inactive state for the provided context. For more information on using experiment contexts, please see [@toggles/experiments](https://www.npmjs.com/package/@toggles/experiments "@toggles/experiments")

## Props

### Experiment.Provider

| Name                        | Type          | Description                                    | Default                       |
| --------------------------- | ------------- | ---------------------------------------------- | ----------------------------- |
| apiKey                      | string        | Toggles API Key                                |                               |
| apiUrl                      | string        | API Url: use a RapidAPI host if using RapidAPI | "https://api.toggles.co"      |
| context                     | object|string | Context used to uniquely identify a user       |                               |
| rapidAPIKey                 | string        | RapidAPI Key                                   |                               |

`context` is either of type `shape`, which supports a single property, `uniqueId`, or a string. This property represents identifying information about a user and may be used to blacklist or whitelist active experiment users.

**NOTE**: If you pass a RapidAPI Key it will be used with preference to the Toggles API Key.

### Experiment.Provider

| Name                        | Type          | Description                                    | Default                       |
| --------------------------- | ------------- | ---------------------------------------------- | ----------------------------- |
| alwaysRenderInactive        | bool          | Should inactive render before API response     | `false`                       |
| experimentId                | string        | A Toggles experiment id                        |                               |

## Contributing

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/Joe%20Groseclose/react-experiment/issues).

## License

Copyright © 2019 []
Licensed under the MIT license.

***

_This file was generated by [readme-generator](https://github.com/jonschlinkert/readme-generator) on June 21, 2019._