Skip to content
lab components / Forms and input

Checkbox

Allow users to select one or more items from a list

ExamplesPropertiesGuidelinesNotable changes

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { Checkbox } from "@siteimprove/fancylab";

#Examples

#Base checkbox

This interactive input control indicates the current state. By default, it is unchecked.

Theme: agentic-ai-2025
const [checked, setChecked] = useState(false); return <BaseCheckbox checked={checked} onChange={(e) => setChecked(e.target.checked)} />;

#Checkbox

Provide a label indicating to users what can be selected or deselected.

Theme: agentic-ai-2025
const [checked, setChecked] = useState(false); return ( <Checkbox value="value" checked={checked} onChange={(e) => setChecked(e.target.checked)}> Label </Checkbox> );

#Checkbox group

When using CheckboxGroup, provide a group label to indicate the category of the options and explain what can be selected.

  • Default state:

    by default, checkboxes are unchecked, meaning no options have been selected. Use checked state when the item is selected.

  • Indeterminate state:

    use the indeterminate state when you have a list of selections, where some items are are selected, and some are unselected.

  • Disabled state:

    when the user expects a predefined set of options, a disabled option is useful to indicate that normally that option would be available, but now it is not available due to a specific condition. If possible, provide hint text or a visual cue to checkbox is disabled to avoid confusion for the user.

  • Label with dynamic text:

    be aware of how the labels will resize and how any visuals surrounding them will be affected.

  • Label with icon or tooltip:

    help the user understand the context of the checkbox.
Theme: agentic-ai-2025
const [selected, setSelected] = useState<string[]>([]); return ( <CheckboxGroup onChange={setSelected} value={selected}> <CheckboxGroup.Checkbox value="option-1">Regular option</CheckboxGroup.Checkbox> <CheckboxGroup.Checkbox value="option-2" indeterminate> Indeterminate option </CheckboxGroup.Checkbox> <CheckboxGroup.Checkbox value="option-3" disabled> Disabled option </CheckboxGroup.Checkbox> <CheckboxGroup.Checkbox value="option-4"> <Icon> <IconApprove /> </Icon> <InlineText>Option with left icon</InlineText> </CheckboxGroup.Checkbox> <CheckboxGroup.Checkbox value="option-5"> {(props: { checked: boolean; disabled: boolean }) => ( <> <InlineText emphasis={props.checked ? "medium" : "normal"} lineHeight="multi-line" tone={props.disabled ? "subtle" : undefined} > Option with right icon and dynamic text style </InlineText> <Icon> <IconApprove /> </Icon> </> )} </CheckboxGroup.Checkbox> <Tooltip variant={{ type: "interactive" }} content="Extra info on the option 5"> <CheckboxGroup.Checkbox value="option-6">Option with tooltip</CheckboxGroup.Checkbox> </Tooltip> </CheckboxGroup> );

#Horizontal checkbox group

Make a horizontal group by using the direction prop on the CheckboxGroup component.

Theme: agentic-ai-2025
const [selected, setSelected] = useState<string[]>([]); return ( <CheckboxGroup onChange={setSelected} value={selected} direction="horizontal"> <CheckboxGroup.Checkbox value="option-1">Regular option</CheckboxGroup.Checkbox> <CheckboxGroup.Checkbox value="option-2" indeterminate> Indeterminate option </CheckboxGroup.Checkbox> <CheckboxGroup.Checkbox value="option-3" disabled> Disabled option </CheckboxGroup.Checkbox> <CheckboxGroup.Checkbox value="option-4"> <Icon> <IconApprove /> </Icon> <InlineText>Option with left icon</InlineText> </CheckboxGroup.Checkbox> <Tooltip variant={{ type: "interactive" }} content="Extra info on the option 5"> <CheckboxGroup.Checkbox value="option-6">Option with tooltip</CheckboxGroup.Checkbox> </Tooltip> </CheckboxGroup> );

#Properties

#Base checkbox

Theme: agentic-ai-2025
PropertyDescriptionDefinedValue
checkedRequired
booleanDetermines if the checkbox appears checked or not
onChangeRequired
functionEvent for when the state of the checkbox changes
idOptional
stringId applied to the form control
onBlurOptional
functionCallback for onBlur event
aria-describedbyOptional
stringID of an an element that describes what the form control is for
aria-labelOptional
stringLabel of the form control
aria-labelledbyOptional
stringID of an an element that labels this form control
valueOptional
stringValue of the form control
nameOptional
stringName applied to the form control
invalidOptional
booleanIs the form control invalid
disabledOptional
booleanDisables the checkbox, prevent it from changing state
indeterminateOptional
booleanShows the checkbox as neither checked nor unchecked
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)
tabIndexOptional
numberTab index of the outermost HTML element of the component
onKeyDownOptional
functionCallback for onKeyDown event
onMouseDownOptional
functionCallback for onMouseDown event
onMouseEnterOptional
functionCallback for onMouseEnter event
onMouseLeaveOptional
functionCallback for onMouseLeave event
onFocusOptional
functionCallback for onFocus event

#Checkbox

Theme: agentic-ai-2025
PropertyDescriptionDefinedValue
onChangeRequired
functionEvent for when the state of the checkbox changes
checkedRequired
booleanDetermines if the checkbox appears checked or not
valueRequired
stringValue of the form control
idOptional
stringId applied to the form control
disabledOptional
booleanDisables the checkbox, prevent it from changing state
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
onKeyDownOptional
functionCallback for onKeyDown event
onBlurOptional
functionCallback for onBlur event
onMouseDownOptional
functionCallback for onMouseDown event
aria-describedbyOptional
stringID of an an element that describes what the form control is for
aria-labelOptional
stringLabel of the form control
aria-labelledbyOptional
stringID of an an element that labels this form control
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)
nameOptional
stringName applied to the form control
tabIndexOptional
numberTab index of the outermost HTML element of the component
onMouseEnterOptional
functionCallback for onMouseEnter event
onMouseLeaveOptional
functionCallback for onMouseLeave event
onFocusOptional
functionCallback for onFocus event
invalidOptional
booleanIs the form control invalid
indeterminateOptional
booleanShows the checkbox as neither checked nor unchecked
childrenOptional
element

