Checkbox and CheckboxGroup

A system checkbox inherits all of the props available to its ancestor component, the Form.Proto as defined on the TextInput, plus all those available to a native checkbox element.

Default example

The default Checkbox is stand-alone for individual checkboxes. To render a group of checkboxes in one fell-swoop, consider using the CheckboxGroup (documented below).

<Checkbox id="foo" name="example1" label="Default checkbox" value="bar" />
<Checkbox id="bar" name="example2" value="bar" label="Checked by default" checked />
<Checkbox id="fizz" name="example3" value="buzz" label="Checked and disabled" disabled checked />

Sizes

Use the size prop to proportionally adjust the size of a checkbox's width and height. Sizes are the same as those available to the sibling component, TextInput.

<Checkbox id="foo" name="example1" label="Small checkbox" size="small" value="bar" checked />
<Checkbox id="foo" name="example1" label="Large checkbox" size="large" value="bar" checked />

Full-width (entire row)

<Checkbox id="foo" name="example1" label="Default checkbox" value="bar" block />
<Checkbox id="bar" name="example2" value="bar" label="Checked by default" block checked />
<Checkbox id="fizz" name="example3" value="buzz" label="Checked and disabled" block disabled checked />

Stacked (column)

<Checkbox id="foo" name="example1" label="Default checkbox" value="bar" stacked />
<Checkbox id="bar" name="example2" value="bar" label="Checked by default" stacked checked />
<Checkbox id="fizz" name="example3" value="buzz" label="Checked and disabled" stacked disabled checked />

CheckboxGroup

To render a group of related checkboxes, the CheckboxGroup component can be utilized.

Rendering with Checkbox children

<Box overflowX='scroll'>
    <CheckboxGroup label='Group of checkboxes with optional parent label and individual labels'>
        <Checkbox id="cbGroup1" name="cbGroup1" value="cbGroup1" label="Checkbox 1" checked />
        <Checkbox id="cbGroup2" name="cbGroup1" value="cbGroup2" label="Checkbox 2" />
        <Checkbox id="cbGroup3" name="cbGroup1" value="cbGroup3" label="Checkbox 3" />
    </CheckboxGroup>
</Box>

Rendering with items prop

The following is the default look-n-feel when an array of objects is passed to the items prop, which takes on a left-to-right layout flow. Notice how each object items' key->value pair determines the corresponding Form.Label and Checkbox's props.

<CheckboxGroup items={[
    {
        name: 'exampleCbGroup',
        label: 'CheckboxGroup Option 1',
        value: 'example value 1'
    },
    {
        name: 'exampleCbGroup',
        label: 'CheckboxGroup Option 2',
        value: 'example value 2'
    },
    {
        checked: true,
        disabled: true,
        name: 'exampleCbGroup',
        label: 'CheckboxGroup Option 3, pre-checked and disabled',
        value: 'example value 3'
    },
    {
        name: 'exampleCbGroup',
        label: 'CheckboxGroup Option 4',
        value: 'example value 4'
    },
    {
        name: 'exampleCbGroup',
        label: 'CheckboxGroup Option 5',
        value: 'example value 5'
    },
    {
        color: 'purple',
        name: 'exampleCbGroup',
        label: 'CheckboxGroup Option 5 with custom color',
        value: 'example value 5'
    }
]} />

Vertical stack (column)

If a stacked or vertical flow between a checkbox and its corresponding label is desired, pass down the stacked prop on the CheckboxGroup as demonstrated below.

<CheckboxGroup stacked items={[
    {
        name: 'exampleCbGroup',
        label: 'CheckboxGroup Option 1',
        value: 'example value 1'
    },
    {
        checked: true,
        disabled: true,
        name: 'exampleCbGroup',
        label: 'CheckboxGroup Option 2, pre-checked and disabled',
        value: 'example value 2'
    },
    {
        color: 'purple',
        name: 'exampleCbGroup',
        label: 'CheckboxGroup Option 3 with custom color',
        value: 'example value 3'
    }
]} />

Full-width amongst a set via block

Leverage the block prop to span individual checkboxes and their respective label wrappers, within a set, across a full-row, similar to individual checkbox instances.

<CheckboxGroup block items={[
    {
        name: 'exampleCbGroup',
        label: 'CheckboxGroup Option 1',
        value: 'example value 1'
    },
    {
        checked: true,
        disabled: true,
        name: 'exampleCbGroup',
        label: 'CheckboxGroup Option 2, pre-checked and disabled',
        value: 'example value 2'
    },
    {
        color: 'purple',
        name: 'exampleCbGroup',
        label: 'CheckboxGroup Option 3 with custom color',
        value: 'example value 3'
    }
]} />

Unique selection within a set

If you need to limit checkbox selection to one (1) option amongst a set of checkboxes, you can do so via the unique prop

