Checkbox
A configurable Checkbox
component used to gather user input through a checkbox.
The component can be used in combination with CheckboxGroup.
Import
- React
- Angular
- Vue.js
// 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"
If the DUIL has been installed, you can use the web component directly:
<dhl-checkbox></dhl-checkbox>
// with @dhl-official/vue-library:
import { DhlCheckbox } from "@dhl-official/vue-library"
// with @dhl-official/ui-libraries/vue-library:
import { DhlCheckbox } from "@dhl-official/ui-libraries/vue-library"
Code
- React
- Angular
- Vue.js
<DhlCheckbox>Example Text</DhlCheckbox>
<dhl-checkbox>Example Text</dhl-checkbox>
<dhl-checkbox>Example Text</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
tochangeEvent
- Rename
disabled
toisDisabled
- 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
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
changeEvent | -- | [DEPRECATED] Use dhlChange event instead.An optional onChange callback handler. | (event: MouseEvent) => void | undefined |
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 | dhl-checkbox-${getRandomString()} |
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 |
isDisabled | is-disabled | An optional flag to define if the component is disabled. | 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. | Sizes.MD \| Sizes.SM | DHL_SELECTION_CONTROL.SIZE.MD |
validation | -- | An optional object to set-up a custom components validation state. Required Fields: message type | { type: Variants.warning \| Variants.valid \| Variants.invalid \| Variants.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" \| "radio-button" \| "radio-button-panel" | DHL_SELECTION_CONTROL.VARIANT.CHECKBOX |
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
Depends on
Graph
Built by DHL User Interface Library Team!