Checkbox API

Import

Cimpress UI exports two checkbox-related components:

Checkbox: main component to display a checkbox.
CheckboxGroup: container component that groups related checkboxes together, providing a shared label, optional description, error handling, and state management.

import { Checkbox, CheckboxGroup } from '@cimpress-ui/react';

Controlled/uncontrolled usage

This component can be used in a controlled or uncontrolled way.

In the controlled way, this component doesn’t maintain its own internal state, and its value is provided by the parent component. Use the controlled way when you need to be able to change the state of this component in other parts of your application.

In the uncontrolled way, this component maintains its own internal state, and can optionally notify the parent component when its internal state changes. Use the uncontrolled way when you don’t need to change the state of this component in other parts of your application.

I am controlled by React state

Make the above checkbox indeterminate

I am uncontrolled and unselected by default

I am uncontrolled and selected by default

import { Checkbox, Stack } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [isSelected, setIsSelected] = useState(false);
  const [isIndeterminate, setIsIndeterminate] = useState(false);

  return (
    <Stack gap={32}>
      <Stack gap={16}>
        <Checkbox isSelected={isSelected} isIndeterminate={isIndeterminate} onChange={setIsSelected}>
          I am controlled by React state
        </Checkbox>

        <Checkbox isSelected={isIndeterminate} onChange={setIsIndeterminate}>
          Make the above checkbox indeterminate
        </Checkbox>
      </Stack>

      <Checkbox>I am uncontrolled and unselected by default</Checkbox>

      <Checkbox defaultSelected>I am uncontrolled and selected by default</Checkbox>
    </Stack>
  );
}

Checkbox group

Preview
Code

import { Checkbox, CheckboxGroup, Stack } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [selectedValues, setSelectedValues] = useState<string[]>(['apple']);

  return (
    <Stack gap={32}>
      <CheckboxGroup label="Favorite fruits (controlled)" value={selectedValues} onChange={setSelectedValues}>
        <Checkbox value="apple">Apple</Checkbox>
        <Checkbox value="banana">Banana</Checkbox>
        <Checkbox value="cherry">Cherry</Checkbox>
      </CheckboxGroup>

      <CheckboxGroup label="Favorite fruits (uncontrolled)" defaultValue={['apple']}>
        <Checkbox value="apple">Apple</Checkbox>
        <Checkbox value="banana">Banana</Checkbox>
        <Checkbox value="cherry">Cherry</Checkbox>
      </CheckboxGroup>
    </Stack>
  );
}

Accessibility notes

The checkbox state can be changed by pressing Enter or Space, similar to a native HTML checkbox.

Each checkbox within CheckboxGroup is a separate tab stop within the page’s tab order. Use the Tab key to navigate between checkboxes.

Checkbox and CheckboxGroup require textual labels to remain accessible to assistive technologies. See our accessibility guide for more details.

Group selection

Selection state of checkboxes within CheckboxGroup cannot be set individually. Please use CheckboxGroup’s value/defaultValue props instead.

// This won't work! :(
<CheckboxGroup label="Favourite fruits">
  <Checkbox value="apple">Apple</Checkbox>
  <Checkbox value="banana">Banana</Checkbox>
  <Checkbox value="cherry" defaultSelected>Cherry</Checkbox>
</CheckboxGroup>

// But this will :)
<CheckboxGroup label="Favourite fruits" defaultValue={['cherry']}>
  <Checkbox value="apple">Apple</Checkbox>
  <Checkbox value="banana">Banana</Checkbox>
  <Checkbox value="cherry">Cherry</Checkbox>
</CheckboxGroup>

Forms

Checkbox and checkbox group can integrate with native HTML forms. See our forms guide to learn how to work with forms.

API reference

Checkbox

Allows users to mark an item as selected. Can be used standalone, or as part of CheckboxGroup.

See checkbox usage guidelines.

ref Section titled “ ref ” Ref<HTMLLabelElement>: The ref type for this component.

CheckboxProps

children Section titled “ children ” StringLikeChildren: The label rendered next to the checkbox.
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-label Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
defaultSelected Section titled “ defaultSelected ” boolean: Whether the element should be selected (uncontrolled).
isSelected Section titled “ isSelected ” boolean: Whether the element should be selected (controlled).
onChange Section titled “ onChange ” (isSelected: boolean) => void: Handler that is called when the element's selection state changes.
value Section titled “ value ” string: The value of the input element, used when submitting an HTML form. See MDN.
isIndeterminate Section titled “ isIndeterminate ” boolean: Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction.
name Section titled “ name ” string: The name of the input element, used when submitting an HTML form. See MDN.
form Section titled “ form ” string: The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See MDN.
autoFocus Section titled “ autoFocus ” boolean: Whether the element should receive focus on render.
isRequired Section titled “ isRequired ” boolean: Whether user input is required on the input before form submission.
isInvalid Section titled “ isInvalid ” boolean: Whether the input value is invalid.
isDisabled Section titled “ isDisabled ” boolean: Whether the input is disabled.
isReadOnly Section titled “ isReadOnly ” boolean: Whether the input can be selected but not changed by the user.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

CheckboxGroup

Allows users to select one or more items from a visible list.

See checkbox usage guidelines.

ref Section titled “ ref ” Ref<HTMLDivElement>: The ref type for this component.

CheckboxGroupProps

children * Section titled “ children * ” ReactNode: Checkboxes belonging to the group. Each checkbox must have a value prop defined.
direction Section titled “ direction ” Responsive<Direction>: Determines the direction in which checkboxes will be stacked.

Defaults to 'vertical' .
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
label Section titled “ label ” string: The content to display as the label.
aria-label Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
form Section titled “ form ” string: The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See MDN.
name Section titled “ name ” string: The name of the input element, used when submitting an HTML form. See MDN.
description Section titled “ description ” string: A description for the field. Provides a hint such as specific requirements for what to choose.
error Section titled “ error ” FieldError: An error message for the field.
validate Section titled “ validate ” (value: string[]) => string | true | string[] | undefined: A function that returns an error message (or true) if a given value is invalid. Validation errors are displayed to the user when the form is submitted. For real-time validation, use the error prop instead.
isRequired Section titled “ isRequired ” boolean: Whether user input is required on the input before form submission.
isInvalid Section titled “ isInvalid ” boolean: Whether the input value is invalid.
isDisabled Section titled “ isDisabled ” boolean: Whether the input is disabled.
isReadOnly Section titled “ isReadOnly ” boolean: Whether the input can be selected but not changed by the user.
value Section titled “ value ” string[]: The current value (controlled).
defaultValue Section titled “ defaultValue ” string[]: The default value (uncontrolled).
onChange Section titled “ onChange ” (value: string[]) => void: Handler that is called when the value changes.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

Checkbox API

Import

Controlled/uncontrolled usage

Single checkbox

Checkbox group

Accessibility notes

Group selection

Forms

API reference

Checkbox

ref

children

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

aria-label

aria-labelledby

aria-describedby

aria-details

defaultSelected

isSelected

onChange

value

isIndeterminate

name

form

autoFocus

isRequired

isInvalid

isDisabled

isReadOnly

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft