Components

Checkbox

Boxes for checking and unchecking multiple values in forms

Version

Basic checkbox

Checkboxes can be checked, unchecked, or in an indeterminate state.

The isChecked prop determines if a checkbox is checked.

function CheckboxExample() {
    const [isChecked, setIsChecked] = React.useState(undefined);
    return (
        <CheckboxV2 isChecked={isChecked} onChange={setIsChecked}>
            Send me promotional emails
        </CheckboxV2>
    );
}

Multiple checkboxes

Checkboxes are block-level and include built-in vertical spacing, so consecutive checkboxes stack with the Figma “Checkbox / List” 8px rhythm without any extra wrapper.

function CheckboxExample() {
    const [isMorningChecked, setIsMorningChecked] = React.useState(true);
    const [isAfternoonChecked, setIsAfternoonChecked] = React.useState(true);
    const [isEveningChecked, setIsEveningChecked] = React.useState(true);

    return (
        <div>
            <CheckboxV2
                id="morning"
                isChecked={isMorningChecked}
                name="example-full"
                onChange={setIsMorningChecked}
            >
                Morning
            </CheckboxV2>
            <CheckboxV2
                id="afternoon"
                isChecked={isAfternoonChecked}
                name="example-full"
                onChange={setIsAfternoonChecked}
            >
                Afternoon
            </CheckboxV2>
            <CheckboxV2
                id="evening"
                isChecked={isEveningChecked}
                name="example-full"
                onChange={setIsEveningChecked}
            >
                Evening
            </CheckboxV2>
        </div>
    );
}

Indeterminate checkboxes

Indeterminate checkboxes are used when not all items in a field are selected.

function CheckboxExample() {
    const [isChecked, setIsChecked] = React.useState(undefined);
    return (
        <CheckboxV2
            isIndeterminate={isChecked === undefined}
            isChecked={isChecked}
            onChange={setIsChecked}
        >
            Select all cities
        </CheckboxV2>
    );
}

Disabled checkboxes

The isDisabled prop visually and functionally disables the checkbox. It also visually disables the related label.

<React.Fragment>
    <CheckboxV2 isDisabled isChecked onChange={() => {}}>
        Morning
    </CheckboxV2>
    <CheckboxV2 isDisabled isChecked onChange={() => {}}>
        Afternoon
    </CheckboxV2>
    <CheckboxV2 isDisabled onChange={() => {}}>
        Evening
    </CheckboxV2>
</React.Fragment>

Checkbox with an error

The hasError prop can be used to visually represent an error. It should be used alongside an error message that helps users advance through the form.

function CheckboxExample() {
    const [isChecked, setIsChecked] = React.useState(undefined);
    return (
        <CheckboxV2 isChecked={isChecked} hasError onChange={setIsChecked}>
            I accept the Terms of Service
        </CheckboxV2>
    );
}

Display type

standard (the default) renders the inline, borderless layout that covers existing v1 use cases. control wraps the checkbox and label in a padded, bordered card; its border becomes brand-colored when the checkbox is selected or indeterminate.

function CheckboxExample() {
    const [isChecked, setIsChecked] = React.useState(undefined);
    return (
        <CheckboxV2 type="control" isChecked={isChecked} onChange={setIsChecked}>
            Send me promotional emails
        </CheckboxV2>
    );
}

Custom label padding

The labelPadding prop expands the click/touch target by applying a CSS padding string to the label, mirroring the v1 prop. It is most useful with the control type, since it overrides the bordered card’s padding.

function CheckboxExample() {
    const [isChecked, setIsChecked] = React.useState(undefined);
    return (
        <CheckboxV2 labelPadding="16px 8px" isChecked={isChecked} onChange={setIsChecked}>
            Send me promotional emails
        </CheckboxV2>
    );
}

Checkbox with a description

The description prop renders secondary text beneath the label, and the label is emphasized. The checkbox still follows checkboxVerticalAlign (use checkboxVerticalAlign="top" to align it with the first line).

