A NSW Government website
NSW Government
Design System v3.16.0

Date picker

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

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 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.

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 windowView theming example
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.

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