DateRangePicker

The DateRangePicker component is used to select a date range value. At mobile viewports, the browsers native input are used.

Import

React

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

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

Angular

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

<dhl-date-range-picker></dhl-date-range-picker>

Vue.js

// with @dhl-official/vue-library:
import { DhlDateRangePicker } from "@dhl-official/vue-library"

// with @dhl-official/ui-libraries/vue-library:
import { DhlDateRangePicker } from "@dhl-official/ui-libraries/vue-library"

Refer to the dhl-date-picker documentation for more details on usage.

Currently, keyboard navigation is not supported.

Code

React

<DhlDateRangePicker></DhlDateRangePicker>

Angular

<dhl-date-range-picker></dhl-date-range-picker>

Vue.js

<dhl-date-range-picker></dhl-date-range-picker>

Interactive Demo

Readme

Usage

Dhl-date-range-picker

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-grid-container columns="2">
    <dhl-grid-cell span-columns="2">
      <dhl-date-range-picker name="date-picker-1"> </dhl-date-range-picker>
    </dhl-grid-cell>

    <dhl-grid-cell>
      <dhl-button
        type="reset"
        variant="text"
        >RESET</dhl-button
      >
      <dhl-button
        type="submit"
        variant="primary"
        >SUBMIT</dhl-button
      >
    </dhl-grid-cell>
  </dhl-grid-container>
</form>

<script type="module">
  const form = document.querySelector("form");
  const dateRange = document.querySelector("dhl-date-range-picker");
  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-grid-container columns="2">
    <dhl-grid-cell span-columns="2">
      <dhl-date-range-picker name="date-picker-1" required> </dhl-date-range-picker>
    </dhl-grid-cell>

    <dhl-grid-cell>
      <dhl-button
        type="reset"
        variant="text"
        >RESET</dhl-button
      >
      <dhl-button
        type="submit"
        variant="primary"
        >SUBMIT</dhl-button
      >
    </dhl-grid-cell>
  </dhl-grid-container>
</form>

<script type="module">
  const form = document.querySelector("form");
  const dateRange = document.querySelector("dhl-date-range-picker");
  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-grid-container columns="2">
    <dhl-grid-cell span-columns="2">
      <dhl-date-range-picker
        name="date-picker-1"
        required
      >
      </dhl-date-range-picker>
    </dhl-grid-cell>

    <dhl-grid-cell>
      <dhl-button
        type="reset"
        variant="text"
        >RESET</dhl-button
      >
      <dhl-button
        type="submit"
        variant="primary"
        >SUBMIT</dhl-button
      >
    </dhl-grid-cell>
  </dhl-grid-container>
</form>

<script type="module">
  const form = document.querySelector("form");
  const dateRange = document.querySelector("dhl-date-range-picker");
  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();
    if (isValid) {
      dateRange.validation = {
        type: "valid",
        message: validationMessageValid,
      };
    } else {
      dateRange.validation = {
        type: "invalid",
        message: validationMessageInvalid,
      };
    }
    return isValid;
  });
</script>

usage with custom events

<form novalidate>
  <dhl-grid-container columns="2">
    <dhl-grid-cell span-columns="2">
      <dhl-date-range-picker
        required
        name="date-picker-1"
      >
      </dhl-date-range-picker>
    </dhl-grid-cell>
    <dhl-grid-cell>
      <dhl-button
        type="reset"
        variant="text"
        >RESET</dhl-button
      >
      <dhl-button
        type="submit"
        variant="primary"
        >SUBMIT</dhl-button
      >
    </dhl-grid-cell>
  </dhl-grid-container>
</form>

<script type="module">
  const form = document.querySelector("form");
  const dateRange = document.querySelector("dhl-date-range-picker");

  const validationMessageInvalid = "This field is invalid";
  const validationMessageValid = "This field valid";
  const text = document.querySelector("dhl-text");

  const isElementValid = async () => {
    const isValid = await dateRange.checkValidity();
    if (isValid) {
      dateRange.validation = {
        type: "valid",
        message: validationMessageValid,
      };
    } else {
      dateRange.validation = {
        type: "invalid",
        message: validationMessageInvalid,
      };
    }
    return isValid;
  };

  form.addEventListener("submit", async (e) => {
    e.preventDefault();
    await isElementValid();
  });

  dateRange.addEventListener(
    "dhlChange",
    async (e) => await isElementValid(),
  );
  dateRange.addEventListener(
    "dhlBlur",
    async (e) => await isElementValid(),
  );
</script>

Properties

