Checkbox

A Checkbox should be used for On/Off or Yes/No questions. Each checkbox should indicate a separate decision and can be organized into groups of similar options.

<Form>
    <Form.Group grouped>
        <label>Attributes</label>
        <Form.Checkbox label="Force User" />
        <Form.Checkbox label="Pilot" />
        <Form.Checkbox label="Bounty Hunter" />
    </Form.Group>

    <Form.Group grouped>
        <label>Subscribe</label>
        <Form.Checkbox label="Subscribe to updates" />
    </Form.Group>

</Form>

<Form>
    <Form.Group grouped>
        <label>Attributes</label>
        <Form.Checkbox label="Force User" />
        <Form.Checkbox label="Pilot" />
        <Form.Checkbox label="Bounty Hunter" />
    </Form.Group>

    <Form.Group grouped>
        <label>Subscribe</label>
        <Form.Checkbox label="Subscribe to updates" />
    </Form.Group>

</Form>

<Form>
    <State initial={0}>
        {([attributes, setAttributes]) => (
            <Form.Group grouped>
                <label>Attributes</label>
                <Form.Radio
                    label="Force User"
                    checked={attributes === 1}
                    onChange={() => setAttributes(1)}
                />
                <Form.Radio
                    label="Pilot"
                    checked={attributes === 2}
                    onChange={() => setAttributes(2)}
                />
                <Form.Radio
                    label="Bounty Hunter"
                    checked={attributes === 3}
                    onChange={() => setAttributes(3)}
                />
            </Form.Group>
        )}
    </State>
    <State initial={0}>
        {([subscribe, setSubscribe]) => (
            <Form.Group grouped>
                <label>Subscribe to updates</label>
                <Form.Radio
                    label="No"
                    checked={subscribe === 1}
                    onChange={() => setSubscribe(1)}
                />
                <Form.Radio
                    label="Yes"
                    checked={subscribe === 2}
                    onChange={() => setSubscribe(2)}
                />
            </Form.Group>
        )}
    </State>
</Form>

<Form>
    <State initial={0}>
        {([attributes, setAttributes]) => (
            <Form.Group grouped>
                <label>Attributes</label>
                <Form.Radio
                    label="Force User"
                    checked={attributes === 1}
                    onChange={() => setAttributes(1)}
                />
                <Form.Radio
                    label="Pilot"
                    checked={attributes === 2}
                    onChange={() => setAttributes(2)}
                />
                <Form.Radio
                    label="Bounty Hunter"
                    checked={attributes === 3}
                    onChange={() => setAttributes(3)}
                />
            </Form.Group>
        )}
    </State>
    <State initial={0}>
        {([subscribe, setSubscribe]) => (
            <Form.Group grouped>
                <label>Subscribe to updates</label>
                <Form.Radio
                    label="No"
                    checked={subscribe === 1}
                    onChange={() => setSubscribe(1)}
                />
                <Form.Radio
                    label="Yes"
                    checked={subscribe === 2}
                    onChange={() => setSubscribe(2)}
                />
            </Form.Group>
        )}
    </State>
</Form>

Sizing

Checkboxes can be sized to be small, medium, and large. Small checkboxes are useful in small areas, and large checkboxes when a lot of whitespace is present.

<Form className="d-f">
    <Form.Group grouped className="flex-grow-1">
        <label>Small</label>
        <Form.Checkbox size="small" label="Force User" />
        <Form.Checkbox size="small" label="Pilot" />
        <Form.Checkbox size="small" label="Bounty Hunter" />
    </Form.Group>
    <Form.Group grouped className="flex-grow-1">
        <label>Medium (default)</label>
        <Form.Checkbox label="Force User" />
        <Form.Checkbox label="Pilot" />
        <Form.Checkbox label="Bounty Hunter" />
    </Form.Group>
    <Form.Group grouped className="flex-grow-1">
        <label>Large</label>
        <Form.Checkbox size="large" label="Force User" />
        <Form.Checkbox size="large" label="Pilot" />
        <Form.Checkbox size="large" label="Bounty Hunter" />
    </Form.Group>
</Form>

<Form className="d-f">
    <Form.Group grouped className="flex-grow-1">
        <label>Small</label>
        <Form.Checkbox size="small" label="Force User" />
        <Form.Checkbox size="small" label="Pilot" />
        <Form.Checkbox size="small" label="Bounty Hunter" />
    </Form.Group>
    <Form.Group grouped className="flex-grow-1">
        <label>Medium (default)</label>
        <Form.Checkbox label="Force User" />
        <Form.Checkbox label="Pilot" />
        <Form.Checkbox label="Bounty Hunter" />
    </Form.Group>
    <Form.Group grouped className="flex-grow-1">
        <label>Large</label>
        <Form.Checkbox size="large" label="Force User" />
        <Form.Checkbox size="large" label="Pilot" />
        <Form.Checkbox size="large" label="Bounty Hunter" />
    </Form.Group>
</Form>

States

Checkboxes can be in an error state and a disabled state.

<Form>
    <Form.Group grouped>
        <label>Disabled States</label>
        <Form.Checkbox disabled checked label="Force User" />
        <Form.Checkbox disabled label="Pilot" />
    </Form.Group>
</Form>

<Form>
    <Form.Group grouped>
        <label>Disabled States</label>
        <Form.Checkbox disabled checked label="Force User" />
        <Form.Checkbox disabled label="Pilot" />
    </Form.Group>
</Form>

Labels and Helper Text

