Components / Library Version 5.11.0

Date Range

The Date Range allows users to type or select a range of dates.

Properties

Examples

API

Accessibility

Notes

* Required property

label-start *

string

The label displayed above the start input.

label-end *

string

The label displayed above the end input.

date-format

string

Conveys the desired date format in the input field placeholders and screen reader messages. Defaults to "mm/dd/yyyy".

disabled

boolean

Disables the date range.

error-message

string

Displays the provided message below both inputs.

invalid-start

boolean

Sets the start input in an error state. Should be used with the error-message property.

invalid-end

boolean

Sets the end input in an error state. Should be used with the error-message property.

required-field

boolean

Indicates both inputs as required with a red asterisk next to their label. Defaults to false.

value-start

string

The value of the start input (in the format specified in date-format).

value-end

string

The value of the end input (in the format specified in date-format).

Usage in HTML

Edit the code below to see changes reflected in the example above.

Javascript Sample

Example code for functionality.

Usage in Elm

Code generated from HTML.

Events

wmStartInputBlur

Emitted when the start input is blurred. Should be used to validate user input, or reformat if necessary. See the Examples tab for Javascript usage.

wmEndInputBlur

Emitted when the end input is blurred. Should be used to validate user input, or reformat if necessary. See the Examples tab for Javascript usage.

wmRangeSelection

Emitted when a full range has been selected via the calendar dropdown. Contains the two dates in several formats. The event.detail object looks like: { startDate: { iso, us, int }, endDate: { iso, us, int } }. Should be used to update value-start and value-end. See the Examples tab for Javascript usage.

input

Emitted when a user types in the input field.

change

Emitted when the user commits a value change.

Methods

reformatDate

Reformats a date string to/from ISO format.

Parameters

inputFormat ("US" | "INT" | "ISO"): Initial format of date.
outputFormat ("US" | "INT" | "ISO"): Desired format of date.
date (string): Date string to reformat.

Usage

reformatDate("US", "ISO", "6/20/1969"); // returns "1969-06-20"
reformatDate("ISO", "INT", "1969-06-20"); // returns "20/06/1969"

isValidIso

Checks an ISO date, returning a boolean based on that date's validity.

Parameters

date (string): ISO date to check.

Usage

isValidIso("1969-06-20"); // returns true
isValidIso("1969-06-33"); // returns false, there is no 33rd day in the month

Keyboard Support

Calendar Button

Key	Function
`Space` `Enter`	Opens the dropdown and moves focus to today's date. If a start or an end date already exists, focuses that date. If both exist, focuses the start date.

Calendar View

Key	Function
`Enter` `Space`	Selects the first date, or if a first date is already selected, selects the second date. If both dates are selected, clears the selection and sets the start date. On selection of the second date, closes the dropdown and focuses the calendar button.
`Escape`	Closes the calendar and focuses the calendar button.
`Up Arrow`	Moves focus a week earlier, changing the view to the previous month if necessary.
`Down Arrow`	Moves focus a week later, changing the view to the next month if necessary.
`Left Arrow`	Moves focus a day earlier, changing the view to the previous month if necessary.
`Right Arrow`	Moves focus a day later, changing the view to the next month if necessary.
`Home`	Focuses first date of the month.
`End`	Focuses last date of the month.

The user can input the date either by typing in the input or by clicking in the calendar. In the first case the input format needs to be validated, whereas it will always be correct in the second. The component provides different events which can be used to handle each case. All validations should be performed when the component is blurred. Some should also be run when the start or end input is blurred. Errors should be cleared when the field is focused again.

Validation	When to perform	Suggested error message
Missing start date	on component blur	"Start date is required"
Missing end date	on component blur	"End date is required"
Missing both dates	on component blur	"Start and end dates are required"
Start date format	on `wmStartInputBlur`	"Please enter a valid start date"
End date format	on `wmEndInputBlur`	"Please enter a valid end date"
Both dates format	on `wmStartInputBlur` and `wmEndInputBlur`	"Please enter valid start and end dates"
Incorrect range	on `wmStartInputBlur` and `wmEndInputBlur`	"Start date must occur before end date"