Checkbox
Let the user select one or more options.
Props
name
string
Unique name to identify the checkbox.
checked
boolean
Marks the checkbox item as selected.
Defaults to
false.
indeterminate
boolean
Shows a mixed/partial selection state. Used for 'Select All' checkboxes when some items are selected.
Defaults to
false.
text
string
Label shown beside the checkbox.
value
string
The value binding.
disabled
boolean
Disable this control. It will not receive focus or events.
Defaults to
false.
error
boolean
Shows an error on the checkbox item.
Defaults to
false.
testId
string
Sets a data-testid attribute for automated testing.
ariaLabel
string
Defines how the text will be translated for the screen reader. If not specified it will fall back to the name.
description
string
Additional description text displayed below the checkbox label.
revealarialabel
string
Text announced by screen readers when the reveal slot content is displayed.
maxWidth
string
Sets the maximum width of the checkbox.
Defaults to
none.
size
default | compact
Sets the size of the checkbox. 'compact' reduces spacing for dense layouts.
Defaults to
default.
version
1 | 2
The design system version for styling purposes.
Defaults to
1.
mt, mr, mb, ml
none | 3xs | 2xs | xs | s | m | l | xl | 2xl | 3xl | 4xl
Apply margin to the top, right, bottom, and/or left of the component.
Events
onChange
(event: Event) => void
_change
CustomEvent
onRevealChange
(event: Event) => void
_revealChange
CustomEvent
Slots
description
Named slot for content
reveal
Named slot for content
Add and edit lots of filters
const [open, setOpen] = useState(false);<GoabButton onClick={() => setOpen(true)}>Filters</GoabButton>
<GoabDrawer
heading="Filters"
open={open}
onClose={() => setOpen(false)}
position="right"
actions={
<GoabButtonGroup>
<GoabButton type="primary" size="compact" onClick={() => setOpen(false)}>
Apply filters
</GoabButton>
<GoabButton type="tertiary" size="compact" onClick={() => setOpen(false)}>
Cancel
</GoabButton>
</GoabButtonGroup>
}
>
<GoabFormItem label="Entry status">
<GoabCheckboxList name="entryStatus" onChange={() => {}}>
<GoabCheckbox name="draft" text="Draft" value="draft" />
<GoabCheckbox name="published" text="Published" value="published" />
</GoabCheckboxList>
</GoabFormItem>
<GoabFormItem label="Assigned to - Region" mt="l">
<GoabCheckboxList name="region" onChange={() => {}}>
<GoabCheckbox name="calgary" text="Calgary" value="calgary" />
<GoabCheckbox name="central" text="Central" value="central" />
<GoabCheckbox name="edmonton" text="Edmonton" value="edmonton" />
<GoabCheckbox name="north" text="North" value="north" />
<GoabCheckbox name="south" text="South" value="south" />
</GoabCheckboxList>
</GoabFormItem>
<GoabFormItem label="Assigned to" mt="l">
<GoabDropdown name="assignedTo" onChange={() => {}}>
<GoabDropdownItem value="1" label="Person 1" />
<GoabDropdownItem value="2" label="Person 2" />
</GoabDropdown>
</GoabFormItem>
<GoabFormItem label="Date taken" mt="l">
<GoabRadioGroup name="dateTaken" onChange={() => {}}>
<GoabRadioItem value="24" label="Last 24 hours" />
<GoabRadioItem value="72" label="Last 72 hours" />
</GoabRadioGroup>
</GoabFormItem>
</GoabDrawer>Include a link in the helper text of an option
<GoabFormItem label="How would you like to be contacted?">
<GoabCheckboxList name="contact-options">
<GoabCheckbox
name="email"
text="Email"
value="email"
description={
<span>
Help text with a <a href="#">link</a>.
</span>
}
/>
<GoabCheckbox name="phone" text="Phone" value="phone" />
<GoabCheckbox name="text" text="Text message" value="text" />
</GoabCheckboxList>
</GoabFormItem>Reveal input based on a selection
const [contactMethod, setContactMethod] = useState("");
const [checkboxSelection, setCheckboxSelection] = useState<string[]>([]);<GoabFormItem
label="How would you like to be contacted?"
helpText="Select one option"
>
<GoabRadioGroup
name="contactMethod"
value={contactMethod}
onChange={(e) => setContactMethod(e.value)}
>
<GoabRadioItem
value="email"
label="Email"
reveal={
<GoabFormItem label="Email address">
<GoabInput name="email" onChange={() => {}} value="" />
</GoabFormItem>
}
/>
<GoabRadioItem
value="phone"
label="Phone"
reveal={
<GoabFormItem label="Phone number">
<GoabInput name="phoneNumber" onChange={() => {}} value="" />
</GoabFormItem>
}
/>
<GoabRadioItem
value="text"
label="Text message"
reveal={
<GoabFormItem label="Mobile phone number">
<GoabInput name="mobilePhoneNumber" onChange={() => {}} value="" />
</GoabFormItem>
}
/>
</GoabRadioGroup>
</GoabFormItem>
<GoabFormItem label="How would you like to be contacted?" mt="xl">
<GoabCheckboxList
name="contactMethods"
value={checkboxSelection}
onChange={(e) => setCheckboxSelection(e.values || [])}
>
<GoabCheckbox
name="email"
text="Email"
value="email"
reveal={
<GoabFormItem label="Email address">
<GoabInput name="email" onChange={() => {}} value="" />
</GoabFormItem>
}
/>
<GoabCheckbox
name="phone"
text="Phone"
value="phone"
reveal={
<GoabFormItem label="Phone number">
<GoabInput name="phoneNumber" onChange={() => {}} value="" />
</GoabFormItem>
}
/>
<GoabCheckbox
name="text"
text="Text message"
value="text"
reveal={
<GoabFormItem label="Mobile phone number">
<GoabInput name="mobilePhoneNumber" onChange={() => {}} value="" />
</GoabFormItem>
}
/>
</GoabCheckboxList>
</GoabFormItem>Select one or more from a list of options
const [selectedOptions, setSelectedOptions] = useState<string[]>([]);<GoabFormItem
label="How would you like to be contacted?"
helpText="Choose all that apply"
>
<GoabCheckboxList
name="contactPreferences"
value={selectedOptions}
onChange={(e) => setSelectedOptions(e.detail.value)}
>
<GoabCheckbox name="email" text="Email" value="email" />
<GoabCheckbox name="phone" text="Phone" value="phone" />
<GoabCheckbox name="text" text="Text message" value="text" />
</GoabCheckboxList>
</GoabFormItem>Types
Don't
Don't use Button for simple navigation (use Link), toggling state (use Toggle or Checkbox), or minor utility functions (use Icon Button).
Content
Do
Start all checkbox labels with a capital letter.
Don't
Don't include punctuation after checkbox labels.
Other
Do
Use checkboxes when the user can select more than one option.
The form item automatically associates the label with the input for screen readers, ensuring your form is accessible.
Do
Use a form item wrapper on all inputs to add a label, helper text, error message, and more.
Positioning
Do
Put the checkbox input to the left of the label.
Do
List checkbox options vertically.
Don't
Don't list options horizontally when showing more than two options.
States
When you must disable a button or input:
- Provide nearby text explaining what needs to happen first
- Consider showing the element enabled with validation on submit instead
- Use aria-describedby to link the disabled element to explanatory text
Don't
Don't disable buttons or inputs without explaining why. Disabled controls can be confusing and users may not understand why they can't interact with an element.