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>
<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>
States
Checkboxes can be in an error state and a disabled state.
<Form>
<Form.Group grouped>
<label>Default States</label>
<Form.Checkbox checked label="Force User" />
<Form.Checkbox label="Pilot" />
</Form.Group>
</Form>
<Form>
<Form.Group grouped>
<label>Error States</label>
<Form.Checkbox error checked label="Force User" />
<Form.Checkbox error 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.
<Form>
<Form.Checkbox
label="Checkbox Label"
labelProps={{
help: "This is help text",
direction: 'r'
}}
/>
</Form>
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>
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>
Custom Label Position
Checkboxes by default have their label to the left. A custom text label can be applied using the standard label, for, and id combination found with HTML checkboxes.
Examples of a label on the left
<Form style={{width: '155px'}}>
<Form.Group grouped>
<Stack
alignItems="center"
justifyContent="space-between"
>
<BodyText
el="label"
htmlFor="checkbox-id1"
className="ta-right m-r-1"
>
Short Label
</BodyText>
<Form.Checkbox
id="checkbox-id1"
name="Checkbox-sample"
/>
</Stack>
<Stack
alignItems="center"
justifyContent="space-between"
>
<BodyText
el="label"
htmlFor="checkbox-id2"
className="ta-right m-r-1"
>
Custom Label
</BodyText>
<Form.Checkbox
id="checkbox-id2"
name="Checkbox-sample"
/>
</Stack>
<Stack
alignItems="center"
justifyContent="space-between"
>
<BodyText
el="label"
htmlFor="checkbox-id3"
className="ta-right m-r-1"
>
A Longer Label
</BodyText>
<Form.Checkbox
id="checkbox-id3"
name="Checkbox-sample"
/>
</Stack>
</Form.Group>
</Form>
<Form>
<Form.Group grouped>
<Stack
alignItems="center"
justifyContent="flex-end"
>
<BodyText
el="label"
htmlFor="checkbox-id4"
className="ta-right m-r-1 m-t-1"
>
Short Label
</BodyText>
<Form.Checkbox
id="checkbox-id4"
name="Checkbox-sample"
className="m-t-0-i"
/>
</Stack>
<Stack
alignItems="center"
justifyContent="flex-end"
>
<BodyText
el="label"
htmlFor="checkbox-id5"
className="ta-right m-r-1 m-t-1"
>
Custom Label
</BodyText>
<Form.Checkbox
id="checkbox-id5"
name="Checkbox-sample"
className="m-t-0-i"
/>
</Stack>
<Stack
alignItems="center"
justifyContent="flex-end"
>
<BodyText
el="label"
htmlFor="checkbox-id6"
className="ta-right m-r-1 m-t-1"
>
A Longer Label
</BodyText>
<Form.Checkbox
id="checkbox-id6"
name="Checkbox-sample"
className="m-t-0-i"
/>
</Stack>
</Form.Group>
</Form>
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.
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.
Related Content
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';
