Checkbox

A configurable Checkbox component used to gather user input through a checkbox.
The component can be used in combination with CheckboxGroup.

Import

React

// with @dhl-official/react-library:
import { DhlCheckbox } from "@dhl-official/react-library"

// with @dhl-official/ui-libraries/react-library:
import { DhlCheckbox } from "@dhl-official/ui-libraries/react-library"

Angular

If the DUIL has been installed, you can use the web component directly:

<duil320-dhl-checkbox></duil320-dhl-checkbox>

Vue.js

If the DUIL has been installed, you can use the web component directly:

<duil320-dhl-checkbox></duil320-dhl-checkbox>

Code

React

<DhlCheckbox>Example Text</DhlCheckbox>

Angular

<duil320-dhl-checkbox>Example Text</duil320-dhl-checkbox>

Vue.js

<duil320-dhl-checkbox>Example Text</duil320-dhl-checkbox>

Examples

Example 1

Checkbox component with a label and description

Code example

<DhlCheckbox
  variant="checkbox"
  label="Checkbox Label"
  description="This is a description for the checkbox."
/>

Example 2

Checkbox component showing checkbox-panel variant

Code example

<DhlCheckbox
  variant="checkbox-panel"
  label="Checkbox Label"
  description="This is a description for the checkbox."
/>

Example 3

Checkbox with Panel variant showing a panel-right and a panel-bottom slot

Code example

<DhlCheckbox
  variant="checkbox-panel"
  label="Checkbox Label"
  description="This is a description for the checkbox."
  hasOtherActions={true}
>
  <div slot="panel-right">
    <DhlStatusBadge variant="pill" label="Status" status="info" showDropdownIcon={false}></DhlStatusBadge>
  </div>
  <div slot="panel-bottom">
    <DhlInputField
      variant={{
      label: 'Label',
      placeholder: 'Placeholder',    
      }}
    ></DhlInputField>
  </div>
</DhlCheckbox>

Example 4

Checkbox with Panel variant and a valid state

Code example

<DhlCheckbox
  variant="checkbox-panel"
  label="Checkbox Label"
  description="This is a description for the checkbox."
  validation={{ type: "valid", message: "Shipped successfully" }}
  checked={true}
/>

Example 5

Checkbox with Panel variant and an invalid state

Code example

<DhlCheckbox
  variant="checkbox-panel"
  label="Checkbox Label"
  description="This is a description for the checkbox."
  validation={{ type: "invalid", message: "Package delivery error" }}
  checked={true}
/>

Interactive Demo

Migrating from DUIL 1.0

• Rename onChange to changeEvent
• Rename disabled to isDisabled
• Add formnovalidate

Readme

Usage

Dhl-checkbox

Snippets of code in HTML and JavaScript to show some of the use cases for the component. The code is not meant to be executed, but to be used as a reference for the usage of the component.
Angular, React and Vue usages are not included in this documentation, but can be easily derived from the HTML and JavaScript code.

default usage

<form novalidate>
  <duil320-dhl-checkbox
    name="checkbox-1"
    value="value1"
    >Checkbox 1</duil320-dhl-checkbox
  >
  <duil320-dhl-checkbox
    name="checkbox-2"
    value="value2"
    >Checkbox 2</duil320-dhl-checkbox
  >
  <duil320-dhl-checkbox
    name="checkbox-3"
    value="value3"
    >Checkbox 3</duil320-dhl-checkbox
  >

  <hr />

  <duil320-dhl-button
    type="reset"
    variant="outline"
    >reset</duil320-dhl-button
  >
  <duil320-dhl-button type="submit">submit</duil320-dhl-button>
</form>

<script>
  const form = document.querySelector("form");
  form.addEventListener("submit", async (e) => {
    e.preventDefault();
    console.log(Object.fromEntries(new FormData(form)));
    return await form.checkValidity();
  });
</script>

usage with validation (required) and (browser) default validation message

<form novalidate>
  <duil320-dhl-checkbox
    name="checkbox-1"
    value="value1"
    required
    >Checkbox 1</duil320-dhl-checkbox
  >
  <duil320-dhl-checkbox
    name="checkbox-2"
    value="value2"
    required="true"
    >Checkbox 2</duil320-dhl-checkbox
  >
  <duil320-dhl-checkbox
    name="checkbox-3"
    value="value3"
    required="false"
    >Checkbox 3</duil320-dhl-checkbox
  >

  <hr />

  <duil320-dhl-button
    type="reset"
    variant="outline"
    >reset</duil320-dhl-button
  >
  <duil320-dhl-button type="submit">submit</duil320-dhl-button>
