Checkbox

Checkboxes give users binary choices when presented with multiple options in a series.

Introduction

Checkboxes provide users with a graphical representation of a binary choice (yes or no, on or off). They are most commonly presented in a series, giving the user multiple choices to make.

The Joy UI Checkbox component replaces the native HTML <input type="checkbox"> element and offers expanded options for styling and accessibility.

Basics

import Checkbox from '@mui/joy/Checkbox';

The basic Checkbox component is a single input set to the unchecked state. Use the label prop to provide text, and add defaultChecked when the input should be checked by default.

Customization

Variants

The Checkbox component supports Joy UI's four global variants: solid, soft, outlined, and plain. By default, when unchecked, the Checkbox is set to outlined; when checked, the variant changes to solid.

Adding the variant prop to your Checkbox overrides this default behavior. Try checking and unchecking the Checkboxes in the demo below to see the differences:

Sizes

The Checkbox component comes in three sizes: sm, md (default), and lg.

Colors

Every palette included in the theme is available via the color prop.

Icons

By default, the Checkbox component is empty when unchecked. Use the uncheckedIcon prop to add a custom icon for the unchecked state. You can also use checkedIcon to customize the checked state.

Appear on hover

You can use the uncheckedIcon as a "preview" of the checked state by making it appear when the user hovers over the empty Checkbox.

The demo below shows how to target the icon by using the svg selector and apply opacity for a smooth effect:

No icons

Use the disableIcon prop to remove the icon entirely. In this case, the state of the Checkbox is communicated through the type of variant applied to the label. Try clicking on the Checkbox labels in the demo below to see how this works:

Focus outline

By default, the focus outline wraps both the Checkbox input and its label. To set the focus outline so that it only wraps the input, target the checkboxClasses.checkbox class and add position: 'relative', as shown in the demo below:

Clickable container

Use the overlay prop to shift the focus outline from the Checkbox to its container, making the entire container clickable to toggle the state of the Checkbox. This works with any wrapper element with positioning—the demo below uses Sheet (by default, it has relative position):

Indeterminate

The default Checkbox is dual-state: the user can toggle between checked and unchecked.

There is also the option for a tri-state or indeterminate Checkbox that supports a state known as "partially checked."

This indeterminate state is often used to communicate the fact that only some out of a set of Checkboxes are checked. As such, it's usually reserved for parent Checkboxes that can control the states of their children.

The demo below shows how to implement the indeterminate prop on a parent Checkbox that watches for the checked state in its children. If only one child is checked, then the parent displays the indeterminate state. Clicking on the parent Checkbox toggles selecting and deselecting all children.

Helper text

import FormControl from '@mui/joy/FormControl';
import FormHelperText from '@mui/joy/FormHelperText';

Use the Form Control and Form Helper Text components add a description to the Checkbox. The Checkbox will be linked to the helper text via the aria-describedby attribute.

Group

To group multiple Checkboxes, wrap them in a container component like Box with role="group".

Combine with the List component to ensure consistent spacing and enable screen readers to interpret the Checkbox group as a list. Learn more about accessible design patterns for checkboxes in the W3C documentation.

Common examples

Sign-up checkbox

To use an interactive element together with a Checkbox, you can wrap it with a FormControl and FormHelperText.

Filtering status

This example uses variants and colors available to the List Item and Checkbox components to communicate state changes.

Filtering members

This example uses the CSS flexDirection: 'rowReverse' property to position the label and icon. Don't forget to use the label prop to ensure proper Checkbox accessibility.

Choice chips

You can use Checkbox to recreate a kind of Chip component, which is commonly implemented in the form of a group of filtering options.

Viewport checklist

Anatomy

The Checkbox component is composed of a root <span> that wraps the input and <label> (if present). Note that the actual <input type="checkbox"> is doubly nested within <span> elements that represent the checkbox and action slots, respectively.

<span class="MuiCheckbox-root">
  <span class="MuiCheckbox-checkbox">
    <span class="MuiCheckbox-action">
      <input type="checkbox" class="MuiCheckbox-input" value />
    </span>
  </span>
  <label class="MuiCheckbox-label">
    <!-- label text -->
  </label>
</span>

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

• <Checkbox />