Date picker
Date pickers help a user to input a date into a form.
Sample HTML
<div data-module="ds-datepicker" class="ds_datepicker">
<label class="ds_label" for="start-date">Start date</label>
<div class="ds_input__wrapper">
<input id="start-date" data-maxdate="19/09/2020" data-mindate="09/08/2020" placeholder="dd/mm/yyyy" type="text" class="ds_input ds_input--fixed-10" />
</div>
</div>
Developer notes
Date formats
Use an attribute of data-dateformat
on the input element to specify one of the following. If none is provided it defaults to DMY
.
DMY
- 14th March 2020 would be written as14/03/2020
MDY
- 14th March 2020 would be written as03/14/2020
YMD
- 14th March 2020 would be written as2020/03/14
Allowed date ranges
Use an attribute of data-mindate
on the input element to specify an earliest possible date for the calendar. Dates before this date cannot be selected.
Use an attribute of data-maxdate
on the input element to specify a latest possible date for the calendar. Dates after this date cannot be selected.
The date format used for both of these is whatever you specify in data-dateformat
or the default, DMY
.
About this component
The date picker is a component that helps users to complete date input fields. To help with accessibility, it can be used with a keyboard, as well as mouse or touchscreen.
The date picker can be set with limits on the dates that users can select.
The date picker component can use a variety of date formats, with the UK style of date-month-year used by default.
Why we use this component
Date pickers are a common component that helps users select and enter a date.
Website analytics
To understand user behaviour, clicks on date picker items can be tracked through the original page path, the click text, and a data attribute showing the element interacted with.
Clicks on buttons inside a date picker, including ‘OK’, ‘Cancel’ and the month navigation buttons are tracked using the standard Button tracking. Data attributes for these are added automatically by the Design System’s ‘tracking’ script.
Accessibility
Keyboard support
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 | Escape |
Closes the date picker and focuses on the calendar button. |
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 | 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. |
Feedback, help or support
If you need any help or want to give any feedback you can e-mail us at: designsystem@gov.scot