React Multiselect Checkboxes

A flexible, stylable, compact multi-select component.

It's based on react-select and has a similar API for data and styling.

Installation

npm i -S react-multiselect-checkboxes

Basic usage

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)

| 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)

| 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)

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
• [ ] ???