</form>

<script>
  const form = document.querySelector("form");
  form.addEventListener("submit", async (e) => {
    e.preventDefault();
    console.log(Object.fromEntries(new FormData(form)));
    return await form.checkValidity();
  });
</script>

usage with validation (required) and custom validation message

<form novalidate>
  <duil320-dhl-checkbox
    name="checkbox-1"
    value="value1"
    required
    >Checkbox 1</duil320-dhl-checkbox
  >
  <duil320-dhl-checkbox
    name="checkbox-2"
    value="value2"
    required="true"
    >Checkbox 2</duil320-dhl-checkbox
  >
  <duil320-dhl-checkbox
    name="checkbox-3"
    value="value3"
    required="false"
    >Checkbox 3</duil320-dhl-checkbox
  >

  <hr />

  <duil320-dhl-button
    type="reset"
    variant="outline"
    >reset</duil320-dhl-button
  >
  <duil320-dhl-button type="submit">submit</duil320-dhl-button>
</form>

<script>
  const form = document.querySelector("form");
  const checkboxes = document.querySelectorAll("duil320-dhl-checkbox");
  const validationMessageInvalid = "This field is required";
  const validationMessageValid = "This field is valid";

  form.addEventListener("submit", async (e) => {
    e.preventDefault();
    const isValid = await e.target.checkValidity();
    checkboxes.forEach(async (checkbox) => {
      const elementValid = await checkbox.checkValidity();

      checkbox.validation = {
        type: elementValid ? Variants.valid : Variants.invalid,
        message: elementValid
          ? validationMessageValid
          : validationMessageInvalid,
      };
    });
    return isValid;
  });
</script>

usage with read-only state

Unlike isDisabled, a read-only checkbox stays focusable and its value is still submitted with the form — it just can't be toggled by user interaction. This is useful for presenting a value the user isn't currently allowed to change, as opposed to one that's entirely inactive.

<form novalidate>
  <duil320-dhl-checkbox name="terms" value="accepted" checked isReadOnly
    >Terms accepted</duil320-dhl-checkbox
  >

  <duil320-dhl-button type="submit">submit</duil320-dhl-button>
</form>

<script>
  const form = document.querySelector("form");
  form.addEventListener("submit", (e) => {
    e.preventDefault();
    // "terms" is still present in the submitted data, even though the
    // checkbox can't be toggled by the user.
    console.log(Object.fromEntries(new FormData(form)));
  });
</script>

usage with indeterminate state (partial selection)

<duil320-dhl-checkbox id="select-all" value="all">Select all</duil320-dhl-checkbox>

<hr />

<duil320-dhl-checkbox class="row" value="row-1">Row 1</duil320-dhl-checkbox>
<duil320-dhl-checkbox class="row" value="row-2">Row 2</duil320-dhl-checkbox>
<duil320-dhl-checkbox class="row" value="row-3">Row 3</duil320-dhl-checkbox>

<script>
  const selectAll = document.querySelector("#select-all");
  const rows = document.querySelectorAll(".row");

  // `duil320-dhl-checkbox`'s own `checked`/`indeterminate` props only flow downward
  // (they aren't synced back from the internal `duil320-dhl-selection-control` after
  // a user interaction), so reading `element.checked` back off a
  // `duil320-dhl-checkbox` after a click is stale. Track state from each
  // `dhlChange` event's `detail.value` instead.
  const checkedRows = new Set();

  const syncSelectAll = () => {
    selectAll.checked = checkedRows.size === rows.length;
    selectAll.indeterminate = checkedRows.size > 0 && checkedRows.size < rows.length;
  };

  selectAll.addEventListener("dhlChange", (e) => {
    const checkAll = e.detail.value !== null;
    rows.forEach((row) => {
      row.checked = checkAll;
      checkAll ? checkedRows.add(row) : checkedRows.delete(row);
    });
    syncSelectAll();
  });

  rows.forEach((row) => {
    row.addEventListener("dhlChange", (e) => {
      e.detail.value !== null ? checkedRows.add(row) : checkedRows.delete(row);
      syncSelectAll();
    });
  });
</script>

usage with custom events

<form novalidate>
  <duil320-dhl-checkbox
    name="checkbox-1"
    value="value1"
    required
    >Checkbox 1</duil320-dhl-checkbox
  >
  <duil320-dhl-checkbox
    name="checkbox-2"
    value="value2"
    required="true"
    >Checkbox 2</duil320-dhl-checkbox
  >
  <duil320-dhl-checkbox
    name="checkbox-3"
    value="value3"
    required="false"
    >Checkbox 3</duil320-dhl-checkbox
  >

  <hr />

  <duil320-dhl-button
    type="reset"
    variant="outline"
    >reset</duil320-dhl-button
  >
  <duil320-dhl-button type="submit">submit</duil320-dhl-button>
