Components / Library Version 5.5.1

Date Range

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

PropertiesExamplesAPIAccessibilityNotes

* 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"
Back to Top