CheckboxControl Edit

Checkboxes allow the user to select one or more items from a set.

Selected and unselected checkboxes

Table of contents Table of contents

  1. Design guidelines
  2. Development guidelines
  3. Related components

Top ↑

Design guidelines Design guidelines

Usage Usage

When to use checkboxes When to use checkboxes

Use checkboxes when you want users to:

  • Select one or multiple items from a list.
  • Open a list containing sub-selections.

Do
Use checkboxes when users can select multiple items from a list. They let users select more than one item.

Don’t
Don’t use toggles when a list consists of multiple options. Use checkboxes — they take up less space.

Checkboxes can be used to open a list containing sub-selections.

Top ↑

Parent and child checkboxes Parent and child checkboxes

Checkboxes can have a parent-child relationship, with secondary options nested under primary options.

When the parent checkbox is checked, all the child checkboxes are checked. When a parent checkbox is unchecked, all the child checkboxes are unchecked.

If only a few child checkboxes are checked, the parent checkbox becomes a mixed checkbox.

Top ↑

Development guidelines Development guidelines

Top ↑

Usage Usage

Render an is author checkbox:

import { CheckboxControl } from '@wordpress/components';
import { withState } from '@wordpress/compose';

const MyCheckboxControl = withState( {
    isChecked: true,
} )( ( { isChecked, setState } ) => (
    <CheckboxControl
        heading="User"
        label="Is author"
        help="Is the user a author or not?"
        checked={ isChecked }
        onChange={ ( isChecked ) => { setState( { isChecked } ) } }
    />
) );

Top ↑

Props Props

The set of props accepted by the component will be specified below.
Props not included in this set will be applied to the input element.

Top ↑

heading heading

A heading for the input field, that appears above the checkbox. If the prop is not passed no heading will be rendered.

  • Type: String
  • Required: No

Top ↑

label label

A label for the input field, that appears at the side of the checkbox.
The prop will be rendered as content a label element.
If no prop is passed an empty label is rendered.

  • Type: String
  • Required: No

Top ↑

help help

If this property is added, a help text will be generated using help property as the content.

  • Type: String|WPElement
  • Required: No

Top ↑

checked checked

If checked is true the checkbox will be checked. If checked is false the checkbox will be unchecked.
If no value is passed the checkbox will be unchecked.

  • Type: Boolean
  • Required: No

Top ↑

onChange onChange

A function that receives the checked state (boolean) as input.

  • Type: function
  • Required: Yes

Top ↑

  • To select one option from a set, and you want to show all the available options at once, use the RadioControl component.
  • To toggle a single setting on or off, use the FormToggle component.