Skip to main content

Checkbox

Checkbox in Storybook
Note: There are deprecated versions of this component. Switch to a version of the docs older than 10.0.x to view their docs.

Examples​

Check out the Usage section for details about how and when to use the Checkbox and CheckboxGroup components.

Basic checkbox​

The Checkbox component can be used alone, outside of the CheckboxGroup context.

<Checkbox label="This is a single checkbox" />

Basic checkboxes in checkbox group​

The CheckboxGroup component acts as container for a set of Checkbox elements. You can choose to display or hide the label, but it is mandatory for the component's accessibility.

<CheckboxGroup label="This is a group">
  <Checkbox label="option 1" />
  <Checkbox label="option 2" />
</CheckboxGroup>

Group without label​

You can hide the CheckboxGroup label by setting the hideLabel property to true. This does not affect any of the other behaviors of the CheckboxGroup element.

<CheckboxGroup
  label="This is only for aria-label"
  hideLabel={true}>
  <Checkbox label="option 1" />
  <Checkbox label="option 2" />
</CheckboxGroup>

Horizontal group​

CheckboxGroup allows the display of options in horizontal distribution by setting the horizontal property to true.

<CheckboxGroup
  label="This is an horizontal group"
  horizontal={true}>
  <Checkbox label="option 1" />
  <Checkbox label="option 2" />
</CheckboxGroup>

Checkbox and CheckboxGroup messages​

Both components allow developers to show error messages. When set at the CheckboxGroup level, errors are displayed below all options. However, when set at the Checkbox level inside a CheckboxGroup, the message is ignored and has no effect.

  export function CheckboxMessages() {
    const [validationMessages, setValidationMessages] = useState({});
    const [groupValidationMessages, setGroupValidationMessages] = useState({});

    const onChange = useCallback((e, newChecked) => {
      setValidationMessages({});
      setGroupValidationMessages({});

      if (newChecked) {
        setValidationMessages({ error: ['This is ignored'] });
        setGroupValidationMessages({ error: ['Only second checkbox can be marked'] });
      }
    }, []);

    return (
      <CheckboxGroup
        label="Do not select the forbidden option"
        stateMessages={groupValidationMessages}
      >
        <Checkbox
          label="Forbidden option"
          onChange={onChange}
          stateMessages={validationMessages}
        />
        <Checkbox label="You can select this one" />
      </CheckboxGroup>
    );
  }
}

Indeterminate state​

Although this is not implemented as part of the Checkbox component, the native behavior of an HTML input element is available. In this case, the indeterminate state can be set programmatically through JavaScript. A checkbox in the indeterminate state has a horizontal line in the box, instead of a check or tick. In the example below, the style is modified to make the option visible.

export function SetIndeterminateState() {
  const onChange = useCallback((e, newCheck) => {
    (document.getElementById('checkbox2') as HTMLInputElement).indeterminate =
      newCheck;
  }, []);

  const style = { opacity: 100 };

  return (
    <CheckboxGroup label="Group of checkboxes">
      <Checkbox
        label="Set the next checkbox as 'indeterminate'"
        onChange={onChange}
      />
      <Checkbox
        label="This is another checkbox"
        id="checkbox2"
        checked={false}
        style={style}
      />
    </CheckboxGroup>
  );
}