Component

ba-checkbox-list

A form field for selecting multiple options from a list

Airframe

Active

Figma

Web Components

Active

Storybook

GitHub

React

Planned

React Native

Planned

Design

Code

Accessibility

Anatomy

Legend

The text that clearly describes what the group of checkboxes represents

Hint text

Optional supporting text that states the selection criteria, such as the minimum, maximum, or required number of options to select

List

The container that groups all of the checkbox items and cards into a single field

Checkbox Card

The interactive control that allows users to select or unselect the option

Checkbox Card Slot

The area for descriptive content in a ba-checkbox-list-card that gives users the context needed to make an informed choice

Checkbox list item

A simpler option, provided using ba-checkbox-list-item, for when no additional descriptive content is needed

Design Documentation

Clearly state the selection criteria, such as the minimum, maximum, or required number of options to select, in the legend or hint text. For example, "Pick up to 3 options", "Select at least 1 item" or "Pick all that apply".

This ensures users understand the requirements for making a valid selection and helps prevent errors or confusion during the selection process.

Positioning ba-checkbox-list-item components after ba-checkbox-list-card components helps maintain a clear visual hierarchy, guiding users from options with more detailed descriptions to simpler choices. This layout improves usability and ensures a logical flow in the selection process.

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

<ba-checkbox-list
  legend="Pick 2 options"
  hint-text="Some hint text to help select the right option"
  max="2"
>
  <ba-checkbox-list-item
    value="value1"
    name="name1"
    label="Checkbox List Item 1"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value2"
    name="name2"
    label="Checkbox List Item 2"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value3"
    name="name3"
    label="Checkbox List Item 3"
  ></ba-checkbox-list-item>
</ba-checkbox-list>

Properties and attributes

Property	Attribute	Description	Type	Default
`hintText`	`hint-text`	Text to display between the legend and the checkboxes	`string \| undefined`	`undefined`
`invalid`	`invalid`	Set the checkbox list to invalid state	`boolean \| undefined`	`false`
`legend`(required)	`legend`	Sets the checkbox list legend which will fill the fieldset legend	`string`	`undefined`
`max`	`max`	Minimum number of checkboxes that must be checked	`number \| undefined`	`undefined`
`min`	`min`	Minimum number of checkboxes that must be checked	`number \| undefined`	`undefined`
`required`	`required`	Set to trigger the is required validation	`boolean \| undefined`	`false`

Permitted ARIA roles

None

Slots

Slot	Description	Permitted elements
Unnamed slot	Elements will render in the body of the component	`<ba‑checkbox‑list‑card>`, `<ba‑checkbox‑list‑item>`
`"error"`	Elements will render in the body of the component	`<p>`
`"error-required"`	Elements will render in the body of the component	`<p>`
`"error-min-checked"`	Elements will render in the body of the component	`<p>`
`"error-max-checked"`	Elements will render in the body of the component	`<p>`
`"error-min-and-max-checked"`	Elements will render in the body of the component	`<p>`
`"error-exact-checked"`	Elements will render in the body of the component	`<p>`

Parent components

ba-checkbox-list 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 list back to its initial value and validity.	`Promise<void>`

Usage

Basic usage using ba-checkbox-list-item

In most scenarios, you will use a list that contains only either ba-checkbox-list-item or ba-checkbox-list-card components.

A checkbox list that allows the user to check up to 3 options using ba-checkbox-list-item

<ba-checkbox-list
  legend="Pick all options that apply"
>
  <ba-checkbox-list-item
    value="value1"
    name="name1"
    label="Checkbox List Item 1"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value2"
    name="name2"
    label="Checkbox List Item 2"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value3"
    name="name3"
    label="Checkbox List Item 3"
  ></ba-checkbox-list-item>
</ba-checkbox-list>

Basic usage using ba-checkbox-list-card

Use ba-checkbox-list-card when you need to show more details alongside each option.

A checkbox list that allows the user to check up to 3 options using ba-checkbox-list-card with more details

<ba-checkbox-list
  legend="Pick all options that apply"
>
  <ba-checkbox-list-card
    value="value1"
    name="name1"
    label="Checkbox List Card 1"
  >
    <ba-content>
      <p>More details about the option</p>
    </ba-content>
  </ba-checkbox-list-card>
  <ba-checkbox-list-card
    value="value2"
    name="name2"
    label="Checkbox List Card 2"
  >
    <ba-content>
      <p>More details about the option</p>
    </ba-content>
  </ba-checkbox-list-card>
  <ba-checkbox-list-card
    value="value3"
    name="name3"
    label="Checkbox List Card 3"
  >
    <ba-content>
      <p>More details about the option</p>
    </ba-content>
  </ba-checkbox-list-card>