function CheckboxExample() {
    const [isChecked, setIsChecked] = React.useState(undefined);
    return (
        <CheckboxV2
            isChecked={isChecked}
            onChange={setIsChecked}
            description="We send at most one email per week."
        >
            Send me promotional emails
        </CheckboxV2>
    );
}

Multi-column content

It’s possible to provide complex UIs to the children prop. Clicking on the content will select the related checkbox.

function CheckboxExample() {
    const [isChecked, setIsChecked] = React.useState(undefined);
    return (
        <CheckboxV2 isChecked={isChecked} onChange={setIsChecked} checkboxVerticalAlign="top">
            <div className="flex">
                <div className="flex-none">
                    <UserAvatar imageUrl="https://randomuser.me/api/portraits/women/63.jpg" />
                </div>
                <div className="pl4 flex items-center" style={{ flex: '1 0 0%' }}>
                    <div>
                        <span className="b">Austin Entertainment LLC.</span>
                        <p>DJs, photo booths, and photography for all of your event needs.</p>
                    </div>
                    <div className="b ml-auto">$120/hr</div>
                </div>
            </div>
        </CheckboxV2>
    );
}

Props

CheckboxV2

isDisabled
Disables the input and the label.

Type
boolean
Default
false
isChecked
Determines if the checkbox is checked. Maps to React Aria's isSelected.

Type
boolean
Default
false
hasError
Renders the checkbox in an error state. Maps to React Aria's isInvalid and styles via the [data-invalid] attribute.

Type
boolean
Default
false
children
Text or elements that appear within the label. If children is not provided, the developer must use the accessibilityLabel prop to label the checkbox for assistive technologies.

Type
React.ReactNode
description
Secondary text rendered beneath the label. When provided, the label is emphasized. The checkbox alignment continues to follow checkboxVerticalAlign (use 'top' for the Figma "standard with description" treatment). Maps to the [data-has-description] attribute.

Type
string
id
The id is added to the underlying checkbox input as an HTML attribute and passed to the onChange function.

Type
string
isRequired
Adds the required HTML attribute.

Type
boolean
Default
false
name
Checkboxes on a page with the same name will be grouped together when sent to the server. The browser will only send the value of checkboxes that are checked.

Type
string
onChange
Function that runs when a checkbox value changes. It preserves the v1 signature and receives the new boolean value, the provided id, and the underlying native change event: props.onChange(isChecked, props.id, event).

React Aria's own onChange only surfaces the boolean, so the native event is recovered from the underlying input element and may be undefined in environments where it cannot be captured.

Type
(value: boolean, id: string | undefined, event?: Event) => void
onKeyDown
Function that is called when the user presses a key while focused on the Checkbox. Maps to React Aria's onKeyDown.

Type
AriaCheckboxProps['onKeyDown']
isIndeterminate
Shows a horizontal line to represent an indeterminate input. The indeterminate visual representation remains regardless of user interaction.

Type
boolean
Default
false
dataTestId
A selector hook into the React component for use in automated testing environments.

Type
string
checkboxVerticalAlign
Determines how the checkbox input will be vertically aligned relative to props.children. Maps to the [data-align] attribute.

Type
'top' | 'center'
Default
'center'
type
Display type. 'standard' renders the inline, borderless layout (the default, covering existing v1 use cases). 'control' wraps the checkbox and label in a bordered, padded card whose border turns brand-colored when selected or indeterminate and is muted when disabled. Maps to the [data-type] attribute.

Type
'standard' | 'control'
Default
'standard'
labelPadding
Padding applied to the label container, primarily to expand the click/touch target. Accepts a CSS padding string such as 8px or 8px 16px, mirroring the v1 labelPadding prop. When omitted, the component uses the standardized Thumbprint v2 spacing. Most useful with the 'control' type, since it overrides the bordered card's padding.

Type
string
value
Determines the value that will be submitted if the checkbox is checked. The default value is 'on'.

Type
string
accessibilityLabel
Accessible label for the checkbox input. Only needed if non-textual children are provided (e.g., images, emojis). Maps to React Aria's aria-label.

Type
string