Skip to main content

DateRangePicker

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

Import

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

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

Currently, keyboard navigation is not supported.

Code​

<DhlDateRangePicker></DhlDateRangePicker>

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.

localeformat
en-USMM/DD/YYYY
en-GB, fr-FRDD/MM/YYYY
he-IL, de-DE, pl-PLDD.MM.YYYY
nl-NLDD-MM-YYYY
ja-JP, zh-CNYYYY/MM/DD
sv-SEYYYY-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​

PropertyAttributeDescriptionTypeDefault
alwaysOpenalways-openAn optional prop to keep the date range picker always open.booleanfalse
dataAriaLabeldata-aria-labelAn optional prop naming the Start / End pair, e.g. "Shipment date range", for when there is no visible label to point dataAriaLabelledby at.stringundefined
dataAriaLabelledbydata-aria-labelledbyAn 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.stringundefined
dataIddata-idAn optional prop. Gives a valid HTML ID attribute value for the component.string`duil321-dhl-date-range-picker-${getRandomString()}`
dataMaskPiidata-mask-piiAn optional prop to mask sensitive data in session-replay tools. When true, sets data-di-mask on the inner element.booleanundefined
dataRoledata-roleAn optional prop defining the role attribute of the component.stringundefined
dataTestiddata-testidAn optional prop. The test id attached to the component as a data-testid attribute.stringundefined
directiondirectionAn 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
disableManualInputdisable-manual-inputAn optional prop to block typing into both inputs, so the dates can only be picked from the calendar.booleanfalse
endDateend-dateAn optional DatePicker value. Must be in IS0-8601 format: YYYY-MM-DD.stringundefined
endDateInputLabelend-date-input-labelAn 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.stringundefined
firstDayOfWeekfirst-day-of-weekAn 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.WednesdayDaysOfWeek.Monday
formatformatAn 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
isDateDisabledis-date-disabledAn 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
isDisabledis-disabledAn optional flag to define if the component is disabled.booleanfalse
isFullscreenOnMobileis-fullscreen-on-mobileAn 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.booleanfalse
localelocaleAn 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"
localeLabelslocale-labelsAn 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
maxmaxAn 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 | stringundefined
minminAn 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 | 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.string`${getRandomString()}-date`
requiredrequiredAn optional prop to flag the component as required within a form context.booleanfalse
showCalendarHeadershow-calendar-headerAn optional prop to hide the full screen calendar's header, which carries the close button and the year.booleantrue
showCtashow-ctaAn 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.booleanfalse
sizesizeAn optional size prop for the component."md" | "sm"Sizes.MD
startDatestart-dateAn optional DatePicker value. Must be in IS0-8601 format: YYYY-MM-DD.stringundefined
startDateInputLabelstart-date-input-labelAn 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.stringundefined
validationvalidationAn optional DatePicker validation prop Required Fields type{ type: "warning" | "valid" | "invalid" | "note"; message?: string; }undefined
variantvariantAn 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​

EventDescriptionType
dhlBlurEvent emitted when the component loses focus.CustomEvent<{ component: string; componentId: string; }>
dhlChangeEvent emitted when the component changes value.CustomEvent<{ value: { start?: string; end?: string; }; }>
dhlCloseEvent emitted when the component is closed.CustomEvent<{ component: string; componentId: string; }>
dhlEndDateChangeEvent emitted when the endDate value changes.CustomEvent<{ component: string; componentId: string; value: string; valueAsDate: Date; short: string; long: string; }>
dhlFocusEvent emitted when the component is focused.CustomEvent<{ component: string; componentId: string; }>
dhlOpenEvent emitted when the component is opened.CustomEvent<{ component: string; componentId: string; }>
dhlStartDateChangeEvent 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​

NameTypeDescription
moveFocusToButtonboolean

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​

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.

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!