Checkbox

When used by itself, the <Checkbox /> component is merely a toggle between checked and not checked. The checkbox will automatically render a visibly hidden <input type="checkbox"> to ensure events propagate correctly.

When using multiple checkboxes together, they allow the user to select any number of values from several options, including zero, one or multiple.

Show codeCopy code

• In a "create"-form (new data being entered), no checkboxes should be checked initially
• Prefer placing the checkboxes underneath each other to aid scannability
• List radios in a logical order, e.g:
  • Alphabetically
  • Numerically
  • Time-based
  • Most to least likely to be checked

The checkbox can be uncontrolled or controlled. Use the checked prop, along with onChange to take control of the state. When controlling checkboxes with useState, prefer using the functional updates syntax. In most cases, React recommends using controlled components to implement forms. If you are using a controlled input the checked value can't be undefined it must be a true|false otherwise React will display an error in the console alerting that the component was changed from uncontrolled to controlled.

Tip: Wrap your checkboxes with the CheckboxGroup component to manage the state more easily, and get the recommended layout out of the box.

Show codeCopy code

The checkbox also supports indeterminate state.

Show codeCopy code

Show codeCopy code

There are two checkbox sizes, small and medium (default).

Show codeCopy code

To customise or add more information to the checkbox label, you can pass in any other component via children.

Show codeCopy code

In rare cases when you need to create a custom checkbox, you can use the <CheckboxPrimitive /> component. Don't forget to use a <label> in conjunction, with a htmlFor="CHECKBOX_PRIMITIVE_ID_HERE" for accessibility.

Show codeCopy code

The <CheckboxGroup /> component is a styled context provider to help manage the state of a controlled group of checkboxes, using the React Context API. Each <Checkbox /> must have a unique value set.

It is recommended to wrap your checkbox group with a Fieldset, which lets you add a legend and will be read out as a "group" by some screen readers.

Show codeCopy code

Use the size prop to control the input size of the nested checkboxes of the checkbox group.

Show codeCopy code

In rare cases you can add the horizontal prop to make the radios in the checkbox group stack horizontally. However – it's recommended to use the default vertical layout for the best readability and experience.

Show codeCopy code

If you need validation on a checkbox group you can use the same validation props as Field; invalid and message.

Show codeCopy code

Just like the Field, extra vertical space is added under each checkbox group by default. This prevents layout shifts when a validation message is displayed. You can turn this extra space off by setting keepSpaceForMessage to false.