checkbox-group

A reusable Lightning Web Component (LWC) that offers a more flexible and compact way to handle single or multiple checkbox validation than standard Salesforce components.

---

Table of Contents

• Features
• Requirements
• Usage
  • Properties (API)
  • Methods (API)
  • Events
  • Examples
• Styling / Customization
• Contributing
• License

---

Features

---

Requirements

• This component relies on the checkbox component as its underlying building block.

---

Usage

You can use this component inside your Lightning Web Components or Aura components.

Properties (API)

Property	Type	Required	Default	Description
label	String	No	<blank>	Label of the checkbox-group.
readonly	Boolean	No	false	If true, the checkbox-group is read-only.
required	Boolean	No	false	If true, at least one checkbox in the group must be selected.
multiple	Boolean	No	false	If false, only one checkbox in the group can be selected at a time.
messageWhenValueMissing	String	No	Complete this field.	Error message shown when the checkbox-group is required and no checkbox in the group has been selected.

Methods (API)

Method	Arguments	Return Type	Description
clear	None	None	Clears the checkbox selection.
blur	None	None	Removes focus from the last focused checkbox.
focus	None	None	Sets focus on the first checkbox in the group.
checkValidity	None	Boolean	Checks if the input is valid. Returns false if: •  readonly = false and custom validity is set •  readonly = false AND required = true AND no checkbox in the group has been selected •  at least one checkbox in the group is invalid Otherwise returns true.
reportValidity	None	Boolean	Displays the error messages and returns false if the checkbox-group is invalid. If the checkbox-group is valid, reportValidity() clears displayed error messages and returns true.
setCustomValidity	message : String	None	Sets a custom error message to be displayed immediately. If message is [<blank>, null, undefined], custom validity is unset.

Events

Event	Description	Detail
change	The state of a checkbox in the group has changed.	The checkbox that triggered the event.
click	A checkbox in the group has been clicked.	The checkbox that triggered the event.
input	Same as change.	The checkbox that triggered the event.
focus	A checkbox in the group has gained focus.	The checkbox that triggered the event.
blur	A checkbox in the group has lost focus.	The checkbox that triggered the event.

Examples

Example 1: Base Usage

<!-- parentComponent.html -->
<template>
  <c-checkbox-group label="Lorem ipsum dolor sit amet, consectetur adipiscing elit." onchange={handleChange}>
      <c-checkbox data-id="a">Quisque efficitur elit ac leo aliquam, sed vestibulum dolor feugiat.</c-checkbox>
      <c-checkbox data-id="b">Fusce sit amet arcu auctor, volutpat sem nec, porta ante.</c-checkbox>
      <c-checkbox data-id="c">Morbi sit amet libero finibus, semper tortor et, aliquet urna.</c-checkbox>
      <c-checkbox data-id="d">Sed eros leo, convallis sed convallis id, elementum at elit.</c-checkbox>
      <c-checkbox data-id="e">Praesent ullamcorper ligula id ex lacinia, eu luctus mauris laoreet.</c-checkbox>
  </c-checkbox-group>
</template>

// parentComponent.js
import { LightningElement, track } from 'lwc';

export default class ParentComponent extends LightningElement {
  @track values = {};

  handleChange(event) {
      this.values[event.detail.dataset.id] = event.detail.checked;
  }
}

Example 2: Multiple Selection

<!-- parentComponent.html -->
<template>
  <c-checkbox-group label="Lorem ipsum dolor sit amet, consectetur adipiscing elit." onchange={handleChange} multiple>
      <c-checkbox data-id="a">Quisque efficitur elit ac leo aliquam, sed vestibulum dolor feugiat.</c-checkbox>
      <c-checkbox data-id="b">Fusce sit amet arcu auctor, volutpat sem nec, porta ante.</c-checkbox>
      <c-checkbox data-id="c">Morbi sit amet libero finibus, semper tortor et, aliquet urna.</c-checkbox>
      <c-checkbox data-id="d">Sed eros leo, convallis sed convallis id, elementum at elit.</c-checkbox>
      <c-checkbox data-id="e">Praesent ullamcorper ligula id ex lacinia, eu luctus mauris laoreet.</c-checkbox>
  </c-checkbox-group>
