Checkbox

Installation

import { Checkbox } from "@octopusdeploy/design-system-components"

import { CheckboxGroup } from "@octopusdeploy/design-system-components"

Using the Checkbox component

There are two ways to use a Checkbox that impacts how you use the checkbox component:

• A singular checkbox
• As a group of checkboxes

Singular Checkbox

If you are using a singular checkbox you can import the Checkbox component on it’s own, it will handle rendering a single checkbox.

For Example:

                                                        
                                                        
                                                            import { Checkbox } from "@octopusdeploy/design-system-components";
                                                        
                                                        <Checkbox  
                                                          label={label} 
                                                          value={value} 
                                                          onChange={onChange} 
                                                          disabled={isDisabled}
                                                        />
                                                        
                                                            

Checkbox without a label

This approach should only be used in rare situations where the surrounding context already makes the checkbox’s purpose clear, for example, in a data table where each row includes a checkbox for selecting one or more items and the column header or row content provides the necessary meaning.

Accessibility requirements become even more critical when a visible label is removed. An ariaLabel must always be provided so assistive technologies can correctly communicate the checkbox’s purpose, not providing one will result in an error in your code editor.

Additionally, removing the label also removes access to supporting features such as description text, popover, and the defaultMarker. For this reason, unlabeled checkboxes should only be used when the interaction remains clear and usable without these supporting elements.

                                                        
                                                        
                                                            import { Checkbox } from "@octopusdeploy/design-system-components";
                                                        
                                                        <Checkbox  
                                                          ariaLabel={ariaLabel} 
                                                          value={value} 
                                                          onChange={onChange} 
                                                          disabled={isDisabled}
                                                        />
                                                        
                                                            

Group of Checkboxes

When setting up a group of Checkbox’s import Checkbox and CheckboxGroup separately. Here you set CheckboxGroup as the parent and add as many checkboxes as children as you need with Checkbox. This makes managing children easier when in a group (Similar to the RadioGroup) component.

When using checkboxes in a group, pass the group’s name to CheckboxGroup (see below). This propagates the name to each checkbox, eliminating the need to repeat it. If desired, you may still set a name on individual checkboxes.

For example:

                                                        
                                                        
                                                            import { Checkbox } from "@octopusdeploy/design-system-components";
                                                        import { CheckboxGroup } from "@octopusdeploy/design-system-components";
                                                         
                                                         <CheckboxGroup 
                                                           value={value} 
                                                           onChange={onChange} 
                                                           label="Label for Checkbox" 
                                                           description="An optional description" 
                                                           name="nameOfGroup"
                                                        
                                                           // When using inside the expandable form sections you can hide the additional label and description
                                                           hideLabel={true} 
                                                           hideDescription={true}
                                                        >
                                                            <Checkbox value="option1" label="Option 1" />
                                                            <Checkbox value="option2" label="Option 2" hasDefaultMarker={true} />
                                                        </CheckboxGroup>
                                                        
                                                            

Expandable form sections

When using inside an ExpandableFormSection you can enable the two boolean props: hideLabel and hideDescription. This visually hides the label and description and instead uses the ExpandableFormSection label and description, while ensuring it is still accessible for assistive technology.

Moving your label and description into a const and sharing them between the ExpandableFormSection and Checkbox is encouraged to ensure consistency.

Form Description

Form descriptions allow you to pass in a string, with the option to include an inline code descriptor or link. It has a particular format to allow for flexibility. You can include as many links or code descriptors as you need.

For example:

                                                        
                                                        
                                                             descriptionText`Set ${descriptionText.code("itemEnabled")} to true or see our ${descriptionText.link("guide", "/docs/guide")} for more details.`
                                                        
                                                            

The above code will render the following:

Adding a Popover to the label

This is used to display a Popover with more content explaining the context of a field. It should only be used when the Helper text is not sufficient.

To include this you can pass the PopoverBasicHelp component to the popover prop e.g.

                                                        
                                                        
                                                            <Checkbox
                                                          label="With Popover"
                                                          value="Popover"
                                                          popover={<PopoverBasicHelp placement="right-start" description="A popover" />}
                                                          onChange={handleChange} 
                                                        >
                                                        
                                                            

Displaying a validation message

To display a validation message, use the validationMessage prop on the CheckboxGroup. This will be displayed as an error message below the group. Other validation states are not supported for checkboxes.

Code Sub-components

Sub-components compose the Form components in the Design System. However, they are not exposed via the design system package and cannot be used on their own. Instead, use the packaged components we ship, e.g., Checkbox, etc.

Should you require changes to the sub-components, please reach out in #team-frontend-foundations-requests or follow the Contribution guidelines.

Examples

Indeterminate State

An indeterminate state might be used when you have a “Select All” checkbox but you unselect some of the options, leaving the checkbox in an indeterminate or “mixed” state.

Singular Checkbox

A checkbox can be used as a Singular checkbox on it’s own without the need for the group wrapper.