Components

Checkbox

Checkbox is an interactive control that can be turned on or off. Checkboxes are often used in groups, wherein multiple options may be selected.

Examples #

Import Syntax #

import Checkbox from 'mineral-ui/Checkbox';

Note

Mineral UI also provides a CheckboxGroup, which offers a simpler API for working with a group of Checkboxes, and a FormField to provide an accessible label and other features. Examples here omit CheckboxGroup and FormFields for clarity and brevity.

Uncontrolled #

Uncontrolled Checkboxes behave just like their HTML input counterparts wherein the checked state is handled by the DOM. The only difference is that defaultChecked must be used to set the initial state rather than checked.

<DemoForm>
  <Checkbox name="minerals" label="Quartz" value="quartz" defaultChecked />
  <Checkbox name="minerals" label="Magnetite" value="magnetite" />
</DemoForm>

Controlled #

In a controlled Checkbox, the checked state is handled by a React component. Set the checked state with the checked prop and provide an onChange handler.

() => {
  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>
          <Checkbox
            name="minerals"
            label="Fluorite"
            value="fluorite"
            checked={this.state.values.indexOf('fluorite') !== -1}
            onChange={this.handleChange} />
          <Checkbox
            name="minerals"
            label="Quartz"
            value="quartz"
            checked={this.state.values.indexOf('quartz') !== -1}
            onChange={this.handleChange} />
          <Checkbox
            name="minerals"
            label="Magnetite"
            value="magnetite"
            checked={this.state.values.indexOf('magnetite') !== -1}
            onChange={this.handleChange} />
        </DemoForm>
      );
    }
  }

  return <MyForm />;
}

Indeterminate #

Checkbox supports an indeterminate or partially-checked state.

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

      this.state = {
        indeterminate: true
      };

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

    handleChange(event) {
      this.setState((prevState) => ({
        indeterminate: !prevState.indeterminate
      }));
    }

    render() {
      return (
        <DemoForm>
          <Checkbox
            name="indeterminate"
            label="Indeterminate"
            value="indeterminate"
            indeterminate={this.state.indeterminate}
            onChange={this.handleChange} />
        </DemoForm>
      );
    }
  }

  return <MyForm />;
}

Disabled #

Use the disabled prop to indicate that the Checkbox is not available for interaction.

<DemoForm>
  <Checkbox label="Quartz" value="quartz" disabled />
  <Checkbox label="Magnetite" value="magnetite" defaultChecked disabled />
</DemoForm>

Required #

The required prop on a Checkbox does nothing visually on its own, but is important for accessibility.

<DemoForm>
  <Checkbox name="minerals" label="Quartz" value="quartz" required defaultChecked />
  <Checkbox name="minerals" label="Magnetite" value="magnetite" required />
</DemoForm>

Invalid #

The invalid prop on a Checkbox does nothing visually on its own, but is important for accessibility.

<DemoForm>
  <Checkbox name="minerals" label="Quartz" value="quartz" defaultChecked invalid />
  <Checkbox name="minerals" label="Magnetite" value="magnetite" invalid />
</DemoForm>

Sizes #

Checkbox is available in a few sizes.

<DemoForm>
  <Checkbox name="size" label="Small" value="small" size="small" />
  <Checkbox name="size" label="Medium" value="medium" size="medium" />
  <Checkbox name="size" label="Large" value="large" defaultChecked />
  <Checkbox name="size" label="Jumbo" value="jumbo" size="jumbo" />
</DemoForm>

Label Position & Justification #

Use the labelPosition prop to adjust the position of the control relative to the label. Use the justify prop to maximize the space between the label and the control. These props are often useful when used in tandem with one another.

<DemoForm>
  <Checkbox name="minerals" label="Quartz" value="quartz" />
  <FormFieldDivider />
  <Checkbox name="minerals" label="Magnetite" value="magnetite" labelPosition="start" />
  <FormFieldDivider />
  <Checkbox name="minerals" label="Azurite" value="azurite" justify />
  <FormFieldDivider />
  <Checkbox name="minerals" label="Hematite" value="hematite" labelPosition="start" justify />
</DemoForm>

Label Wrapping #

