Components / Library Version 4.10.0

Datepicker

The Datepicker allows users to type in a date or select a date from a calendar. See the Examples javascript usage tab for more information.

PropertiesExamplesAPIAccessibility

* Required property

label *
string
A description for the input. Required even if the label-position is set to none (for accessibility reasons).
date-format
string
Defaults to "mm/dd/yyyy". Conveys the desired date format in the input field placeholder and screen reader messages.
disabled
boolean
Disables the datepicker.
error-message
string
Sets the component in an error state, displaying the provided message.
label-position
top | left | none
Defaults to top. Set this property to none if no label should be displayed.
preselected
string: iso date
The date the calendar popup focuses when opened. If preselected is not provided, the calendar will open to a date based on the value and date-format property. If the value is unable to be parsed, opens to the current date.
required-field
boolean
Setting this property to true will display a red asterisk next to the label to indicate it is required. Defaults to false.
value
string
The date displayed in the input field. The value property is updated as the user types, and can be set by the application as necessary.

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.

Methods

See source code for method definitions.

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

Events

wmDatepickerInputBlurred
Emitted when the Datepicker's input field is blurred.
wmDatepickerDateSelected
Emitted when a date is selected from Datepicker's calendar popup. The event detail contains the selected date in iso format.
input
Emitted when a user types in the input field.
change
Emitted when the user commits a value change.

Keyboard Support

Input Field

Key Function
Tab Focuses the calendar button.

Calendar Button

Key Function
Shift + Tab Focuses the input field.
Space Enter Down Arrow Opens calendar to the month and year entered in the input and focuses the corresponding date. If the input field is blank, the calendar opens to the current month and year, and today's date is focused.

Calendar—Date Selection View

Key Function
Enter
  • If a date is in focus, it selects that date, closes the calendar, and focuses the calendar button.
  • If the month-year button is in focus, calendar changes to the month selection view, and the currently selected month is focused.
  • If the previous button is in focus, the calendar view updates to show previous month (in the case of January, the selected year also changes).
  • If the next button is in focus, the calendar view updates to show next month (in the case of December, the year also changes).
Escape
  • Closes the calendar without selecting or changing the date.
  • Focuses the calendar button.
Up Arrow Focuses date in the same column of the row above (same day of previous week). If that date is not in the displayed month, the previous month is brought into view before the date is focused.
Down Arrow Focuses date in the same column of the row below (same day of next week). If that date is not in the displayed month, the next month is brought into view before the date is focused.
Home Focuses first of the month.
End Focuses last date of the month.
Tab Moves focus clockwise from date in focus to previous button, to month-year button, to next button, and back to date.
Shift + Tab Moves focus counter-clockwise from date in focus to next button, to month-year button, to previous button, and back to date.

Calendar—Month Selection View

Key Function
Enter
  • If a month is in focus, it selects the month, calendar changes to the date selection view, and the date last in focus regains focus.
  • If the year button is in focus, calendar changes to the date selection view, and the date last in focus regains focus.
  • If the previous button is in focus, the year goes back by one.
  • If the next button is in focus, the year goes forward by one.
Escape
  • Closes the calendar without selecting or changing the date.
  • Focuses the calendar button.
Up Arrow Focuses month in the same column of the row above. If a month in the top row is focused, focus moves to month in the same column of the bottom row.
Down Arrow Focuses month in the same column of the row below. If the month was in the bottom row, focus moves to month in the same column of the first row.
Home Focuses January.
End Focuses December.
Tab Moves focus clockwise from month in focus to previous button, to year button, to next button, and back to month.
Shift + Tab Moves focus counter-clockwise from month in focus to next button, to year button, to previous button, and back to month.
Back to Top