Date picker

Use a date picker to let users pick a date from a calendar

Guidance
Demo & Code

Usage

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:

display the date format above the text input
ensure users can enter dates via the calendar or text input
disable dates that aren’t available

When to use

Use a date picker:

when the date options are relatively close to the present day.
when users need to know the day of the week, or the week of the month, as well as the date.
when knowing the day of the week helps users choose a specific date.

When to avoid

Don't use a date picker:

when the user needs to select a set date that they know, like their birthday — use date input instead
when having a calendar is not likely to help the user - such as a date several years in the past
when screen size is limited, a full calendar view might not be practical.

How this component works

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:

Month labels

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:

Date format

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:

Date separator

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:

Preselected date

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.

Date ranges and disabled dates

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.

Accessibility

All components are responsive and designed to comply with WCAG 2.2 AA accessibility standards. Full compliance depends on using and configuring the components correctly.

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.

Ensuring compliance through usage

Redundant entry

To ensure WCAG 2.2 AA compliance for a date picker, correct usage and configuration are key. While the component offers an accessible foundation, it's important to minimise redundant input by retaining previously selected dates if users return to the form. Ensure that keyboard navigation is fully functional, and provide clear labels and instructions for selecting dates. If errors occur, users should be able to correct them without needing to re-select the date.

Following these usage practices supports an inclusive experience that meets accessibility standards.

Keyboard support

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.

View in new window View theming example

Select date Use dd/mm/yyyy format. For example 28 10 2024

Date ranges and disabled dates

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.

Select date Use dd/mm/yyyy format. For example 28 10 2024

Individual date inputs for day, month and year

Start date For example 28 10 2024

Day

Month

Year