## Table of contents
* [Motivation](#motivation)
* [Inspiration](#inspiration)
* [Installation](#installation)
* [Components](#components)
* [OnOff](#onoff)
* [OnOffCollection](#onoffcollection)
* [OnOffItem](#onoffitem)
* [Related](#related)
* [License](#license)
## Motivation
Many UI components either have a single or multiple on/off states and require
you to write the same type of stateful React components over and over again.
It's not hard, but it takes time and duplicates code. Instead, we can extract
common state requirements into generic, flexible and well-tested components
and reuse them. This is what `react-on-off` is.
## Inspiration
All credit for the design and API should go to
[`react-toggled`](https://github.com/kentcdodds/react-toggled). If you only need
to render a toggle component, go with `react-toggled` since it comes with
functions that help with accessibility. If you're handling accessibility by
yourself or you need to manage multiple on/off states, `react-on-off` is for
you.
## Installation
```sh
npm install --save react-on-off
# or
yarn add react-on-off
```
You can also use UMD builds from unpkg:
```html
```
## Components
### `OnOff`
Manages a single, independent on/off state. Useful whenever you need to render
something with two states.
#### Usage
```js
import React from "react";
import { render } from "react-dom";
import { OnOff } from "react-on-off";
render(
{({ on, toggle }) => (
<>
{on ? "Red" : "Blue"}
)}
,
document.getElementById("root")
);
```
#### Props
| Prop | Type | Default | Description |
| --------------------------- | ---------- | ------- | ---------------------------------------------------------------------------------------- |
| `defaultOn` _optional_ | `boolean` | `false` | The initial `on` state. |
| `on` _optional_ | `boolean` | – | Control prop if you want to control the state by yourself. |
| `onChange` _optional_ | `function` | – | Called whenever the state changes with the new `on` state. |
| `children` _required_ | `function` | – | A render prop. This is where you render whatever you want based on the state of `OnOff`. |
#### Render object
`OnOff` expects the `children` prop to be a function. It is called with a
single argument, an object with the following properties:
| Property | Type | Description |
| -------- | ---------- | ---------------------------------------------------------------------- |
| `on` | `boolean` | `true` if the state is on, `false` otherwise. |
| `off` | `boolean` | Convenience property if you need `!on`. |
| `setOn` | `function` | Sets the state to on. |
| `setOff` | `function` | Sets the state to off. |
| `toggle` | `function` | Toggles the state (i.e. when it's on, will set to off and vice versa). |
### `OnOffCollection`
Manages multiple on/off states where only one state can be on at all times. To
render the indivial on/off states, use `OnOffItem` anywhere inside an
`OnOffCollection` parent.
#### Usage
```js
import React from "react";
import { render } from "react-dom";
import { OnOffCollection, OnOffItem } from "react-on-off";
render(
,
document.getElementById("root")
);
```
#### Props
| Prop | Type | Default | Description |
| --------------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `defaultOn` _optional_ | `string` | – | The item id that should be on initially. |
| `on` _optional_ | `string` | – | Control prop if you want to control which item should be on. Either an id or `null` if no item should be on. |
| `onChange` _optional_ | `function` | – | Called whenever the state changes with the item id that is on. |
### `OnOffItem`
Represents a single on/off state that is coupled to other on/off states. Doesn't
do anything without an `OnOffCollection` parent.
#### Usage
See [`OnOffCollection` Usage](#usage-1)
#### Props
| Prop | Type | Default | Description |
| -------------------------- | ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------- |
| `id` _optional_ | `string` | a unique id | Only useful in combination with the `defaultOn` or `onChange` prop from `OnOffCollection`. Defaults to a unique id. |
| `children` _required_ | `function` | – | A render prop. This is where you render whatever you want based on the state of the `OnOffItem`. |
#### Render object
`OnOffItem` expects the `children` prop to be a function. It is called with a
single argument, an object with the following properties:
| Property | Type | Description |
| -------- | ---------- | ---------------------------------------------------------------------------------- |
| `id` | `string` | The state id you set yourself or a generated unique id. |
| `on` | `boolean` | `true` if the state is on, `false` otherwise. |
| `off` | `boolean` | Convenience property if you need `!on`. |
| `setOn` | `function` | Sets the state of the item to on. |
| `setOff` | `function` | Sets the state of the item to off. |
| `toggle` | `function` | Toggles the state of the item (i.e. when it's on, will set to off and vice versa). |
## Related
* [react-toggled](https://github.com/kentcdodds/react-toggled)
* [react-powerplug](https://github.com/renatorib/react-powerplug)
## License
MIT