No Label Checkboxes

A checkbox can be isolated, without margins or label text. This is useful when checkboxes are placed in tables.

Label Help

Labels can have a help icon with a tooltip to provide additional context to a label.

Helper Text

<Form>
    <Form.Checkbox
        description={<span>Our terms of service can be found <Link primary>here</Link></span>}
        label="I Agree to Terms of Service"
    />
    <Form.Checkbox
        error="You must agree to create your account."
        label="I Agree to Terms of Service"
    />
    <Form.Checkbox
        description={<span>Our terms of service can be found <Link primary>here</Link></span>}
        error="You must agree to create your account."
        label="I Agree to Terms of Service"
    />
</Form>

<Form>
    <Form.Checkbox
        description={<span>Our terms of service can be found <Link primary>here</Link></span>}
        label="I Agree to Terms of Service"
    />
    <Form.Checkbox
        error="You must agree to create your account."
        label="I Agree to Terms of Service"
    />
    <Form.Checkbox
        description={<span>Our terms of service can be found <Link primary>here</Link></span>}
        error="You must agree to create your account."
        label="I Agree to Terms of Service"
    />
</Form>

Indeterminate Checkboxes

Checkboxes can also be in an indeterminate state. This state is commonly used on checkboxes that control groups of items such as the bulk selection checkbox in Gmail.

Clicking a parent checkbox typically either selects or deselects all child checkboxes. When clicking a parent checkbox in an indeterminate state, default to select all.

<State initial={[
    { value: 1, isChecked: false, text: "Mercury" },
    { value: 2, isChecked: false, text: "Venus" },
    { value: 3, isChecked: true, text: "Earth" },
    { value: 4, isChecked: false, text: "Mars" }
]}>
    {([state, setState]) => (
        <Form>
            <Checkbox
                checked={state.every(i => i.isChecked)}
                indeterminate={state.some(i => i.isChecked) && !state.every(i => i.isChecked)}
                label="Planets"
                onChange={
                    (value, checked) => setState(prev => prev.map(i => ({...i, isChecked: checked})))
                }
            />
            <Form.Group grouped>
                {state.map((item, index) => (
                    <Form.Checkbox
                        key={index}
                        checked={item.isChecked}
                        value={item.value}
                        label={item.text}
                        onChange={
                            (value, checked) => setState(prev => prev.map(i => i.value === value ? ({...i, isChecked: checked}) : i))
                        }
                        className="m-l-4-i"
                    />
                ))}
            </Form.Group>
        </Form>
    )}
</State>

<State initial={[
    { value: 1, isChecked: false, text: "Mercury" },
    { value: 2, isChecked: false, text: "Venus" },
    { value: 3, isChecked: true, text: "Earth" },
    { value: 4, isChecked: false, text: "Mars" }
]}>
    {([state, setState]) => (
        <Form>
            <Checkbox
                checked={state.every(i => i.isChecked)}
                indeterminate={state.some(i => i.isChecked) && !state.every(i => i.isChecked)}
                label="Planets"
                onChange={
                    (value, checked) => setState(prev => prev.map(i => ({...i, isChecked: checked})))
                }
            />
            <Form.Group grouped>
                {state.map((item, index) => (
                    <Form.Checkbox
                        key={index}
                        checked={item.isChecked}
                        value={item.value}
                        label={item.text}
                        onChange={
                            (value, checked) => setState(prev => prev.map(i => i.value === value ? ({...i, isChecked: checked}) : i))
                        }
                        className="m-l-4-i"
                    />
                ))}
            </Form.Group>
        </Form>
    )}
</State>

Content Guidelines

Give a descriptive, action-oriented label

The user relies on the label to provide context and identify what the checkbox controls. Use positive and active wording for checkbox labels. Include a verb to prompt the user to take action.

Use sentence case (capitalize only the first word and proper nouns) so control labels are easy to scan. Do not use periods for short phrases or single sentences.

Checkbox labels should follow the content guidelines for labels.

Give the user the information they need to make an informed decision

The checkbox label might not give the required information and context they need to make an informed decision about the option.

Inline help is the best option for this situation because it requires no user interaction and is always visible. Keep inline help to 1-2 sentences.

Use the content guidelines for inline help.

Avoid using a Tooltip to communicate this kind of information about an option. It’s an additional step for users to mouse over the Tooltip to reveal its information, and users can’t refer to the Tooltip content and take action at the same time.

Best practices

Checkboxes should:

Work independently from each other: selecting one checkbox shouldn’t change the selection status of another checkbox in the list. The exception is when a checkbox is used to make a bulk selection of multiple items.
Be framed positively: for example, Turn on notifications instead of Turn off notifications
Always have a label when used to toggle a setting on or off
Be listed according to a logical order, whether it’s alphabetical, numerical, time-based, or some other clear system.
Link to more information or include a subtitle as required to provide more explanation. Don’t rely on tooltips to explain a checkbox.

Components

To build a full form, use the Form component.
For more than 5 options, like choosing tags, a Select with multiselect support could be a better option.
To present a list of options where users can only make a single choice, use the Radio component.
To build more prominent checkboxes, or with complex labels, use the Togglebox component.
For actions that have immediate results, use the Toggle Switch

Patterns

Form design pattern for how related controls are ordered.

Importing

We recommend using the Form shorthand component <Form.Checkbox />. It automatically provide the correct Form grouping structure and spacing. You can import the standalone component for custom Form layouts.

import { Checkbox } from '@servicetitan/design-system';