checkbox

A reusable Lightning Web Component (LWC) that offers a more flexible and customizable checkbox than the standard Salesforce checkbox component, making it easy to adapt to a variety of use cases.

---

Table of Contents

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

---

Features

• Label is more flexible than the standard:
  • it can be blank or missing
  • it can contains hyperlinks or other text-oriented HTML tags
  • it's always displayed to the right of the checkbox and formatted as a single block, even when the label text is long
• Option to set the checkbox as read-only
• Option to make the checkbox required (must be checked) with a customizable error message.
  • If the checkbox is required and left unchecked, the error message appears when it loses focus or when the reportValidity() method is called
• Ability to invalidate the checkbox programmatically and show a custom error message using the setCustomValidity(message) method
• Support for creating a validation group using the accompanying checkbox-group component

---

Usage

You can use this component inside your Lightning Web Components, Aura components or together with the companion checkbox-group component.

Properties (API)

Property	Type	Required	Default	Description
checked	Boolean	No	false	State of the checkbox.
value	Boolean	No	false	Same as checked property.
readonly	Boolean	No	false	If true, the checkbox is read-only.
required	Boolean	No	false	If true, the checkbox is required (must be checked).
messageWhenValueMissing	String	No	Complete this field.	Error message shown when the checkbox is required and has not been checked.

Methods (API)

Method	Arguments	Return Type	Description
blur	None	None	Removes focus from the checkbox.
focus	None	None	Sets focus on the checkbox.
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 checked = false Otherwise returns true.
reportValidity	None	Boolean	Displays the error messages and returns false if the checkbox is invalid. If the checkbox 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
change	Checkbox state has changed.
click	Checkbox has been clicked.
input	Same as change.
focus	Checkbox has gained focus.
blur	Checkbox has lost focus.

Examples

Example 1: Basic Usage

<!-- parentComponent.html -->
<template>
  <c-checkbox
    checked={accepted}
    onchange={handleCheckboxChange}>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  </c-checkbox>
</template>

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

export default class ParentComponent extends LightningElement {
  @track accepted = false;

  handleCheckboxChange(event) {
    this.accepted = event.target.checked;
  }
}

Example 2: Required

<!-- parentComponent.html -->
<template>
  <c-checkbox
    onchange={handleCheckboxChange}
    required>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  </c-checkbox>
</template>

Example 3: Read-Only

<!-- parentComponent.html -->
<template>
  <c-checkbox
    checked="true"
    readonly>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  </c-checkbox>
</template>

Example 4: Custom Missing Value Message

<!-- parentComponent.html -->
<template>
  <c-checkbox
    checked={accepted}
    onchange={handleCheckboxChange}
    message-when-value-missing="This field is required."
    required>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  </c-checkbox>
</template>

Example 5: Custom Validity

<!-- parentComponent.html -->
<template>
  <lightning-button label="Toogle Custom Validity" onclick={handleCustomValidityToogle}></lightning-button>
  <c-checkbox>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</c-checkbox>
</template>

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

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

Example 6: Label with hyperlink

<!-- parentComponent.html -->
<template>
  <c-checkbox>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Take a look <a href="https://www.lipsum.com" target="_blank">here</a>.
  </c-checkbox>
</template>

Example 7: Long label

<!-- parentComponent.html -->
<template>
  <c-checkbox>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque efficitur elit ac leo aliquam, sed vestibulum dolor feugiat. Fusce sit amet arcu auctor, volutpat sem nec, porta ante. Morbi sit amet libero finibus, semper tortor et, aliquet urna. Sed cursus euismod purus id malesuada. Sed eros leo, convallis sed convallis id, elementum at elit. Praesent ullamcorper ligula id ex lacinia, eu luctus mauris laoreet. Sed eleifend interdum dolor eu vestibulum. Integer molestie diam eu sapien cursus pharetra. Ut ultrices nunc sem, nec hendrerit neque maximus id. Maecenas molestie nulla ac leo maximus, ut pulvinar arcu efficitur. Duis condimentum vel ipsum sollicitudin consequat. Curabitur lacinia nisl sit amet finibus gravida. Integer efficitur, neque a porttitor mollis, velit risus commodo massa, eget fermentum est massa sit amet quam. Ut quis urna hendrerit, viverra felis mollis, tempor leo. Integer mollis finibus nulla sit amet tempor.
  </c-checkbox>
</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.