Skip to main content

Checkbox

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

Import

// 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"

Code​

<DhlCheckbox>Example Text</DhlCheckbox>

Examples​

Basic Checkbox​

A Checkbox component with a label and description.

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

Checkbox with Panel variant​

A Checkbox component showing checkbox-panel variant.

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

Checkbox with Panel variant, valid state and a right slot​

A Checkbox with Panel variant showing a panel-right slot.

<DhlCheckbox
  variant="checkbox-panel"
  label="Checkbox Label"
  description="This is a description for the checkbox."
  validation={{ type: "valid", message: "Shipped successfully" }}
  checked={true}
>
  <div slot="panel-right">
    <DhlIcon
      src={IlluGogreen}
      size="60px"
    />
  </div>
</DhlCheckbox>
Shipped successfully

Checkbox with Panel variant, invalid state and a right slot​

A Checkbox with Panel variant showing a panel-right slot.

<DhlCheckbox
  variant="checkbox-panel"
  label="Checkbox Label"
  description="This is a description for the checkbox."
  validation={{ type: "invalid", message: "Package delivery error" }}
  checked={true}
  >
  <div slot="panel-right">
    <DhlIcon
      src={IlluMovingBox}
      size="60px"
    />
  </div>
</DhlCheckbox>
Package delivery error

Checkbox with Panel variant, a right and bottom slot​

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

<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>
Status

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>
  <dhl-checkbox
    name="checkbox-1"
    value="value1"
    >Checkbox 1</dhl-checkbox
  >
  <dhl-checkbox
    name="checkbox-2"
    value="value2"
    >Checkbox 2</dhl-checkbox
  >
  <dhl-checkbox
    name="checkbox-3"
    value="value3"
    >Checkbox 3</dhl-checkbox
  >

  <hr />

  <dhl-button
    type="reset"
    variant="outline"
    >reset</dhl-button
  >
  <dhl-button type="submit">submit</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>
  <dhl-checkbox
    name="checkbox-1"
    value="value1"
    required
    >Checkbox 1</dhl-checkbox
  >
  <dhl-checkbox
    name="checkbox-2"
    value="value2"
    required="true"
    >Checkbox 2</dhl-checkbox
  >
  <dhl-checkbox
    name="checkbox-3"
    value="value3"
    required="false"
    >Checkbox 3</dhl-checkbox
  >

  <hr />

  <dhl-button
    type="reset"
    variant="outline"
    >reset</dhl-button
  >
  <dhl-button type="submit">submit</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>
  <dhl-checkbox
    name="checkbox-1"
    value="value1"
    required
    >Checkbox 1</dhl-checkbox
  >
  <dhl-checkbox
    name="checkbox-2"
    value="value2"
    required="true"
    >Checkbox 2</dhl-checkbox
  >
  <dhl-checkbox
    name="checkbox-3"
    value="value3"
    required="false"
    >Checkbox 3</dhl-checkbox
  >

  <hr />

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

<script>
  const form = document.querySelector("form");
  const checkboxes = document.querySelectorAll("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 custom events​

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

  <hr />

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

<script>
  const form = document.querySelector("form");
  const checkboxes = document.querySelectorAll("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​

PropertyAttributeDescriptionTypeDefault
changeEvent--[DEPRECATED] Use dhlChange event instead.

An optional onChange callback handler.		(event: MouseEvent) => voidundefined
checkedcheckedAn optional prop used to describe either a checked or unchecked state of the component.booleanfalse
dataAriaDescribedbydata-aria-describedbyAn optional prop defining the list of reference IDs (separated by spaces), recommended when you want to an error message on your field.stringundefined
dataAriaInvaliddata-aria-invalidAn optional prop used to indicate that the form value of the component does not conform to the expected format.stringundefined
dataAriaLabeldata-aria-labelAn 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.stringundefined
dataClassNamedata-class-nameAn optional class name prop for the component.stringundefined
dataIdidAn optional prop. Gives a valid HTML ID attribute value for the component.stringdhl-checkbox-${getRandomString()}
dataTestiddata-testidAn optional prop. The test id attached to the component as a data-testid attribute.stringundefined
dataTrackingdata-trackingAn optional data tracking prop for the component.stringundefined
descriptiondescriptionAn optional prop to set the description for the component.stringundefined
formNoValidateform-no-validateAn optional prop used to set native formnovalidate attribute. This bypasses form control validation for form submission for the types image and submit.booleanundefined
hasOtherActionshas-other-actionsAn 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.booleanfalse
isDisabledis-disabledAn optional flag to define if the component is disabled.booleanundefined
labellabelAn optional prop to set the label for the component.stringundefined
namenameAn 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.stringundefined
renderLabelAsDivrender-label-as-divAn 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.booleanundefined
requiredrequiredAn optional prop to flag the component as required within a form context.booleanundefined
sizesizeAn optional size prop for the component.Sizes.MD \| Sizes.SMDHL_CHECKBOX.SIZE.MD
validation--An optional object to set-up a custom components validation state. Required Fields: message type{ type: Variants.valid \| Variants.invalid \| Variants.note; message?: string; }undefined
valuevalueAn optional prop defining the value of the component which is taken when a form is submitted.stringundefined
variantvariantAn optional prop to set the variant of the component."checkbox" \| "checkbox-panel"DHL_CHECKBOX.VARIANT.CHECKBOX

Events​

EventDescriptionType
dhlBlurEvent emitted when the component loses focus.CustomEvent<FocusEvent>
dhlChangeEvent emitted when the component changes value.CustomEvent<{ value: string; }>
dhlClickEvent emitted when the component is clicked on.CustomEvent<MouseEvent>
dhlFocusEvent emitted when the component receives focus.CustomEvent<FocusEvent>

Methods​

checkValidity() => Promise<boolean>​

Checks the validity of the component.

Returns​

Type: Promise<boolean>

A promise that resolves to true if the component is valid, otherwise false.

getCheckboxElement() => Promise<HTMLInputElement>​

Retrieves the component asynchronously.

Returns​

Type: Promise<HTMLInputElement>

A promise that resolves to the component.

getValidationMessage() => Promise<string>​

Retrieves the validation message for the component.

Returns​

Type: Promise<string>

A promise that resolves to a string representing the validation message.

reportValidity() => Promise<boolean>​

Reports the validity of the component.

Returns​

Type: Promise<boolean>

A promise that resolves to a boolean indicating whether the component is valid.

setValidity(validity: ValidityState, validationMessage?: string) => Promise<void>​

Sets the validity state of the component.

Parameters​

NameTypeDescription
validityValidityState- The validity state to set.
validationMessagestring- An optional validation message to set.

Returns​

Type: Promise<void>

A Promise that resolves when the validity state is set.

willValidate() => Promise<boolean>​

Returns a promise that resolves to true if the element will successfully validate, or false otherwise.

Returns​

Type: Promise<boolean>

A promise that resolves to a boolean value indicating whether the element will validate.

Slots​

SlotDescription
"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​

Depends on​

Graph​

dhl-checkbox
dhl-icon-wrapper
dhl-icon
dhl-required-indicator
dhl-validation-feedback
dhl-validation-feedback-icon
dhl-validation-message
dhl-selectable-card
dhl-table

Built by DHL User Interface Library Team!