Property	Attribute	Description	Type	Default
dataAriaLabelledby	data-aria-labelledby	An optional ariaLabelledby prop that establishes the relationships between objects and their label(s), and its value should be one or more element IDs, which refer to elements that have the text needed for labelling. List multiple element IDs in a space delimited fashion.	string	undefined
dataId	data-id	An optional prop. Gives a valid HTML ID attribute value for the component.	string	dhl-date-range-picker-${getRandomString()}
dataRole	data-role	An optional prop defining the role attribute of the component.	string	undefined
dataTestid	data-testid	An optional prop. The test id attached to the component as a data-testid attribute.	string	undefined
direction	direction	An optional prop which forces the opening direction of the calendar modal to be always left or right. This setting can be useful when the input is smaller than the opening date picker would be as by default the picker always opens towards right.	"left" \| "right"	DHL_DATE_PICKER.DIRECTION.RIGHT
endDate	end-date	An optional DatePicker value. Must be in IS0-8601 format: YYYY-MM-DD.	string	undefined
endDateInputLabel	end-date-input-label	An optional prop used to set the label inside the DatePicker start date inputfield. This is also used as an aria label for the input. Please use the dataAriaLabelledby prop with an associated label should you choose to not supply this prop.	string	undefined
firstDayOfWeek	first-day-of-week	An optional prop used to set the first day of the week. Sunday is treated as index 0. The default is 1; Monday.	DaysOfWeek.Friday \| DaysOfWeek.Monday \| DaysOfWeek.Saturday \| DaysOfWeek.Sunday \| DaysOfWeek.Thursday \| DaysOfWeek.Tuesday \| DaysOfWeek.Wednesday	DaysOfWeek.Monday
isDateDisabled	--	An optional prop used to set which days are disabled and therefore disallowed. For example, this can be used to disallow selection of weekends.	(date: Date) => boolean	() => false
isDisabled	is-disabled	An optional flag to define if the component is disabled.	boolean	false
locale	locale	An optional prop used to change the calendar locale - following the the BCP 47 standard Note that localeLabels is provided by default in English en-GB. If you want to use a different locale, you will need to provide your own localeLabels prop.	string	"default"
localeLabels	--	An optional prop used to set the DatePicker localization labels and aria labels. Defaults to English en-GB.	{ buttonLabel: string; selectedDateMessage: string; selectedDateRangeMessage: string; prevMonthLabel: string; nextMonthLabel: string; prevYearLabel: string; nextYearLabel: string; monthSelectLabel: string; yearSelectLabel: string; closeLabel: string; invalidDateErrorMessage: string; invalidDateRangeErrorMessage: string; }	defaultLocaleLabels
max	max	An optional prop used to set the maximum date allowed to be picked. Must be in IS0-8601 format: YYYY-MM-DD. This setting can be used alone or together with the min property.	Date \| string	undefined
min	min	An optional prop used to set the minimum date allowed to be picked. Must be in IS0-8601 format: YYYY-MM-DD. This setting can be used alone or together with the max property.	Date \| 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	${getRandomString()}-date
required	required	An optional prop to flag the component as required within a form context.	boolean	false
startDate	start-date	An optional DatePicker value. Must be in IS0-8601 format: YYYY-MM-DD.	string	undefined
startDateInputLabel	start-date-input-label	An optional prop used to set the label inside the DatePicker start date inputfield. This is also used as an aria label for the input. Please use the dataAriaLabelledby prop with an associated label should you choose to not supply this prop.	string	undefined
validation	--	An optional DatePicker validation prop Required Fields type	{ type: Variants.valid \| Variants.invalid \| Variants.note; message?: string; }	undefined

Events

Event	Description	Type
dhlBlur	Event emitted when the component loses focus.	CustomEvent<{ component: string; componentId: string; }>
dhlChange	Event emitted when the component changes value.	CustomEvent<{ value: { start?: string; end?: string; }; }>
dhlClose	Event emitted when the component is closed.	CustomEvent<{ component: string; componentId: string; }>
dhlEndDateChange	Event emitted when the endDate value changes.	CustomEvent<{ component: string; componentId: string; value: string; valueAsDate: Date; short: string; long: string; }>
dhlFocus	Event emitted when the component is focused.	CustomEvent<{ component: string; componentId: string; }>
dhlOpen	Event emitted when the component is opened.	CustomEvent<{ component: string; componentId: string; }>
dhlStartDateChange	Event emitted when the startDate value changes.	CustomEvent<{ component: string; componentId: string; value: string; valueAsDate: Date; short: string; long: string; }>

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.

getEndDateInputElement() => Promise<HTMLInputElement>

Retrieves the start date input element asynchronously.

Returns

Type: Promise<HTMLInputElement>

A promise that resolves to the input element.

getStartDateInputElement() => Promise<HTMLInputElement>

Retrieves the start date input element asynchronously.

Returns

Type: Promise<HTMLInputElement>

A promise that resolves to the input element.

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.

hide(moveFocusToButton?: boolean) => Promise<void>

Hide the calendar modal. Set moveFocusToButton to false to prevent focus returning to the date picker's button. Default is true.

Parameters

Name	Type	Description
moveFocusToButton	boolean

Returns

Type: Promise<void>

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.

setFocus() => Promise<void>

Sets focus on the date picker's input. Use this method instead of the global focus().

Returns

Type: Promise<void>

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

Sets the validity state of the component.

Parameters

Name	Type	Description
validity	ValidityState	- The validity state to set.
validationMessage	string	- An optional validation message to set.

Returns

Type: Promise<void>

A Promise that resolves when the validity state is set.

show() => Promise<void>

Show the calendar modal, moving focus to the calendar inside.

Returns

Type: Promise<void>

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.

Dependencies

Depends on

• dhl-input-group
• dhl-icon
• dhl-button
• dhl-text
• dhl-label

Graph

---

Built by DHL User Interface Library Team!