<!---
THIS IS AN AUTOGENERATED FILE. EDIT PACKAGES/BOUNDLESS-CHECKBOX-GROUP/INDEX.JS INSTEAD.
-->
# CheckboxGroup

The most common use case for `CheckboxGroup` is a "select all" / children scenario. This particular
configuration is built-in and is activated by passing the `selectAll` prop.

## Installation

```bash
npm i boundless-checkbox-group --save
```

Then use it like:


```jsx
/** @jsx createElement */

import { createElement, PureComponent } from 'react';
import CheckboxGroup from 'boundless-checkbox-group';
import { filter, map, merge, some } from 'lodash';

export default class CheckboxGroupDemo extends PureComponent {
    state = {
        items: [ {
            inputProps: {
                checked: false,
                name: 'likes-science',
            },
            label: 'Science',
        }, {
            inputProps: {
                checked: false,
                name: 'likes-math',
            },
            label: 'Mathematics',
        }, {
            inputProps: {
                checked: false,
                name: 'likes-tech',
            },
            label: 'Technology',
        }, {
            inputProps: {
                checked: false,
                name: 'likes-art',
            },
            label: 'Art',
        }, {
            inputProps: {
                checked: false,
                name: 'likes-sports',
            },
            label: 'Sports',
        } ],
    }

    mutateAll(delta) {
        this.setState({
            items: map(this.state.items, function transformer(item) {
                return merge({}, item, delta);
            }),
        });
    }

    mutateOne(name, delta) {
        this.setState({
            items: map(this.state.items, function transformer(item) {
                if (item.inputProps.name !== name) {
                    return item;
                }

                return merge({}, item, delta);
            }),
        });
    }

    handleAllChecked = () => {
        this.mutateAll({ inputProps: { checked: true } });
    }

    handleAllUnchecked = () => {
        this.mutateAll({ inputProps: { checked: false } });
    }

    handleChildChecked = (name) => {
        this.mutateOne(name, { inputProps: { checked: true } });
    }

    handleChildUnchecked = (name) => {
        this.mutateOne(name, { inputProps: { checked: false } });
    }

    renderFeedback() {
        if (some(this.state.items, { inputProps: { checked: true } })) {
            const liked = map(filter(this.state.items, { inputProps: { checked: true } }), 'label');
            const lastIndex = liked.length - 1;

            return (
                <p>You said you like: {liked.length === 1 ? liked[0] : [ liked.slice(0, lastIndex).join(', '), 'and', liked.slice(lastIndex) ].join(' ')}.</p>
            );
        }
    }

    render() {
        return (
            <div>
                <p>What subjects are you interested in?</p>
                <CheckboxGroup
                    className='checkbox-group-demo'
                    items={this.state.items}
                    selectAll={CheckboxGroup.selectAll.AFTER}
                    selectAllProps={{ label: 'All of the above' }}
                    onAllChecked={this.handleAllChecked}
                    onAllUnchecked={this.handleAllUnchecked}
                    onChildChecked={this.handleChildChecked}
                    onChildUnchecked={this.handleChildUnchecked} />
                    <br />
                {this.renderFeedback()}
            </div>
        );
    }
}
```


CheckboxGroup can also just be directly used from the main [Boundless library](https://www.npmjs.com/package/boundless). This is recommended when you're getting started to avoid maintaining the package versions of several components:

```bash
npm i boundless --save
```

the ES6 `import` statement then becomes like:

```js
import { CheckboxGroup } from 'boundless';
```


## Props

> Note: only top-level props are in the README, for the full list check out the [website](https://boundless.js.org/CheckboxGroup).

### Required Props

- __`items`__ &middot; the data wished to be rendered, each item must conform to the [Checkbox prop spec](https://github.com/enigma-io/boundless/blob/master/packages/boundless-checkbox)

  Expects | Default Value
  ---     | ---
  `array` | `[]`


### Optional Props

- __`*`__ &middot; any [React-supported attribute](https://facebook.github.io/react/docs/tags-and-attributes.html#html-attributes)

  Expects | Default Value
  ---     | ---
  `any` | `n/a`

- __`component`__ &middot; override the wrapper HTML element if desired

  Expects | Default Value
  ---     | ---
  `string` | `'div'`

- __`onAllChecked`__ &middot; called when all children become checked (not fired on first render), no return

  Expects | Default Value
  ---     | ---
  `function` | `() => {}`

- __`onAllUnchecked`__ &middot; called when all children become unchecked (not fired on first render), no return

  Expects | Default Value
  ---     | ---
  `function` | `() => {}`

- __`onChildChecked`__ &middot; called when a specific child has become checked, returns the child definition

  Expects | Default Value
  ---     | ---
  `function` | `() => {}`

- __`onChildUnchecked`__ &middot; called when a specific child has become checked, returns the child definition

  Expects | Default Value
  ---     | ---
  `function` | `() => {}`

- __`selectAll`__ &middot; renders a master checkbox that can manipulate the values of all children simultaneously

  Expects | Default Value
  ---     | ---
  `CheckboxGroup.selectAll.BEFORE or CheckboxGroup.selectAll.AFTER or CheckboxGroup.selectAll.NONE` | `CheckboxGroup.selectAll.BEFORE`

- __`selectAllProps`__ &middot; must conform to the [Checkbox prop spec](./Checkbox)

  Expects | Default Value
  ---     | ---
  `object` | `{}`


## Reference Styles
### Stylus
You can see what variables are available to override in [variables.styl](https://github.com/enigma-io/boundless/blob/master/variables.styl).

```stylus
// Redefine any variables as desired, e.g:
color-accent = royalblue

// Bring in the component styles; they will be autoconfigured based on the above
@require "node_modules/boundless-checkbox-group/style"
```

### CSS
If desired, a precompiled plain CSS stylesheet is available for customization at `/build/style.css`, based on Boundless's [default variables](https://github.com/enigma-io/boundless/blob/master/variables.styl).