Skip to main content

CheckboxGroup

A configurable CheckboxGroup component used as a container of Checkbox elements.

Import

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

Code​

<DhlCheckboxGroup>
  [dhl-checkbox elements]
</DhlCheckboxGroup>

Interactive Demo​

Readme​

Usage​

Dhl-checkbox-group​

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-group 
    label="Checkbox Group"
    name="checkbox-group">
    <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
    >
  </dhl-checkbox-group>


  <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 e.target.checkValidity();
  });
</script>

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

<form novalidate>
  <dhl-checkbox-group
    name="checkbox-group"
    label="Checkbox Group"
    required
  >
    <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
    >
  </dhl-checkbox-group>

  <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)));
    await e.target.checkValidity();
  });
</script>

usage with validation (required) and custom validation message​

<form novalidate>
  <dhl-checkbox-group
    label="Checkbox Group"
    name="checkbox-group"
    required
  >
    <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
  >
  </dhl-checkbox-group>

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

<script>
  const form = document.querySelector("form");
  const checkboxGroup = document.querySelector("dhl-checkbox-group");
  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();
    const elementValid = await checkboxGroup.checkValidity();

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

usage with custom events​

<form novalidate>
  <dhl-checkbox-group
    label="Checkbox Group"
    name="checkbox-group"
    data-orientation="vertical"
    required
  >
    <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
    >
  </dhl-checkbox-group>

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

<script>
  const form = document.querySelector("form");
  const checkboxGroup = document.querySelector("dhl-checkbox-group");

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

Properties​

PropertyAttributeDescriptionTypeDefault
dataClassNamedata-class-nameAn optional class name prop for the component.stringundefined
dataIddata-idAn optional prop. Gives a valid HTML ID attribute value for the component.stringdhl-checkbox-group-${getRandomString()}
dataOrientationdata-orientationAn optional prop to determine the layout of the component. It takes any valid value that can be used for the class attribute of an HTMLInputElement.Orientation.horizontal \| Orientation.verticalDHL_CHECKBOX_GROUP.ORIENTATION.HORIZONTAL
dataTestiddata-testidAn optional prop. The test id attached to the component as a data-testid attribute.stringundefined
isDisableddisabledAn optional flag to define if the component is disabled.booleanundefined
labellabelAn optional 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.stringdhl-checkbox-group-${getRandomString()}
requiredrequiredAn optional prop to flag the component as required within a form context.booleanundefined
validation--An optional object to set-up a custom components validation state. Required Fields: 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.string""

Events​

EventDescriptionType
dhlBlurEvent emitted when the component is focused on.CustomEvent<FocusEvent>
dhlChangeEvent emitted when the value has changed.CustomEvent<{ value: any; }>
dhlClickEvent emitted when the component is clicked on.CustomEvent<MouseEvent>
dhlFocusEvent emitted when the component is focused on.CustomEvent<FocusEvent>

Methods​

checkValidity() => Promise<boolean>​

Checks the validity of the input field.

Returns​

Type: Promise<boolean>

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

getValidationMessage() => Promise<string>​

Retrieves the validation message for the input field.

Returns​

Type: Promise<string>

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

reportValidity() => Promise<boolean>​

Reports the validity of the input field.

Returns​

Type: Promise<boolean>

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

setValidity() => Promise<void>​

Sets the validity state of the input field.

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
"unnamed"unnamed children slot for text that accompanies the DhlCheckbox

Dependencies​

Depends on​

Graph​

Built by DHL User Interface Library Team!