Checkbox
Let the user select one or more options.
Props
name
string
Unique name to identify the checkbox.
ariaLabel
string
Defines how the text will be translated for the screen reader. If not specified it will fall back to the name.
checked
boolean
Marks the checkbox item as selected.
description
string | React.ReactNode
Additional description text displayed below the checkbox label.
disabled
boolean
Disable this control. It will not receive focus or events.
error
boolean
Shows an error on the checkbox item.
id
string
Sets a unique id for the checkbox element.
indeterminate
boolean
Shows a mixed/partial selection state. Used for 'Select All' checkboxes when some items are selected.
maxWidth
string
Sets the maximum width of the checkbox.
revealAriaLabel
string
Text announced by screen readers when the reveal slot content is displayed.
size
GoabCheckboxSize
Sets the size of the checkbox. 'compact' reduces spacing for dense layouts.
Defaults to
default.
testId
string
Sets a data-testid attribute for automated testing.
text
string
Label shown beside the checkbox.
value
string | number | boolean
The value binding.
mt, mr, mb, ml
Spacing
Apply margin to the top, right, bottom, and/or left of the component.
Events
onBlur
(detail: GoabCheckboxOnBlurDetail) => void
Callback fired when the checkbox loses focus.
onChange
(detail: GoabCheckboxOnChangeDetail) => void
Callback fired when the checkbox selection changes.
onFocus
(detail: GoabCheckboxOnFocusDetail) => void
Callback fired when the checkbox receives focus.
ReactNode
description
ReactNode
Additional description text displayed below the checkbox label.
reveal
ReactNode
Content revealed when the checkbox is checked.
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.
Tip
Use the description prop to add context on complex options where the label alone isn't enough.
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.
