Use a date picker to let users pick a date from a calendar
A date picker simplifies the process of entering dates by providing a visual calendar interface helping users to understand a date’s relationship to other days, such as the day of the week or how far away a date is from today.
The date picker is a progressive enhancement to text inputs that lets users choose a date from a calendar interface or enter the date as text. To help with accessibility, it can be used with a keyboard, as well as mouse or touchscreen.
Do:
Use a date picker:
Don't use a date picker:
The date picker component relies on JavaScript so should be treated as an enhancement. Users should always be able to enter the date into a text field as well as use the control.
Users select dates from a visual representation of the month and can skip through months and years. This allows them to easily see what day of the week and week of the month a particular date is in, which is particularly useful for tasks like appointment booking.
The Date Picker component comes with the following customizations:
By default, the calendar widget shows the full English name of the months; if you wish to change this default (e.g., passing a short version of the label or using a different language), add a data-months attribute to the .nsw-date-input element with the comma-separated list of the labels you want to use:
By default, the date format of the text input field is 'dd/mm/yyyy'; if you want to change this order (e.g., yyyy/mm/dd), add a data-date-format attribute to the .nsw-date-input element with the new order you want to use:
By default, the slash ('/') is used as date separator; if you want to use a different character (e.g., '-'), add a data-date-separator attribute to the .nsw-date-input element:
If you want to prefill your Date Picker component with a date, use the .js-date-input__text
input element and set its value
equal to the date you want to use. Make sure to use the date format you specify in data-date-format or the default, d-m-y.
Allowed date ranges for a date picker can be set by specifying earliest and latest allowed dates. Individual dates can also be disabled.
If you want to specify an earliest possible date for the calendar, add a data-min-date attribute to the .nsw-date-input element:
If you want to specify a latest possible date for the calendar, add a data-max-date attribute to the .nsw-date-input element:
Use an attribute of data-dates-disabled to specify a list of dates that the user will not be able to select.
The value of this attribute should be a space-separated list of dates in the format you specify in data-date-format or the default, d-m-y.
All components are responsive and meet WCAG 2.1 AA accessibility guidelines.
The dialog contains a calendar that uses the grid pattern to present buttons that enable the user to choose a day from the calendar. Choosing a date from the calendar closes the dialog and populates the date input field. When the dialog is opened, if the input field is empty, or does not contain a valid date, then the current date is focused in the calendar. Otherwise, the focus is placed on the day in the calendar that matches the value of the date input field.
Users can navigate the calendar by using the cursor keys to move around the calendar, and can use the enter key or spacebar to select a date.
The following table lists the keyboard commands that the date picker supports.
Element | Key | Action |
---|---|---|
Calendar button | Space ,Enter
|
Opens the date picker. If there is a current date set in the text input, that date is focussed in the date picker. If not, today's date is focussed. |
Date picker | Tab |
Moves focus to the next element in the tab order. If tabbing away from the last focusable element in the tab order, moves focus to the first focusable element in the date picker. |
Date picker | Shift + Tab |
Moves focus to the previous element in the tab order. If tabbing away from the first focusable element in the tab order, moves focus to the last focusable element in the date picker. |
Month and year buttons | Space ,Enter
|
Change the current month or year displayed in the date picker. |
Dates | Space ,Enter
|
Selects the focussed date, closes the date picker and moves focus back to the calendar button. Updates the accessible name of the calendar button to indicate the selected date. |
Dates | Up |
Moves focus to the same day of the previous week, changing the displayed month if necessary. |
Dates | Down |
Moves focus to the same day of the next week, changing the displayed month if necessary. |
Dates | Left |
Moves focus to the previous day, changing the displayed month if necessary. |
Dates | Right |
Moves focus to the next day, changing the displayed month if necessary. |
Dates | Home |
Moves focus to the first day of the current week. |
Dates | End |
Moves focus to the last day of the current week. |
Dates | Page Up |
Shows the previous month and focuses on the same day of the month. |
Dates | Shift + Page Up |
Shows same month in the previous year and focuses on the same day of the month. |
Dates | Page Down |
Shows the next month and focuses on the same day of the month. |
Dates | Shift + Page Down |
Shows same month in the next year and focuses on the same day of the month. |
Cancel button | Space ,Enter
|
Closes the date picker and makes no change to the date in the text input. Focus is returned to the calendar button. |
OK button | Space ,Enter
|
Closes the date picker and updates the date in the text input with the chosen date in the date picker. Focus is returned to the calendar button. |
Allowed date ranges for a date picker can be set by specifying earliest and latest allowed dates. Individual dates can also be disabled.
In this example, a max date of 28 January 2024, a min date of 02 January 2024 has been set and three days in January 2024 have been disabled.