DateRangePicker
The DateRangePicker component is used to select a date range value. At mobile viewports, the browsers native input are used.
Import
- React
- Angular
- Vue.js
// 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"
If the DUIL has been installed, you can use the web component directly:
<duil321-dhl-date-range-picker></duil321-dhl-date-range-picker>
If the DUIL has been installed, you can use the web component directly:
<duil321-dhl-date-range-picker></duil321-dhl-date-range-picker>
Refer to the dhl-date-picker documentation for more details on usage.
Currently, keyboard navigation is not supported.
Code
- React
- Angular
- Vue.js
<DhlDateRangePicker></DhlDateRangePicker>
<duil321-dhl-date-range-picker></duil321-dhl-date-range-picker>
<duil321-dhl-date-range-picker></duil321-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>
<duil321-dhl-grid-container columns="2">
<duil321-dhl-grid-cell span-columns="2">
<duil321-dhl-date-range-picker name="date-picker-1"> </duil321-dhl-date-range-picker>
</duil321-dhl-grid-cell>
<duil321-dhl-grid-cell>
<duil321-dhl-button
type="reset"
variant="text"
>RESET</duil321-dhl-button
>
<duil321-dhl-button
type="submit"
variant="primary"
>SUBMIT</duil321-dhl-button
>
</duil321-dhl-grid-cell>
</duil321-dhl-grid-container>
</form>
<script type="module">
const form = document.querySelector("form");
const dateRange = document.querySelector("duil321-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 a custom date format
The optional format prop changes how the dates are shown in and typed into
both inputs. It is display only: the startDate / endDate props and every
emitted value (dhlChange, dhlStartDateChange, dhlEndDateChange) always stay
in ISO YYYY-MM-DD, so min/max, form submission, and any code reading the
values are unaffected.
Supported formats: YYYY-MM-DD, DD/MM/YYYY, MM/DD/YYYY,
DD.MM.YYYY, DD-MM-YYYY, YYYY/MM/DD, DD MMM YYYY.
<duil321-dhl-date-range-picker
name="date-picker-1"
start-date="2024-12-01"
end-date="2024-12-31"
format="DD.MM.YYYY"
></duil321-dhl-date-range-picker>
<!-- inputs show 01.12.2024 and 31.12.2024; the props stay ISO -->
DD MMM YYYY shows the month as a three letter abbreviation instead of digits.
The month names come from the English locale (Jan, Feb, ... Dec) and are
accepted in any casing when typed.
<duil321-dhl-date-range-picker
name="date-picker-1"
start-date="2024-12-01"
end-date="2024-12-31"
format="DD MMM YYYY"
></duil321-dhl-date-range-picker>
<!-- inputs show 01 Dec 2024 and 31 Dec 2024; the props stay ISO -->
usage with the format derived from the locale
Without a format, the format follows the locale prop: the order and
separator of the locale's numeric date are mapped to the closest supported
format. An explicit format always wins, and without a locale the format
stays YYYY-MM-DD.
| locale | format |
|---|---|
en-US | MM/DD/YYYY |
en-GB, fr-FR | DD/MM/YYYY |
he-IL, de-DE, pl-PL | DD.MM.YYYY |
nl-NL | DD-MM-YYYY |
ja-JP, zh-CN | YYYY/MM/DD |
sv-SE | YYYY-MM-DD |
<duil321-dhl-date-range-picker
name="date-picker-1"
start-date="2024-12-01"
end-date="2024-12-31"
locale="he-IL"
></duil321-dhl-date-range-picker>
<!-- inputs show 01.12.2024 and 31.12.2024; the props stay ISO -->
usage with calendar only (no manual input)
disable-manual-input blocks typing and pasting, so a date can only be picked
from the calendar. Backspace or Delete clears the date, and required keeps
working.
<duil321-dhl-date-range-picker
name="date-picker-1"
disable-manual-input
></duil321-dhl-date-range-picker>
usage with validation (required) and (browser) default validation message
<form novalidate>
<duil321-dhl-grid-container columns="2">
<duil321-dhl-grid-cell span-columns="2">
<duil321-dhl-date-range-picker name="date-picker-1" required> </duil321-dhl-date-range-picker>
</duil321-dhl-grid-cell>
<duil321-dhl-grid-cell>
<duil321-dhl-button
type="reset"
variant="text"
>RESET</duil321-dhl-button
>
<duil321-dhl-button
type="submit"
variant="primary"
>SUBMIT</duil321-dhl-button
>
</duil321-dhl-grid-cell>
</duil321-dhl-grid-container>
</form>
<script type="module">
const form = document.querySelector("form");
const dateRange = document.querySelector("duil321-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>
<duil321-dhl-grid-container columns="2">
<duil321-dhl-grid-cell span-columns="2">
<duil321-dhl-date-range-picker
name="date-picker-1"
required
>
</duil321-dhl-date-range-picker>
</duil321-dhl-grid-cell>
<duil321-dhl-grid-cell>
<duil321-dhl-button
type="reset"
variant="text"
>RESET</duil321-dhl-button
>
<duil321-dhl-button
type="submit"
variant="primary"
>SUBMIT</duil321-dhl-button
>
</duil321-dhl-grid-cell>
</duil321-dhl-grid-container>
</form>
<script type="module">
const form = document.querySelector("form");
const dateRange = document.querySelector("duil321-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>
<duil321-dhl-grid-container columns="2">
<duil321-dhl-grid-cell span-columns="2">
<duil321-dhl-date-range-picker
required
name="date-picker-1"
>
</duil321-dhl-date-range-picker>
</duil321-dhl-grid-cell>
<duil321-dhl-grid-cell>
<duil321-dhl-button
type="reset"
variant="text"
>RESET</duil321-dhl-button
>
<duil321-dhl-button
type="submit"
variant="primary"
>SUBMIT</duil321-dhl-button
>
</duil321-dhl-grid-cell>
</duil321-dhl-grid-container>
</form>
<script type="module">
const form = document.querySelector("form");
const dateRange = document.querySelector("duil321-dhl-date-range-picker");
const validationMessageInvalid = "This field is invalid";
const validationMessageValid = "This field valid";
const text = document.querySelector("duil321-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>
full screen calendar on mobile
The optional is-fullscreen-on-mobile prop swaps the popover calendar for a
full screen one below the 768px breakpoint: the calendar fills the viewport,
its header and its Cancel/Select footer stay put, and the months scroll
vertically without paging. Above the breakpoint nothing changes, so the same
markup serves a phone and a desktop, and variant still decides whether the
desktop calendar shows one month or two.
The first tap sets the start of the range and enables Select; the second sets the end. Cancel, the close button and Escape all dismiss the calendar and put the range back as it was before it was opened, so nothing is kept unless it is confirmed.
While the full screen calendar is in use the fields are text inputs rather than
type="date", so the platform's own picker is not summoned on top of it, and
the calendar button is shown on mobile as the calendar's trigger.
<duil321-dhl-date-range-picker
name="travel-dates"
variant="single-month"
start-date-input-label="From"
end-date-input-label="To"
is-fullscreen-on-mobile="true"
></duil321-dhl-date-range-picker>
The wording of the header and the two buttons comes from localeLabels
(calendarRangeTitle, closeLabel, cancelLabel, selectLabel).
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
alwaysOpen | always-open | An optional prop to keep the date range picker always open. | boolean | false |
dataAriaLabel | data-aria-label | An optional prop naming the Start / End pair, e.g. "Shipment date range", for when there is no visible label to point dataAriaLabelledby at. | string | undefined |
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. Names both the Start / End pair and the calendar dialog. | string | undefined |
dataId | data-id | An optional prop. Gives a valid HTML ID attribute value for the component. | string | `duil321-dhl-date-range-picker-${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 |
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 |
disableManualInput | disable-manual-input | An optional prop to block typing into both inputs, so the dates can only be picked from the calendar. | boolean | false |
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 end date inputfield. It is bound to the input as its label and so gives the input its accessible name. | 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 |
format | format | An optional prop to set the date format shown in and typed into both inputs. This is display only: the startDate / endDate props and every emitted value (dhlChange, dhlStartDateChange, dhlEndDateChange) always stay ISO YYYY-MM-DD. When not set, the format is derived from locale (e.g. de-DE shows DD.MM.YYYY), and without a locale it is YYYY-MM-DD. | "DD MMM YYYY" | "DD-MM-YYYY" | "DD.MM.YYYY" | "DD/MM/YYYY" | "MM/DD/YYYY" | "YYYY-MM-DD" | "YYYY/MM/DD" | undefined |
isDateDisabled | is-date-disabled | 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 |
isFullscreenOnMobile | is-fullscreen-on-mobile | An optional prop that turns the calendar into a full screen, vertically scrollable one on narrow screens. Above the 768px breakpoint the picker is unaffected and keeps rendering the popover calendar, so the same markup serves a phone and a desktop. Has no effect together with alwaysOpen, which is an inline calendar with nothing to dismiss. | 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 | locale-labels | 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; invalidDateErrorMessage: string; invalidDateRangeErrorMessage: string; closeLabel?: string; cancelLabel?: string; selectLabel?: string; calendarTitle?: string; calendarRangeTitle?: string; rangeButtonLabel?: 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 |
showCalendarHeader | show-calendar-header | An optional prop to hide the full screen calendar's header, which carries the close button and the year. | boolean | true |
showCta | show-cta | An optional prop that puts Cancel and Select buttons under the calendar. A tapped date is then only applied once Select is pressed, and Cancel discards it, leaving the value as it was. Has no effect together with alwaysOpen, which is an inline calendar the buttons have nothing to close. | boolean | false |
size | size | An optional size prop for the component. | "md" | "sm" | Sizes.MD |
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. It is bound to the input as its label and so gives the input its accessible name. | string | undefined |
validation | validation | An optional DatePicker validation prop Required Fields type | { type: "warning" | "valid" | "invalid" | "note"; message?: string; } | undefined |
variant | variant | An optional prop to select the variant. By default, the double month variant is used. | "double-month" | "single-month" | DHL_DATE_RANGE_PICKER.VARIANT.DOUBLE_MONTH |
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
Graph
Built by DHL User Interface Library Team!