<CheckboxGroup unique block label="Look ma, I can only pick one option!">
    <Checkbox id="UniqueCbGroup1" name="uniqueCbGroup1" value="UniqueCbGroup1" label="Checkbox 1" checked />
    <Checkbox id="UniqueCbGroup2" name="uniqueCbGroup1" value="UniqueCbGroup2" label="Checkbox 2" />
    <Checkbox id="UniqueCbGroup3" name="uniqueCbGroup1" value="UniqueCbGroup3" label="Checkbox 3" />
</CheckboxGroup>

Color and Scheme Usage

As is common with other components, defining the text and background color of a component can be done using various system props, such as color and bg, respectively, or even the scheme prop. When both the color and scheme props are defined for a checkbox item, the color value takes precedence. If a checkbox is disabled, the disabled state color also takes precedence over the scheme value. Check out the following example:

Color Scheme via CheckboxGroup's scheme prop

<Form.CheckboxGroup block placement='right' scheme='purple' label='Sample color schemes defined by parent component'>
    <Checkbox id="cb_color_scheme1" name="cb_color_scheme1" label='Checkbox 1 w/inherited scheme' value="checkbox1" checked />
    <Checkbox id="cb_color_scheme2" name="cb_color_scheme1" label='Checkbox 2 w/inherited scheme' value="checkbox2" checked />
    <Checkbox id="cb_color_scheme2" name="cb_color_scheme1" label='Parent scheme overriden by local disabled state' value="checkbox3" scheme="disabled" disabled checked />
</Form.CheckboxGroup>

Color Scheme via individual Checkbox instances

<Form.CheckboxGroup block placement='right' label='Scheme defined by individual checkbox instances'>
    <Checkbox id="cb_color_scheme1" name="cb_color_scheme1" label='Default' value="default" scheme="default" checked />
    <Checkbox id="cb_color_scheme2" name="cb_color_scheme1" label='Blue' value="blue" scheme="blue" checked />
    <Checkbox id="cb_color_scheme2" name="cb_color_scheme1" label='Disabled' value="disabled" scheme="disabled" disabled checked />
    <Checkbox id="cb_color_scheme2" name="cb_color_scheme1" label='Error' value="error" scheme="error" checked />
    <Checkbox id="cb_color_scheme1" name="cb_color_scheme1" label='Pending' value="pending" scheme="pending" checked />
    <Checkbox id="cb_color_scheme1" name="cb_color_scheme1" label='Purple' value="purple" scheme="purple" checked />
    <Checkbox id="cb_color_scheme2" name="cb_color_scheme1" label='Red' value="red" scheme="red" checked />
    <Checkbox id="cb_color_scheme2" name="cb_color_scheme1" label='Success' value="success" scheme="success" checked />
    <Checkbox id="cb_color_scheme2" name="cb_color_scheme1" label='Warning' value="warning" scheme="warning" checked />
</Form.CheckboxGroup>

Color Schemes via CheckboxGroup's items prop

<CheckboxGroup block label='A set of checkboxes defined with items prop' items={[
    {
        checked: true,
        color: 'purple',
        scheme: 'error',
        name: 'exampleCbGroup',
        label: '`color` and `scheme` defined; `color` wins',
        value: 'example value 1'
    },
    {
        checked: true,
        disabled: true,
        scheme: 'error',
        name: 'exampleCbGroup',
        label: '`disabled` and `scheme` defined; `disabled` wins',
        value: 'example value 2'
    },
    {
        checked: true,
        scheme: 'success',
        name: 'exampleCbGroup',
        label: '`scheme` defined only',
        value: 'example value 3'
    }
]} />

System props

Checkbox components get BACKGROUND BORDER, COMMON, TYPOGRAPHY and CORE VARIANT system props, since the component is an extension of the Form.Item prototype. Read the System Props doc page for a full list of available props.

Checkbox component props

NameTypeDefaultDescription
checkedBooleanSets the checked attribute on the element
disabledBooleanSets the disabled attribute on the element
idStringSets the id attribute on the element
labelStringLabel that describes the input for screen reader users
nameStringSets the name attribute on the element
onChangeFunctionFunction to be called when content in Input changes
requiredBooleanSets the required attribute on the element
schemeStringdefaultSets a color scheme for the checkbox based on the theme's formStyles definition.
valueStringCurrent value of the Input.

CheckboxGroup component props

NameTypeDefaultDescription
childrennodeReact or System components that are of type Checkbox or Radio.
itemsArrayAn array of objects with a set of defined name and label keys for rendering a group of related checkboxes. Use when not defining children literals. Each item object takes all props that an individual Checkbox takes as defined above, in addition to: color; color is for defining the label's text-color; scheme defines a checkbox's color scheme when ticked (checked))
placementString'left'Aligns the checkbox to the left or right of the label text for any given checkbox.
blockBooleanRenders checkbox items full-width, left-to-right (or RTL), where each checkbox and corresponding label text takes up an entire horizontal space-line. Works in tandem with the Form.Label component's block prop.
stackedBooleanRenders individual checkbox items' label and checkbox vertically, or stacked in a column-fashion. Works in tandem with the Form.Label component's stack prop.