</ba-checkbox-list>

Mixing ba-checkbox-list-item and ba-checkbox-list-card

In some cases, you may want to mix ba-checkbox-list-item and ba-checkbox-list-card components. This can be useful when you want to provide users with a mix of simple and detailed options.

A list with detailed checkboxes (ba-checkbox-list-card) at the top followed by simpler options

<ba-checkbox-list
  legend="Pick all options that apply"
>
  <ba-checkbox-list-card
    value="value1"
    name="name1"
    label="Checkbox List Card 1"
  >
    <ba-content>
      <p>More details about the option</p>
    </ba-content>
  </ba-checkbox-list-card>
  <ba-checkbox-list-card
    value="value2"
    name="name2"
    label="Checkbox List Card 2"
  >
    <ba-content>
      <p>More details about the option</p>
    </ba-content>
  </ba-checkbox-list-card>
  <ba-checkbox-list-item
    value="value3"
    name="name3"
    label="Checkbox List Item 3"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value4"
    name="name4"
    label="Checkbox List Item 4"
  ></ba-checkbox-list-item>
</ba-checkbox-list>

Pick minimum number

Setting the min attribute will require the user to select a minimum number of checkboxes.

A checkbox list that a user can check at least 2 options

<ba-checkbox-list
  legend="Pick two options"
  min="2"
>
  <ba-checkbox-list-item
    value="value1"
    name="name1"
    label="Checkbox List Item 1"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value2"
    name="name2"
    label="Checkbox List Item 2"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value3"
    name="name3"
    label="Checkbox List Item 3"
  ></ba-checkbox-list-item>
</ba-checkbox-list>

Pick maximum number

Setting the max attribute will set the maximum number of checkboxes a user can select. If you don't supply a max value, the user can select as many checkboxes as they like.

A checkbox list that a user can check up to 2 options

<ba-checkbox-list
  legend="Pick up to 2 options"
  max="2"
>
  <ba-checkbox-list-item
    value="value1"
    name="name1"
    label="Checkbox List Item 1"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value2"
    name="name2"
    label="Checkbox List Item 2"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value3"
    name="name3"
    label="Checkbox List Item 3"
  ></ba-checkbox-list-item>
</ba-checkbox-list>

Pick exact number

Setting both the min and max to the same value will require the user to select an exact number of checkboxes.

A checkbox list that a user can only check 2 options

<ba-checkbox-list
  legend="Pick 2 options"
  min="2"
  max="2"
>
  <ba-checkbox-list-item
    value="value1"
    name="name1"
    label="Checkbox List Item 1"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value2"
    name="name2"
    label="Checkbox List Item 2"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value3"
    name="name3"
    label="Checkbox List Item 3"
  ></ba-checkbox-list-item>
</ba-checkbox-list>

Pick a range between min and max

Setting both the min and max attributes will require the user to select a number of checkboxes within that range.

A checkbox list that a user can check from 2 to 4 options

<ba-checkbox-list
  legend="Pick between 2 and 4 options"
  min="2"
  max="4"
>
  <ba-checkbox-list-item
    value="value1"
    name="name1"
    label="Checkbox List Item 1"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value2"
    name="name2"
    label="Checkbox List Item 2"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value3"
    name="name3"
    label="Checkbox List Item 3"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value4"
    name="name4"
    label="Checkbox List Item 4"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value5"
    name="name5"
    label="Checkbox List Item 5"
  ></ba-checkbox-list-item>
</ba-checkbox-list>

Require at least one option

You can require at least one option in a checkbox list by adding the required attribute to the ba-checkbox-list component.

A checkbox list where all options are required

<ba-checkbox-list
  legend="Check all options"
  required
>
  <ba-checkbox-list-item
    value="value1"
    name="name1"
    label="Checkbox List Item 1"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value2"
    name="name2"
    label="Checkbox List Item 2"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value3"
    name="name3"
    label="Checkbox List Item 3"
  ></ba-checkbox-list-item>
</ba-checkbox-list>

Required min, max, exact

You can use min and max in combination with the required attribute to set the number of checkboxes that must be selected.

A checkbox list that a user must check up to 2 options

<ba-checkbox-list
  legend="Pick up to 2 options"
  max="2"
  required
