ba-checkbox-card
An enhanced checkbox component with a description area for additional context
Airframe
Web Components
React
React Native
Anatomy
Checkbox input
The interactive control that allows users to select or unselect the card
Content slot
The area for descriptive content that gives users the context needed to make an informed choice
Label
The text that clearly describes what the checkbox card option means
Card
The clickable container that groups the checkbox, label, and content into a single selectable option
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.
Links, buttons, and other clickable elements (such as ba-link, ba-button, and <a>) can be nested inside the content slot, for example to link out to terms and conditions. Clicking one of these elements activates the element itself rather than toggling the card.
Use this sparingly and only where it's genuinely useful. Adding too many clickable elements makes the card harder to scan and increases the risk of users mis-tapping the card instead of the element (or vice versa). Where multiple clickable elements are used, leave enough space between them so each has a large enough, clearly separated tap target.
Live Demo
Checkbox details
<ba-checkbox-card
label="Checkbox label"
name="checkboxName"
value="checkboxValue"
required
>
<ba-content>
<p>Checkbox details</p>
</ba-content>
</ba-checkbox-card>
Properties and attributes
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
checked |
checked |
If true, the checkbox is selected. |
boolean | undefined |
false |
icon(required) |
icon |
The name of the icon to show | string |
undefined |
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 |
|---|---|---|
| Unnamed slot | Elements will render in the body of the component | <a>, <ba‑content>, <ba‑grid>, <ba‑image>, <ba‑link>, <ba‑media‑object> |
"error" |
Elements will render in the body of the component | <p> |
Parent components
ba-checkbox-card can be slotted into:
Events
| Event | Description | Type |
|---|---|---|
baChange |
Emitted when the checked property has changed. | CustomEvent<CheckboxCardChangeEventDetail> |
Methods
| Method | Description | Type |
|---|---|---|
isValid() => Promise<boolean> |
Triggers required validation and resolves with validity state. | Promise<boolean> |
reset() => Promise<void> |
Resets the checkbox card back to its initial value and validity. | Promise<void> |
Usage
Basic usage
Most scenarios will only require the label attribute and some content
<ba-checkbox-card
label="Checkbox label"
name="checkboxName"
value="checkboxValue"
required
>
<ba-content>
<p>Additional descriptive content goes here</p>
</ba-content>
</ba-checkbox-card>Adding an icon
An icon can be shown between the checkbox and the label.
<ba-checkbox-card
label="Checkbox label"
name="checkboxName"
value="checkboxValue"
required
icon="baggage"
>
<ba-content>
<p>Additional descriptive content goes here</p>
</ba-content>
</ba-checkbox-card>Adding a clickable element
Clickable elements such as ba-link, <a>, and ba-button can be nested inside the content slot. Clicking these elements activates them instead of toggling the card.
<ba-checkbox-card
label="Checkbox label"
name="checkboxName"
value="checkboxValue"
required
>
<ba-content>
<p>Additional descriptive content goes here. Read our <ba-link href="#">terms and conditions</ba-link></p>
</ba-content>
</ba-checkbox-card>Guidelines
Always use the label attribute to give a meaningful label to the field.
Further reading:
Always add descriptive text in the body of ba-checkbox-card to provide users with the context needed for informed selections. This enhances clarity and supports accessibility by offering more information about each option.
If you require a checkbox without a description, use the ba-checkbox component instead.
All of the content in a ba-checkbox-card will be read out at once when a screen reader user lands on it. Keep any descriptive text in the body of ba-checkbox-card short and to the point. If you need to convey more extensive information, consider placing it outside of the card or referencing a separate page/resource. Doing so avoids overwhelming screen reader users and helps maintain a clear, accessible interface.
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-card> gets focus
State: <ba-checkbox-card> has focus
Toggles the checked state
Next tabbable element gets focus, including any clickable element nested in the content slot
State: A clickable element (e.g. a link or button) nested in the content slot has focus
Activates the nested element without toggling the card's checked state
Usage and accessibility checklist
Use this checklist to confirm the component has been configured and used correctly.
UX checklist
- Use ba-checkbox-card when one, none, or multiple options can be selected
- Do not use ba-checkbox-card when only one option can be selected from a group; use ba-select or ba-radio-group instead
- Use ba-checkbox-card instead of ba-checkbox when descriptive content is needed to give users more context about an option
- Descriptive content in the card body is clear and concise
- Clickable elements (such as links or buttons) are used sparingly in the content slot, and only where genuinely useful
Accessibility checklist
- A visible label is always provided
- Descriptive content is concise, as it is all read out at once to screen reader users
- If an icon is added, it does not convey information that isn't already available from the label
- Clickable elements nested in the content slot remain independently operable and do not toggle the card when activated
- Where multiple clickable elements are nested in the content slot, each has a large enough, clearly separated tap target
- Focus indicator has not been obscured on all sides of the component and for all interactive elements within the card
These checks are handled by the component and do not need to be repeated each time it is used.
- ba-checkbox-card is operable using assistive technology
- Card is operable with keyboard using tab to focus the checkbox and space to toggle
- 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