</form>

<script>
  const form = document.querySelector("form");
  const checkboxes = document.querySelectorAll("duil320-dhl-checkbox");

  checkboxes.forEach((checkbox) => {
    checkbox.addEventListener("dhlChange", async (e) => {
      const isValid = await e.target.checkValidity();
      console.log(e.target, "is valid:", isValid);
      return isValid;
    });
  });
</script>

Properties

Property	Attribute	Description	Type	Default
checked	checked	An optional prop used to describe either a checked or unchecked state of the component.	boolean	false
dataAriaDescribedby	data-aria-describedby	An optional prop defining the list of reference IDs (separated by spaces), recommended when you want to an error message on your field.	string	undefined
dataAriaInvalid	data-aria-invalid	An optional prop used to indicate that the form value of the component does not conform to the expected format.	string	undefined
dataAriaLabel	data-aria-label	An optional prop defining the text read by the screen reader to represent the component; use this if you need different text to be read from label.	string	undefined
dataClassName	data-class-name	An optional class name prop for the component.	string	undefined
dataId	id	An optional prop. Gives a valid HTML ID attribute value for the component.	string	`duil320-dhl-checkbox-${getRandomString()}`
dataMaskPii	data-mask-pii	An optional prop to mask sensitive data in session-replay tools. When true, sets data-di-mask on the inner element.	boolean	undefined
dataTestid	data-testid	An optional prop. The test id attached to the component as a data-testid attribute.	string	undefined
dataTracking	data-tracking	An optional data tracking prop for the component.	string	undefined
description	description	An optional prop to set the description for the component.	string	undefined
formNoValidate	form-no-validate	An optional prop used to set native formnovalidate attribute. This bypasses form control validation for form submission for the types image and submit.	boolean	undefined
hasOtherActions	has-other-actions	An optional prop defining whether there are other actions in the panel. If true, click event on the panel will not toggle the checkbox. Only works if variant prop is set to DHL_CHECKBOX.VARIANT.CHECKBOX_PANEL.	boolean	false
indeterminate	indeterminate	An optional prop to visually display the indeterminate (partial selection) state. Takes visual precedence over checked regardless of its value. Visual-only — does not affect the underlying checked state. Clicking an indeterminate checkbox sets checked to true and indeterminate to false.	boolean	false
isDisabled	is-disabled	An optional flag to define if the component is disabled.	boolean	undefined
isReadOnly	is-read-only	An optional flag to define if the component is read-only. Unlike isDisabled, a read-only checkbox stays focusable and its value is still submitted with the form — it just can't be toggled by user interaction. Note: the native readonly HTML attribute has no effect on checkboxes, so this is implemented in JS rather than reflected as readonly.	boolean	undefined
label	label	An optional prop to set the label for the component.	string	undefined
name	name	An optional value to be set to the element HTML name attribute. It takes any valid value that can be used for the name attribute of an HTMLInputElement.	string	undefined
renderLabelAsDiv	render-label-as-div	An optional prop used to prevent a11y multiple label warning, setting renderLabelAsDiv to true presents the inner label as a "div" as opposed to a "label". Ensure that if set true, another label is used for the component - or the ariaLabel/ariaDescribedby prop is used.	boolean	undefined
required	required	An optional prop to flag the component as required within a form context.	boolean	undefined
size	size	An optional size prop for the component.	"md" | "sm"	DHL_CHECKBOX.SIZE.MD
validation	validation	An optional object to set-up a custom components validation state. Required Fields: message type	{ type: "warning" | "valid" | "invalid" | "note"; message?: string; }	undefined
value	value	An optional prop defining the value of the component which is taken when a form is submitted.	string	undefined
variant	variant	An optional prop to set the variant of the component.	"checkbox" | "checkbox-panel"	DHL_CHECKBOX.VARIANT.CHECKBOX

Events

Event	Description	Type
dhlChange	Event emitted when the checkbox value changes.	CustomEvent<{ value: string; }>

Slots

Slot	Description
"panel-bottom"	used for elements intended to be positioned as the bottom of the DhlCheckbox panel variant.
"panel-right"	used for elements intended to be positioned as the right side of the DhlCheckbox panel variant.

Dependencies

Used by

• duil320-dhl-selectable-card
• duil320-dhl-table

Depends on

• duil320-dhl-selection-control

Graph

---

Built by DHL User Interface Library Team!