ba-checkbox-list

A form field for selecting multiple options from a list

 Figma GitHub Storybook

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 list of options, use ba-select or ba-radio-group instead.

Always use the legend attribute to give a meaningful label to the field.

Further reading:

Code

Properties & 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

Events

Event Description Type
baChange Emitted when the checked property has changed. CustomEvent<CheckboxChangeEventDetail>

Methods

isValid() => Promise<boolean>

An exposed method for triggering the inputs required validation

reset() => Promise<void>

Resets the input back to its initial value

Returns

Type: Promise<void>

Slots

Slot Description Permitted elements
Unnamed slot Elements will render in the body of the component <ba‑checkbox‑list>, <ba‑checkbox‑list>
"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>

Permitted ARIA roles

  • none

Parent components

ba-checkbox-list can be slotted into:

Slots

Slot Description Permitted elements
Unnamed slot Elements will render in the body of the component <ba‑checkbox‑list>, <ba‑checkbox‑list>
"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>

Usage

Basic examples

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

An 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>
An checkbox list that allows the user to check up to 3 options using ba-checkbox-list-cards 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.

An list with detailed checkboxes (ba-checkbox-list-card) at the top followed by simplier 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

An optional 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.

An optional checkbox list that a user can check 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.

An optional 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 an exact number of checkboxes.

An optional 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>

All required

You can set all the options in a checkbox list by adding the required attribute to the ba-checkbox-list-item 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 the min, max in combination with the required attribute to set the number of checkboxes that must be selected.

An 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
  • Mimimum 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-input-text name="text-input" label="Input text" required>

<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>
GitHub Storybook Figma library Version 3 release guide Release history BAgel helper QA process