>
  <ba-checkbox-list-item
    value="value1"
    name="name1"
    label="Checkbox List Item 1"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value2"
    name="name2"
    label="Checkbox List Item 2"
  ></ba-checkbox-list-item>
  <ba-checkbox-list-item
    value="value3"
    name="name3"
    label="Checkbox List Item 3"
  ></ba-checkbox-list-item>
</ba-checkbox-list>

Custom error messages

BAgel provides error messages with translations for:

Required
Minimum number to check
Maximum number to check
Minimum and maximum number to check
Exact number to check

These can be customised using slots.

Specifying custom validation errors

<ba-checkbox-list
  legend="Checkbox legend"
  required
>
  <!-- Checkbox list items -->

  <p slot="error-required">Custom required error message</p>
  <p slot="error-min-checked">Custom min error message</p>
  <p slot="error-max-checked">Custom max error message</p>
  <p slot="error-min-and-max-checked">Custom min and max error message</p>
  <p slot="error-exact-checked">Custom exact error message</p>
</ba-checkbox-list>

Override all error messages

You can override all error messages with the error slot.

Overriding all error messages

<ba-checkbox-list
  legend="Checkbox legend"
  required
>
  <!-- Checkbox list items -->

  <p slot="error">This will override all error messages</p>
  <p slot="error-required">Custom required error message</p>
  <p slot="error-min-checked">Custom min error message</p>
  <p slot="error-max-checked">Custom max error message</p>
  <p slot="error-min-and-max-checked">Custom min and max error message</p>
  <p slot="error-exact-checked">Custom exact error message</p>
</ba-checkbox-list>

Custom validation

You can provide your own custom validation using events and props.

Custom validation

<ba-checkbox-list
  legend="Checkbox legend"
  required
>
  <!-- Checkbox list items -->

  <p slot="error">Custom error message</p>
</ba-checkbox-list>

<script>
  const checkboxList = document.querySelector('ba-checkbox-list');
  checkboxList.addEventListener('baChange', (e) => {
    const value = e.detail.value;

    // Do your custom validation here.
    //
    //
    // Then set the input to invalid
    checkboxList.setAttribute('invalid', '')
  })
</script>

Guidelines

The legend text helps users of assistive technologies understand that this component is a group of related form fields.

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

State: Previous element in DOM has focus

⇥ Tab

First checkbox item or card in the list gets focus

State: A checkbox item or card in the list has focus

␣ Space

Toggles the checked state

⇥ Tab

Next tabbable element gets focus, including any clickable element nested in a card's content slot; after the last item, focus moves to the next tabbable element

Usage and accessibility checklist

Use this checklist to confirm the component has been configured and used correctly.

UX checklist

Use ba-checkbox-list when one, none, or multiple options can be selected from a list
Do not use ba-checkbox-list when only one option can be selected from a group; use ba-select or ba-radio-group instead
Include the selection criteria, such as the minimum, maximum, or required number of options to select, in either the legend or hint text
Place ba-checkbox-list-item components after ba-checkbox-list-card components when both are used in the same list

Accessibility checklist

A meaningful legend is always provided
Hint text clearly communicates any minimum, maximum, or required selection criteria
Custom error messages are clear and describe how to resolve the error
Clickable elements nested in the ba-checkbox-list-card content slot remain independently operable and do not toggle the card when activated
Where multiple clickable elements are nested in the ba-checkbox-list-card content slot, each has a large enough, clearly separated tap target
Focus indicator has not been obscured on all sides of the checkbox list components and for all interactive elements within the ba-checkbox-list-card content slot

These checks are handled by the component and do not need to be repeated each time it is used.

ba-checkbox-list is operable using assistive technology
List is operable with keyboard using tab to move between items and space to toggle
Has a visible focus indicator on all sides of each checkbox
Colour contrast for all states in all BAgel themes
Animations respect users' reduced motion settings
High contrast mode adjustments

ba-checkbox-list

Airframe

Web Components

React

React Native

Anatomy

Legend

Hint text

List

Checkbox Card

Checkbox Card Slot

Checkbox list item

Design Documentation

Live Demo

Properties and attributes

Permitted ARIA roles

Slots

Parent components

Events

Methods

Usage

Basic usage using ba-checkbox-list-item

Basic usage using ba-checkbox-list-card

Mixing ba-checkbox-list-item and ba-checkbox-list-card

Pick minimum number

Pick maximum number

Pick exact number

Pick a range between min and max

Require at least one option

Required min, max, exact

Custom error messages

Override all error messages

Custom validation

Guidelines

Keyboard navigation

State: Previous element in DOM has focus

State: A checkbox item or card in the list has focus

Usage and accessibility checklist

UX checklist

Accessibility checklist