</template>

Example 3: Required

<!-- parentComponent.html -->
<template>
  <c-checkbox-group label="Lorem ipsum dolor sit amet, consectetur adipiscing elit." onchange={handleChange} required>
      <c-checkbox data-id="a">Quisque efficitur elit ac leo aliquam, sed vestibulum dolor feugiat.</c-checkbox>
      <c-checkbox data-id="b">Fusce sit amet arcu auctor, volutpat sem nec, porta ante.</c-checkbox>
      <c-checkbox data-id="c">Morbi sit amet libero finibus, semper tortor et, aliquet urna.</c-checkbox>
      <c-checkbox data-id="d">Sed eros leo, convallis sed convallis id, elementum at elit.</c-checkbox>
      <c-checkbox data-id="e">Praesent ullamcorper ligula id ex lacinia, eu luctus mauris laoreet.</c-checkbox>
  </c-checkbox-group>
</template>

Example 4: Read-Only

<!-- parentComponent.html -->
<template>
  <c-checkbox-group label="Lorem ipsum dolor sit amet, consectetur adipiscing elit." onchange={handleChange} readonly>
      <c-checkbox data-id="a" checked>Quisque efficitur elit ac leo aliquam, sed vestibulum dolor feugiat.</c-checkbox>
      <c-checkbox data-id="b" checked>Fusce sit amet arcu auctor, volutpat sem nec, porta ante.</c-checkbox>
      <c-checkbox data-id="c">Morbi sit amet libero finibus, semper tortor et, aliquet urna.</c-checkbox>
      <c-checkbox data-id="d" checked>Sed eros leo, convallis sed convallis id, elementum at elit.</c-checkbox>
      <c-checkbox data-id="e">Praesent ullamcorper ligula id ex lacinia, eu luctus mauris laoreet.</c-checkbox>
  </c-checkbox-group>
</template>

Example 5: Custom Missing Value Message

<!-- parentComponent.html -->
<template>
  <c-checkbox-group label="Lorem ipsum dolor sit amet, consectetur adipiscing elit." onchange={handleChange}
      message-when-value-missing="At least one option must be selected."
      required>
      <c-checkbox data-id="a">Quisque efficitur elit ac leo aliquam, sed vestibulum dolor feugiat.</c-checkbox>
      <c-checkbox data-id="b">Fusce sit amet arcu auctor, volutpat sem nec, porta ante.</c-checkbox>
      <c-checkbox data-id="c">Morbi sit amet libero finibus, semper tortor et, aliquet urna.</c-checkbox>
      <c-checkbox data-id="d">Sed eros leo, convallis sed convallis id, elementum at elit.</c-checkbox>
      <c-checkbox data-id="e">Praesent ullamcorper ligula id ex lacinia, eu luctus mauris laoreet.</c-checkbox>
  </c-checkbox-group>
</template>

Example 6: Custom Validity

<!-- parentComponent.html -->
<template>
  <lightning-button label="Toogle Custom Validity" onclick={handleCustomValidityToogle}></lightning-button>
  <c-checkbox-group label="Lorem ipsum dolor sit amet, consectetur adipiscing elit.">
      <c-checkbox data-id="a">Quisque efficitur elit ac leo aliquam, sed vestibulum dolor feugiat.</c-checkbox>
      <c-checkbox data-id="b">Fusce sit amet arcu auctor, volutpat sem nec, porta ante.</c-checkbox>
      <c-checkbox data-id="c">Morbi sit amet libero finibus, semper tortor et, aliquet urna.</c-checkbox>
      <c-checkbox data-id="d">Sed eros leo, convallis sed convallis id, elementum at elit.</c-checkbox>
      <c-checkbox data-id="e">Praesent ullamcorper ligula id ex lacinia, eu luctus mauris laoreet.</c-checkbox>
  </c-checkbox-group>
</template>

// parentComponent.js
import { LightningElement } from 'lwc';

