Automattic Design System

Components

CheckboxControl

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

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

View on Storybook

View in Figma

View source on GitHub

PropsPermalink to this section

NameDefaultDescription
help

ReactNode

Additional description for the control.

Only use for meaningful description or instructions for the control. An element containing the description will be programmatically associated to the BaseControl by the means of an aria-describedby attribute.

__nextHasNoMarginBottom

boolean

Start opting into the new margin-free styles that will become the default in a future version.

disabled

boolean

Whether the checkbox should be disabled.

onChange Required

(value: boolean) => void

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

label

string

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.

checked

boolean

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.

indeterminate

boolean

If indeterminate is true the state of the checkbox will be indeterminate.

heading

ReactNode

ExamplesPermalink to this section

DefaultPermalink to this section

const Default = () => <ControlledCheckboxControl label="Is author" help="Is the user an author or not?" />;

IndeterminatePermalink to this section

const Indeterminate = () => {
    const [ fruits, setFruits ] = useState( {
        apple: false,
        orange: false,
    } );

    const isAllChecked = Object.values( fruits ).every( Boolean );
    const isIndeterminate =
        Object.values( fruits ).some( Boolean ) && ! isAllChecked;

    return (
        <VStack>
            <CheckboxControl
                label="Select all"
                checked={ isAllChecked }
                indeterminate={ isIndeterminate }
                onChange={ ( v ) => {
                    setFruits( {
                        apple: v,
                        orange: v,
                    } );
                    onChange( v );
                } } />
            <CheckboxControl
                label="Apple"
                checked={ fruits.apple }
                onChange={ ( apple ) =>
                    setFruits( ( prevState ) => ( {
                        ...prevState,
                        apple,
                    } ) )
                } />
            <CheckboxControl
                label="Orange"
                checked={ fruits.orange }
                onChange={ ( orange ) =>
                    setFruits( ( prevState ) => ( {
                        ...prevState,
                        orange,
                    } ) )
                } />
        </VStack>
    );
};

With Custom LabelPermalink to this section

For more complex designs, a custom <label> element can be associated with the checkbox by leaving the label prop undefined and using the id and htmlFor props instead. Because the label element also functions as a click target for the checkbox, do not place interactive elements such as links or buttons inside the <label> node.

Similarly, a custom description can be added by omitting the help prop and using the aria-describedby prop instead.

const WithCustomLabel = () => {
    const [ isChecked, setChecked ] = useState( true );

    return (
        <HStack justify="flex-start" alignment="top" spacing={ 0 }>
            <CheckboxControl
                checked={ isChecked }
                onChange={ ( v ) => {
                    setChecked( v );
                    onChange( v );
                } }
                id="my-checkbox-with-custom-label"
                aria-describedby="my-custom-description" />
            <VStack>
                <label htmlFor="my-checkbox-with-custom-label">My custom label
                                        </label>
                <div id="my-custom-description" style={ { fontSize: 13 } }>A custom description.
                                        </div>
            </VStack>
        </HStack>
    );
};

With VisualPermalink to this section

When adding a visual aid, prefer placing it at the trailing end of the row, rather than placing it directly before the label, or moving the checkbox to the trailing end.

const WithVisual = () => <Stack gap="md" align="flex-start" justify="space-between">
    <Stack>
        <ControlledCheckboxControl
            help="Additional context that helps users understand what this setting does and when they might want to turn it on or off." />
    </Stack>
    <Stack
        align="center"
        justify="center"
        style={ {
            backgroundColor:
                'var(--wpds-color-background-surface-neutral-weak)',
            borderRadius: 'var(--wpds-border-radius-md)',
            flexShrink: 0,
            height: 'var(--wpds-dimension-size-lg)',
            width: 'var(--wpds-dimension-size-lg)',
        } }>
        <Icon icon={ wordpress } />
    </Stack>
</Stack>;