Checkbox

Boxes for checking and unchecking multiple values in forms

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 (
        <Checkbox isChecked={isChecked} onChange={setIsChecked}>
            Send me promotional emails
        </Checkbox>
    );
}

Multiple checkboxes

This an example of how to use many Checkbox components at once.

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

    return (
        <div>
            <Checkbox
                id="morning"
                isChecked={isMorningChecked}
                name="example-full"
                labelPadding="4px 0"
                onChange={setIsMorningChecked}
            >
                Morning
            </Checkbox>
            <Checkbox
                id="afternoon"
                isChecked={isAfternoonChecked}
                name="example-full"
                labelPadding="4px 0"
                onChange={setIsAfternoonChecked}
            >
                Afternoon
            </Checkbox>
            <Checkbox
                id="evening"
                isChecked={isEveningChecked}
                name="example-full"
                labelPadding="4px 0"
                onChange={setIsEveningChecked}
            >
                Evening
            </Checkbox>
        </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 (
        <Checkbox
            isIndeterminate={isChecked === undefined}
            isChecked={isChecked}
            onChange={setIsChecked}
        >
            Select all cities
        </Checkbox>
    );
}

Disabled checkboxes

The isDisabled prop visually and functionally disabled the radio button. It also visually disables the related label.

<React.Fragment>
    <Checkbox isDisabled isChecked onChange={() => {}} labelPadding="4px 0">
        Morning
    </Checkbox>
    <Checkbox isDisabled isChecked onChange={() => {}} labelPadding="4px 0">
        Afternoon
    </Checkbox>
    <Checkbox isDisabled onChange={() => {}} labelPadding="4px 0">
        Evening
    </Checkbox>
</React.Fragment>

Checkbox with an error

The hasError prop can be used to visually represent an error.

This prop only changes the checkbox’s color. It should be used alongside an error message that helps users advance through the form.

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

Multi-column content

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

This example puts the label content within children. It’s also possible to not provide children as undefined and use a custom label instead. In that case, you must use Checkbox’s id prop.

function CheckboxExample() {
    const [isChecked, setIsChecked] = React.useState(undefined);
    return (
        <Checkbox isChecked={isChecked} onChange={setIsChecked}>
            <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>
        </Checkbox>
    );
}

Checkbox input by default is vertically center-aligned with `children`. If `children` prop spans over multiple lines and you want it to align at the top, it is possible to provide `checkboxVerticalAlign` prop as `top`.

function CheckboxExample() {
    const [isChecked, setIsChecked] = React.useState(undefined);
    return (
        <Checkbox isChecked={isChecked} onChange={setIsChecked} checkboxVerticalAlign="top">
            <Text>
                Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum dapibus est nec
                eros congue, ac dapibus ipsum cursus. Quisque at odio viverra, consequat metus a,
                commodo ipsum. Donec sodales sapien in luctus sodales. Vivamus ornare mauris in arcu
                maximus placerat.
            </Text>
        </Checkbox>
    );
}

Using classes

These example use React Hooks, but if you want to use the old class-based components, you can do that.

class CheckboxExample extends React.Component {
    constructor(props) {
        super(props);
        this.state = {
            isChecked: undefined,
        };
        this.onChange = this.onChange.bind(this);
    }

    onChange(isChecked) {
        this.setState({ isChecked });
    }

    render() {
        return (
            <Checkbox isChecked={this.state.isChecked} onChange={this.onChange}>
                Send me promotional emails
            </Checkbox>
        );
    }
}

Props

Checkbox

onChange
required
Function that runs when a checkbox value changes. It receives the new boolean value, the provided id, and the underlying event as such: props.onChange(event.target.checked, props.id, event).

Type
( value: boolean, id: string | undefined, event: React.ChangeEvent<HTMLInputElement>, ) => void
isDisabled
Disables the input and the label.

Type
boolean
Default
false
isChecked
Determines if the checkbox is checked.

Type
boolean
Default
false
hasError
Makes the radio and text color red.

Type
boolean
Default
false
children
Text or elements that appear within the label. If children is not provided, the developer must use the Radio's id prop to associate it with a custom <label> element.

Type
React.ReactNode
id
The id is added to the checkbox 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
labelPadding
Determine that padding that gets applied to the label. This can be used to increase the label's click target. The value supplied should be a string with a unit such as 8px or 8px 16px.

Type
string
Default
'14px 0'
onKeyDown
Function that is called when the user presses a key while focused on the Checkbox.

Type
(event: React.KeyboardEvent<HTMLInputElement>) => void
Default
(): void => {}
isIndeterminate
Shows a horizontal line to represent an indeterminate input.

Type
boolean
Default
false
dataTestId
A selector hook into the React component for use in automated testing environments. It is applied internally to the <input /> element.

Type
string
dataTest
deprecated
A selector hook into the React component for use in automated testing environments. It is applied internally to the <input /> element.

Note:
Deprecated in favor of the dataTestId prop

Type
string
checkboxVerticalAlign
Determines how the checkbox input will be vertically aligned relative to props.children.

Type
'top' | 'center'
Default
'center'
value
Determines the value that will be submitted if the checkbox is checked. The default value is 'on'.

Type
string | string[] | number