export default class ParentComponent extends LightningElement {
  handleCustomValidityToogle(event) {
    const checkboxGroup = this.template.querySelector('c-checkbox-group');
    checkboxGroup.setCustomValidity(checkboxGroup.checkValidity() ? 'This field is required.' : '');
  }
}

Example 7: Clear Selection

<!-- parentComponent.html -->
<template>
  <lightning-button label="Clear" onclick={handleClear}></lightning-button>
  <c-checkbox-group label="Lorem ipsum dolor sit amet, consectetur adipiscing elit." multiple>
      <c-checkbox data-id="a">Quisque efficitur elit ac leo aliquam, sed vestibulum dolor feugiat.</c-checkbox>
      <c-checkbox data-id="b">Fusce sit amet arcu auctor, volutpat sem nec, porta ante.</c-checkbox>
      <c-checkbox data-id="c">Morbi sit amet libero finibus, semper tortor et, aliquet urna.</c-checkbox>
      <c-checkbox data-id="d">Sed eros leo, convallis sed convallis id, elementum at elit.</c-checkbox>
      <c-checkbox data-id="e">Praesent ullamcorper ligula id ex lacinia, eu luctus mauris laoreet.</c-checkbox>
  </c-checkbox-group>
</template>

// parentComponent.js
import { LightningElement } from 'lwc';

export default class ParentComponent extends LightningElement {
  handleClear(event) {
    const checkboxGroup = this.template.querySelector('c-checkbox-group');
    checkboxGroup.clear();
  }
}

Example 8: Without Label

<!-- parentComponent.html -->
<template>
  <c-checkbox-group>
      <c-checkbox data-id="a">Quisque efficitur elit ac leo aliquam, sed vestibulum dolor feugiat.</c-checkbox>
      <c-checkbox data-id="b">Fusce sit amet arcu auctor, volutpat sem nec, porta ante.</c-checkbox>
      <c-checkbox data-id="c">Morbi sit amet libero finibus, semper tortor et, aliquet urna.</c-checkbox>
      <c-checkbox data-id="d">Sed eros leo, convallis sed convallis id, elementum at elit.</c-checkbox>
      <c-checkbox data-id="e">Praesent ullamcorper ligula id ex lacinia, eu luctus mauris laoreet.</c-checkbox>
  </c-checkbox-group>
</template>

Example 9: Long Label

<!-- parentComponent.html -->
<template>
  <c-checkbox-group label="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer ultrices leo eget nunc imperdiet, et convallis neque rhoncus. Aenean finibus, enim vel imperdiet porttitor, mauris ipsum varius quam, vitae vulputate orci nisl vel justo. Quisque est ipsum, vehicula a ultricies ut, finibus ut orci. Proin et commodo nisi, sit amet suscipit dui. Nam pellentesque ligula at massa cursus, vitae cursus est ultrices. Sed non dictum ex, et efficitur magna. Donec in commodo leo." multiple>
      <c-checkbox data-id="a">Quisque efficitur elit ac leo aliquam, sed vestibulum dolor feugiat.</c-checkbox>
      <c-checkbox data-id="b">Fusce sit amet arcu auctor, volutpat sem nec, porta ante.</c-checkbox>
      <c-checkbox data-id="c">Morbi sit amet libero finibus, semper tortor et, aliquet urna.</c-checkbox>
      <c-checkbox data-id="d">Sed eros leo, convallis sed convallis id, elementum at elit.</c-checkbox>
      <c-checkbox data-id="e">Praesent ullamcorper ligula id ex lacinia, eu luctus mauris laoreet.</c-checkbox>
  </c-checkbox-group>
</template>

Styling / Customization

You can customize styles (colors, size, margins, etc.) by editing the component's .css file.
Use CSS variables or SLDS design tokens where possible to maintain compatibility with Salesforce themes (light/dark, accessibility).

---

Contributing

1. Open an Issue to report bugs or request features.
2. Fork the repository and create a new branch for your changes.
3. Submit a Pull Request with a clear description of your updates.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.