CheckboxGroup | Mineral UI

CheckboxGroup allows authors to construct a group of Checkboxes and provides a simpler API than working with Checkbox directly.

CheckboxGroup allows users to select multiple options from a list.

Examples #

Import Syntax #

import { CheckboxGroup } from 'mineral-ui/Checkbox';

Note

CheckboxGroups should be wrapped in a FormField to provide an accessible label and other features. Examples here omit labels for clarity and brevity.

Data vs. Children #

Use either the data prop or children to construct a group of related controls.

<DemoForm>
  <CheckboxGroup
    name="minerals-1"
    defaultChecked={['magnetite', 'quartz']}
    data={[
      { label: 'Fluorite', value: 'fluorite' },
      { label: 'Magnetite', value: 'magnetite' },
      { label: 'Quartz', value: 'quartz' }
    ]} />

  <FormFieldDivider />

  <CheckboxGroup name="minerals-2" defaultChecked={['hematite', 'pyrite']}>
    <Checkbox label="Azurite" value="azurite" />
    <Checkbox label="Hematite" value="hematite" />
    <Checkbox label="Pyrite" value="pyrite" />
  </CheckboxGroup>
</DemoForm>

Uncontrolled #

Create an uncontrolled CheckboxGroup by using the defaultChecked prop rather than the checked prop.

<DemoForm>
  <CheckboxGroup
    name="minerals"
    defaultChecked={['magnetite', 'quartz']}
    data={[
      { label: 'Fluorite', value: 'fluorite' },
      { label: 'Magnetite', value: 'magnetite' },
      { label: 'Quartz', value: 'quartz' }
    ]} />
</DemoForm>

Controlled #

Provide the checked prop and an onChange handler to create a controlled component.

() => {
  class MyForm extends Component {
    constructor(props) {
      super(props);

      this.state = {
        values: ['magnetite', 'quartz']
      };

      this.handleChange = this.handleChange.bind(this);
    }

    handleChange(event) {
      const { checked, value } = event.target;

      this.setState(prevState => {
        const values = [...prevState.values];
        const index = values.indexOf(value);
        const hasValue = index !== -1;

        if (checked && !hasValue) {
          values.push(value);
        } else if (hasValue) {
          values.splice(index, 1);
        }

        return { values };
      });
    }

    render() {
      return (
        <DemoForm>
          <CheckboxGroup
            name="minerals"
            onChange={this.handleChange}
            checked={this.state.values}
            data={[
              { label: 'Fluorite', value: 'fluorite' },
              { label: 'Magnetite', value: 'magnetite' },
              { label: 'Quartz', value: 'quartz' }
            ]} />
        </DemoForm>
      );
    }
  }

  return <MyForm />;
}

Inline #

Use the inline prop to display choices inline horizontally rather than stacked vertically.

<DemoForm>
  <CheckboxGroup
    inline
    name="minerals"
    defaultChecked={['magnetite', 'quartz']}
    data={[
      { label: 'Fluorite', value: 'fluorite' },
      { label: 'Magnetite', value: 'magnetite' },
      { label: 'Quartz', value: 'quartz' }
    ]} />
</DemoForm>

FormField #

Use a FormField to provide an accessible label and other features as well as a more streamlined API.

Note: The invalid and required props are not automatically forwarded to Checkboxes because doing so might not do what the author expects (marking all Checkboxes as invalid or required). These props can, however, be set using the data prop.

<DemoForm>
  <FormField
    input={CheckboxGroup}
    label="What are the primary characteristics of a mineral?"
    caption="Hint: All of the above"
    name="contact"
    variant="success"
    required
    data={[
      { label: 'Naturally occurring', value: 'natural' },
      { label: 'Inorganic', value: 'inorganic' },
      { label: 'Solid', value: 'solid' },
      { label: 'Definite chemical composition', value: 'composition' },
      { label: 'Crystalline structure', value: 'crystalline' }
    ]} />
</DemoForm>

API & Theme #

CheckboxGroup Props #

The CheckboxGroup component takes the following React props.

Name	Type	Default	Description
checked	Array<string>		Array of values of the selected Checkboxes; primarily for use with controlled components. If this prop is specified, an `onChange` handler must also be specified. See also: `defaultChecked`.
children	React$Node		Mineral Checkbox components
data			Data used to contruct Checkboxes, see example
defaultChecked	Array<string>		Array of values of the selected Checkboxes; primarily for use with uncontrolled components.
inline	boolean		Display the choices inline horizontally rather than stacked vertically.
name	string	required	The name of the group
onChange			Function called when a choice is selected
rootProps	Object		Props to be applied directly to the root element

Note

Unlike most other components, which apply undocumented properties to the root element, CheckboxGroup applies undocumented properties, including as and css, to the Checkbox component.

CheckboxGroup Theme Variables #

These variables can be used as hooks to override this component's style at either a local or global level. The theme referenced below is whatever theme is available from props to the instance of this component.

Variable	Value
CheckboxGroupControl_marginHorizontal_inline	theme.space_inline_xl
CheckboxGroupControl_marginVertical_stacked	theme.space_stack_md
CheckboxGroupControl_marginVertical_stackedJumbo	theme.space_stack_lg

Usage #

When/How to Use #

CheckboxGroup is used to provide a simpler API for creating a group of Checkboxes. It also provides proper row spacing and an inline layout option.

Use CheckboxGroup to allow users to select multiple options from a list.

CheckboxGroups should be wrapped in a FormField to provide an accessible label and other features. See the FormField example for details.

Best Practices #

Use when the number of choices is relatively small.

For simple boolean questions, use a single checkbox.

Don't use when the user should only select a single option. Use a Radio instead.