react-multiselect-checkboxes/README.md

Spiffy multiselect with checkboxes

# React Multiselect Checkboxes

A flexible, stylable, compact multi-select component. 

It's based on [`react-select`](https://github.com/JedWatson/react-select) and has a similar API for data and styling.

![An image of the component](https://user-images.githubusercontent.com/2994372/44043882-ed30c560-9ef1-11e8-9021-1e4d14f8530f.png)

## Installation

```bash
npm i -S react-multiselect-checkboxes
```

## Basic usage

```jsx
import ReactMultiSelectCheckboxes from 'react-multiselect-checkboxes';

// ...
const options = [
  { label: 'Thing 1', value: 1},
  { label: 'Thing 2', value: 2},
];
<ReactMultiSelectCheckboxes options={options} />
```

## Props

Nearly all of the options from [react-select]() are supported, except where they don't make sense (for instance, `isMulti={false}` isn't supported, since this is always in multi-select mode). These props are passed directly to the underlying `Select` component. In addition, there are some options  which are specific to `react-multiselect-checkboxes`:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placeholderButtonLabel`| `PropTypes.string`  | `'Select...'` | Displayed on dropdown button if no value is selected. |
| `getDropdownButtonLabel`  | `PropTypes.func`  | `({ placeholderButtonLabel, value }) => {/* if-else logic*/}` | Get the label for the dropdown, based on the placeholder and the current value. By default this is (a) the placeholder, if nothing is selected; (b) the selected value's label, if one option is selected; or (c) the number selected (e.g. "3 selected") if more than one option is selected |
| `rightAligned` | `PropTypes.bool` | `false` | Whether to align the menu to the right side of the component. By default it's flush with the left. |

## Styling

Like props, styles supported by react-select are passed directly into the underlying `Select` component. Some of the defaults have been tweaked for the multiselect, but you can override them like normal (see https://react-select.com/styles). In addition, there are some styles which are specific to `react-multiselect-checkboxes`:

| Style key  | Options | Description | Screenshot |
| --- | --- | --- | --- |
| `dropdownButton` | `{ value, isOpen, width }`| Used to style the dropdown button component. Pressing this component opens the menu. | |
| `groupHeading` | `{ checked, indeterminate }`| This exists in react-select already -- it's used to style the group heading label. We add two new options based on the selected state of the group: `checked` is true if all options in the group are selected, `indeterminate` if only some are selected.| |

## Component replacement

Again, we're taking this API straight from `react-select`, and you can replace any of the basic `Select` components as well. There are some new components which are specific to `react-multiselect-checkboxes` too:

### `Dropdown` ([source](https://github.com/twineteam/react-multiselect-checkboxes/blob/master/src/lib/Dropdown.jsx))

| Prop | Type  | Description |
| --- | --- | --- |
| `children`| `PropTypes.node` | The children _for the menu_. Note: this is _not_ the dropdown button / click target. |
| `isOpen`  | `PropTypes.bool`  | Is the Dropdown open right now? |
| `rightAligned` | `PropTypes.bool` | Whether to align the menu to the right side of the component. By default it's flush with the left. |
| `onClose` | `PropTypes.func` | Callback function to run when the menu is closed. In the default implementation this happens on outside click. |
| `target` | `PropTypes.node` | The dropdown button / click target. Clicking on this will generally open the menu. |

### `DropdownButton` ([source](https://github.com/twineteam/react-multiselect-checkboxes/blob/master/src/lib/DropdownButton.jsx))

| Prop | Type  | Description |
| --- | --- | --- |
| `children`| `PropTypes.node` | The contents of the dropdown button, generally a string. |
| `onPress` | `PropTypes.func` | Callback function to run when the dropdown button is pressed. This will generally open the menu. |
| `iconAfter` | `PropTypes.node` | An icon component to render after the button's contents. By default it's a down-facing chevron. |
| `style`  | `PropTypes.object`  | The style to apply to the dropdown button. If you're doing custom styling, you'll probably ignore it. |

### `DropdownButtonIcon` ([source](https://github.com/twineteam/react-multiselect-checkboxes/blob/master/src/lib/ChevronDown.jsx))

No props, this is just a down-facing chevron icon, in SVG form.

## Road to 1.0

- [ ] Fire up the Github.io site
- [ ] Allow replacing more props (e.g. `Menu`)
- [ ] Tests
- [ ] More comprehensive storybook
- [ ] ???