#Checkbox group

Theme: agentic-ai-2025
PropertyDescriptionDefinedValue
valueRequired
string[]Value of the form control
onChangeRequired
functionCallback for onChange event
nameOptional
stringName applied to the form control
idOptional
stringId applied to the form control
invalidOptional
booleanIs the form control invalid
onBlurOptional
functionCallback for onBlur event
aria-labelOptional
stringLabel of the form control
aria-describedbyOptional
stringID of an an element that describes what the form control is for
aria-labelledbyOptional
stringID of an an element that labels this form control
childrenOptional
element
directionOptional
"horizontal" | "vertical"
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)

#Guidelines

#Best practices

#General

Use Checkbox or CheckboxGroup when

  • multiple choices are available, and users can choose zero, one, or multiple items from a list.
  • seven or fewer related items can be selected from a list.
  • the user needs to confirm, save changes, or take explicit action.
  • the user can enable or disable a single feature.

#Placement

Checkboxes are typically used in the following places:

  • Forms

    Checkboxes can be used in forms on a full page, in modals, or in side panels. To group multiple options, checkboxes can be placed in the Form element wrapper component or by using the Select component in the multi-select mode. An example of a checkbox in forms can be found in Keyword Monitoring.

  • Filtering and bulk action

    Checkboxes can be used to filter information on a page, in modals, in forms, or within components. Checkboxes can be used in the Select component when using custom option elements. An example of filtering can be found in Activity Plan Overview.

  • Terms and conditions

    Users can indicate whether they agree or disagree with the terms by ticking or unticking a standalone checkbox. Ticked or unticked a checkbox also indicates that an option is enabled or disabled (e.g. "Remember me on this computer"). Examples of terms and conditions can be found on the page of CMS Plugin Setup.

  • Line Chart

    Checkboxes can be used to toggle the visibility of lines on a chart. Examples of a chart can be found on the page of QA overview.

#Style

  • Checkbox labels are recommended to align to the right of their corresponding base checkboxes. (Cohesive)
  • Checkbox groups can be positioned vertically or horizontally depending on the use case and the UI structure. Whenever possible, arrange the checkboxes vertically to make it easier for the user to scan and compare the options, especially in a form. (Intuitive)
  • Checkbox labels can be wrapped into two lines if they are long and viewed on a mobile screen size. A checkbox label should never be truncated, omitted, or replaced with “…”. (Accessible)
  • Checkbox groups should not be nested. Ensure that all options are on the same level to prevent confusion. (Intuitive)

#Do not use when

  • The user can only choose one item from a list. In this case, use Radios instead.
  • Each of the items represents an independent feature or behaviour and is not related to each other.
  • The user does not need to confirm, save, or take explicit action.
  • The user requires an immediate response or change in the settings. In this case, use the Toggle switch component instead.

#Accessibility

For designers

  • A checkbox should have a label.
  • A checkbox group must have a meaningful name as an aria-label, which helps the screen reader properly announce the group of checkboxes to make it clear that they belong together. To understand what is aria-label, please visit this link.
  • If possible, add a hint text under the checkbox label to improve the clarity of the action and add further context to the label.
  • For BaseCheckbox within the form, containing 10, or more options, add buttons for selecting and deselecting all options. For example: “Select 25 links on this page”, or “Select all 35 links”.

For developers

  • A checkbox must have a visible label. For example: <Checkbox value="Apple">Apple</Checkbox>
  • A group of checkboxes must be contained in a CheckboxGroup component.
  • To allow the screen reader to announce a CheckboxGroup meaningfully, the text of the aria-label must be provided by a designer.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

  • It is recommended that the checkbox label contains three words or less.
  • Use clear and concise checkbox labels and group labels.
  • Use sentence case for a group label.
  • Do not include punctuation after a checkbox label.
  • Use positive and affirmative labels. For example: “Remember password” instead of “Forget password”.
  • Whenever possible, provide a hint text indicating how many items users should select from a list of checkboxes. For example: “Select all that apply”, or “Select at least one item”.

#Notable changes

#Migrating from FancyLab 16.x to FancyLab 17.x

The CheckboxGroup component on FancyLab 16.x or prior takes an array of control objects as input/property, which is terse and works well with typechecking, but it plays poorly with composition. As an example, adding a tooltip to a checkbox label is not possible using this structure as well as changing the icon position to after or before the label.

So, in FancyLab 17.x, the CheckboxGroup component was refactored to allow composing other components with them. Now, instead of having a controls object, subcomponents are used to create the controls.

Please find below an example that illustrates the usage before and after these changes. Note that the controls property has been replaced by children of type CheckboxGroup.Checkbox.

#Before

<CheckboxGroup onChange={setSelected} value={selected} controls={[ { label: "White Wine", value: "white-wine" }, { label: "Red Wine", value: "red-wine" }, ]} />

#After

<CheckboxGroup onChange={setSelected} value={selected}> <CheckboxGroup.Checkbox value="white-wine">White Wine</CheckboxGroup.Checkbox> <CheckboxGroup.Checkbox value="red-wine">Red Wine</CheckboxGroup.Checkbox> </CheckboxGroup>