Skip to main content
Reakit
DocumentationNewsletter
GitHub
GitHub
Reakit is featured on Product Hunt!

Checkbox

Checkbox follows the WAI-ARIA Checkbox Pattern, which means you'll have a working dual or tri-state toggle button regardless of the type of the underlying element. By default, it renders the native <input type="checkbox">.

#Installation

npm install reakit

Learn more in Get started.

#Usage

It receives the same props as controlled inputs, such as checked and onChange:

import React from "react";
import { Checkbox } from "reakit/Checkbox";

function Example() {
  const [checked, setChecked] = React.useState(false);
  const toggle = () => setChecked(!checked);
  return <Checkbox checked={checked} onChange={toggle} />;
}

#useCheckboxState

For convenience, Reakit provides a useCheckboxState that already implements the state logic:

import { useCheckboxState, Checkbox } from "reakit/Checkbox";

function Example() {
  const checkbox = useCheckboxState({ state: true });
  return <Checkbox {...checkbox} />;
}

#indeterminate state

You can programmatically set checkbox value as indeterminate:

import React from "react";
import { Checkbox, useCheckboxState } from "reakit/Checkbox";

function useTreeState({ values }) {
  const group = useCheckboxState();
  const items = useCheckboxState();

  // updates items when group is toggled
  React.useEffect(() => {
    if (group.state === true) {
      items.setState(values);
    } else if (group.state === false) {
      items.setState([]);
    }
  }, [group.state]);

  // updates group when items is toggled
  React.useEffect(() => {
    if (items.state.length === values.length) {
      group.setState(true);
    } else if (items.state.length) {
      group.setState("indeterminate");
    } else {
      group.setState(false);
    }
  }, [items.state]);

  return { group, items };
}

function Example() {
  const values = ["Apple", "Orange", "Watermelon"];
  const { group, items } = useTreeState({ values });
  return (
    <ul>
      <li>
        <label>
          <Checkbox {...group} /> Fruits
        </label>
      </li>
      <ul>
        {values.map((value, i) => (
          <li key={i}>
            <label>
              <Checkbox {...items} value={value} /> {value}
            </label>
          </li>
        ))}
      </ul>
    </ul>
  );
}

#as prop

You can render the checkbox as any element. Reakit will add the props and interactions necessary for accessibility. You may need to add some styling though. You can use selectors like [aria-checked] for doing so.

import { useCheckboxState, Checkbox } from "reakit/Checkbox";

function Example() {
  const checkbox = useCheckboxState();
  return (
    <Checkbox {...checkbox} as="button">
      {checkbox.state ? "Checked" : "Unchecked"}
    </Checkbox>
  );
}

#Accessibility

  • Checkbox has role checkbox.
  • When checked, Checkbox has aria-checked set to true.
  • When not checked, Checkbox has aria-checked set to false.
  • When partially checked, Checkbox has aria-checked set to mixed.

Learn more in Accessibility.

#Composition

Learn more in Composition.

#Props

#useCheckboxState

  • state boolean | any[] | "indeterminate"

    Stores the state of the checkbox. If checkboxes that share this state have defined a value prop, it's going to be an array.

#Checkbox

  • disabled boolean | undefined

    Same as the HTML attribute.

  • focusable boolean | undefined

    When an element is disabled, it may still be focusable. It works similarly to readOnly on form elements. In this case, only aria-disabled will be set.

  • state boolean | any[] | "indeterminate"

    Stores the state of the checkbox. If checkboxes that share this state have defined a value prop, it's going to be an array.

  • setState (value: SetStateAction<boolean | any[] | "indet...

    Sets state.

  • value any

    Checkbox's value is going to be used when multiple checkboxes share the same state. Checking a checkbox with value will add it to the state array.

  • checked boolean | undefined

    Checkbox's checked state. If present, it's used instead of state.