This example demonstrates how the text of a long label will wrap in relation to the position of the control.

<DemoForm>
  <Checkbox name="example" label={loremIpsum} defaultChecked />
</DemoForm>

Visually Hidden Label #

If the purpose of a Checkbox is obvious from context and adding a label would negatively affect the design, you can use hideLabel to visually hide the label while retaining accessibility.

<DemoForm>
  <Checkbox label="Select All" hideLabel />
</DemoForm>

Input ref #

The following example demonstrates how to get a reference to the underlying input element.

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

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

    focus() {
      this.input.focus();
    }

    render() {
      return (
        <DemoLayout>
          <Checkbox
            label="Option 1"
            value="1"
            inputRef={ref => { this.input = ref; }} />
          <Button onClick={ this.focus }>Focus the input</Button>
        </DemoLayout>
      )
    }
  }

  return <MyForm />;
}

Bidirectionality #

Checkboxes support right-to-left (RTL) languages.

<div dir="rtl">
  <ThemeProvider theme={{ direction: 'rtl' }}>
    <DemoForm>
      <Checkbox name="example" label="مرحبا بالعالم"  />
      <Checkbox name="example" label="مرحبا بالعالم"  labelPosition="start" />
      <FormFieldDivider />
      <Checkbox name="example" label="مرحبا بالعالم"  justify />
      <Checkbox name="example" label="مرحبا بالعالم"  labelPosition="start" justify />
    </DemoForm>
  </ThemeProvider>
</div>

API & Theme #

Checkbox Props #

The Checkbox component takes the following React props.

NameTypeDefaultDescription
checkedboolean

Checked state of the checkbox. Primarily for use with controlled components. If this prop is specified, an onChange handler must also be specified. See also: defaultChecked.

defaultCheckedboolean

Initial checked state of the checkbox; primarily for use with uncontrolled components

defaultIndeterminateboolean

Initial indeterminate state of the checkbox; primarily for use with uncontrolled components

disabledboolean

Disables the checkbox

hideLabelboolean

Visually hide label, but keep available for assistive technologies

indeterminateboolean

Partially checked state. Primarily for use with controlled components. If this prop is specified, an onChange handler must also be specified. See also: defaultIndeterminate.

inputRef

Ref for the checkbox

invalidboolean

Indicates that the value of the input is invalid

justifyboolean

Maximize the distance between the label and the control

labelstring | React$Element<*>required

Label associated with the input element

labelPosition'start' | 'end''end'

Determines the position of the label relative to the control

namestring

Used to uniquely define a group of checkboxes

onChange

Function called when a checkbox is selected

requiredboolean

Indicates that the user must select an option before submitting a form

rootPropsObject

Props to be applied directly to the root element rather than the input

size'small' | 'medium' | 'large' | 'jumbo''large'

Available sizes

valuestring

The value of the checkbox

Note

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

Checkbox 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.

VariableValue
CheckboxControl_backgroundColortheme.input_backgroundColor
CheckboxControl_backgroundColor_checkedtheme.borderColor_theme
CheckboxControl_backgroundColor_checkedHovertheme.borderColor_theme_hover
CheckboxControl_borderColortheme.borderColor
CheckboxControl_borderColor_hovertheme.borderColor_theme_hover
CheckboxControl_borderColor_checkedtheme.borderColor_theme
CheckboxControl_borderColor_checkedHovertheme.borderColor_theme_hover
CheckboxControl_borderRadiustheme.borderRadius_1
CheckboxControl_boxShadow_focus0 0 0 1px boxShadow_focusInner, 0 0 0 2px borderColor_theme_focus
CheckboxControl_size1em
CheckboxControl_size_jumbo1.5em
CheckboxText_colortheme.color
CheckboxText_fontSizetheme.fontSize_ui
CheckboxText_fontSize_small0.75em
CheckboxText_marginHorizontaltheme.space_inline_md

Usage #

When/How to Use #

Use Checkboxes to change settings rather than initiate actions.

Checkboxes are often created in groups.

Best Practices #

Begin labels with a capital letter.

Don't use punctuation at the end of each line if the label is a single sentence, word, or fragment.