Components / Library version 3.26.0

Datepicker

The datepicker allows users to type in a date or select a date from a calendar. The component parses the date into ISO format and exposes it through its value property, just like the native input. It has built-in date validations and will display an error if the user types a date that does not exist or that is in the wrong format. The component can also display a customized error message if the date fails an external validation performed by the app. See the Notes tab for more information.

Properties Examples Events Accessibility Notes

* Required property

label *
string
A description for the input. Required even if the label-position is set to none (for accessibility reasons).
date-format
US | INT | ISO
Determines how the date will be displayed for the user. The component will validate the date according to this format, i.e., if the date-format is US and the user enters 20/1/2020, the component will display an error message prompting the user to correct the date. Defaults to US.
US: mm/dd/yyyy
INT: dd/mm/yyyy
ISO: yyyy/mm/dd
disabled
boolean
Disables the datepicker.
error-message
string
The message to display if the user input fails a validation performed by the app.
invalid
boolean
Readonly. An indicator for when the current user input fails validation or an error is present.
label-position
top | left | none
Defaults to top. Set this property to none if no label should be displayed.
prevent-validation
string
Validation will not occur when clicking on an element with this id. Accepts multiple ids separated by spaces. See Notes tab for more information.
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.
required-field-message
string
The message to display when an error is displayed due to the field being left empty. If not set, this message will be: "A date is required."
value
string
The date to initially display in the input. The value attribute will be updated when the user enters or selects a date, just like any native input. The component expects the value to be in ISO format and will update it in ISO format. If no value is initially set or an empty string is passed, the input will display the date format as a placeholder in the input (as mm/dd/yyyy, dd/mm/yyyy, or yyyy/mm/dd, depending on the value of date-format).

Usage in HTML

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

Usage in Elm

Code generated from HTML.
wmDatepickerNewValidValue
Emitted when the Datepicker's value changes and is valid.
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.
  • This datepicker can account for scenarios where not all dates are valid. When a range of dates is invalid, they can still be manually selected in the picker or entered in the input field. The component will notify the user of an invalid format or invalid date with a custom error upon field validation. As per Watermark guidelines, this component does not disable invalid dates because users do not know why elements can be disabled and can assume there is a way to enable them.
  • The prevent-validation prop is used with a specific use-case in mind. When components that feature required fields are initally focused within a modal, closing the modal will flash the required error. The prevent-validation prop is useful in this case, where the close button's id can be passed through preventing the validation flash.

In a compound component like Select or Action Menu, child components are rendered in the parent's slot element, part of its shadow DOM tree. Slots essentially serve as a placeholder for markup that you the developer define in the light DOM tree, like <wm-menuitem>, <wm-option>, text content, or other child elements.

The browser distributes the child elements defined in the light DOM into the shadow DOM of the parent. The result is a flattened DOM tree—a merger of the the light DOM and the shadow DOM. This flattened tree is what you see in DevTools and what is rendered on the page.

With the standard implementation of the component, dynamically updating the child items will throw an error. Elm's efficient diffing of the DOM will register that only the child items have changed and try to update them, but the component has already been composed.

Rendering the component in a Keyed node and giving it a dynamic id will cause the entire component, rather than just the child items, to render anew, avoiding the error.