ba-checkbox
A form field for single and multiple selections
Airframe
Web Components
React
React Native
Anatomy
Checkbox input
The interactive control that allows users to select or unselect an option
Label
The text that clearly describes what the checkbox option means
Required indicator
Text to illustrate the checkbox is not required
Design Documentation
This is when one, none, or multiple options can be selected. If only one option can be selected from a list of options, use ba-select or ba-radio-group instead.
Live Demo
<ba-checkbox
label="Checkbox label"
name="checkboxName"
value="checkboxValue"
required
></ba-checkbox>
Properties and attributes
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
checked |
checked |
If true, the checkbox is selected. |
boolean | undefined |
false |
label(required) |
label |
text displayed next to the checkbox | string |
undefined |
name(required) |
name |
The name of the control, which is submitted with the form data. | string |
undefined |
required |
required |
If true, the user must check the checkbox before submitting a form. |
boolean | undefined |
false |
value(required) |
value |
the value of the checkbox. | string |
undefined |
Permitted ARIA roles
- None
Slots
| Slot | Description | Permitted elements |
|---|---|---|
"error" |
Elements will render in the body of the component | <p> |
Parent components
ba-checkbox can be slotted into:
Events
| Event | Description | Type |
|---|---|---|
baChange |
Emitted when the checked property has changed. | CustomEvent<CheckboxChangeEventDetail> |
Methods
| Method | Description | Type |
|---|---|---|
isValid() => Promise<boolean> |
Triggers required validation and resolves with validity state. | Promise<boolean> |
reset() => Promise<void> |
Resets the checkbox back to its initial value and validity. | Promise<void> |
Usage
Basic usage
<ba-checkbox
label="Checkbox label"
name="checkboxName"
value="checkboxValue"
required
></ba-checkbox>Guidelines
Always use the label attribute to give a meaningful label to the field.
Further reading:
Disabled form elements are not supported in BAgel because they create accessibility challenges, such as preventing keyboard navigation, confusing screen reader users, and reducing visual clarity for those with impairments
Further reading:
Keyboard navigation
State: Previous element in DOM has focus
<ba-checkbox> gets focus
State: <ba-checkbox> has focus
Toggles the checked state and emits baChange
Next tabbable element in the DOM gets focus
Usage and accessibility checklist
Use this checklist to confirm the component has been configured and used correctly.
UX checklist
- Use ba-checkbox when one, none, or multiple options can be selected
- Do not use ba-checkbox when only one option can be selected from a group; use ba-select or ba-radio-group instead
- Label text is clear, concise, and helps users make an informed choice
Accessibility checklist
- A visible label is always provided
- Disabled state is only used when interaction is intentionally unavailable
- Checkbox is operable with keyboard using tab to focus and space to toggle
- Focus indicator has not been obscured on all sides of the component
These checks are handled by the component and do not need to be repeated each time it is used.
- ba-checkbox is operable using assistive technology
- Has a visible focus indicator on all sides of the checkbox
- Colour contrast for all states in all BAgel themes
- Animations respect users' reduced motion settings
- High contrast mode adjustments