Designsystem.gov.scot uses cookies which are essential for the site to work. We also use non-essential cookies to help us improve our websites. Any data collected is anonymised. By continuing to use this site, you agree to our use of cookies.

Cookie settings

Your cookie settings have been saved.

Component

Date picker

Date pickers help a user to input a date into a form.

Open this example in a new window

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" 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 as 14/03/2020
  • MDY - 14th March 2020 would be written as 03/14/2020
  • YMD - 14th March 2020 would be written as 2020/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.

Open this example in a new window

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>

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, for example data-form="date-select". Submits are tracked using the Button pattern, for example data-button="button-datepicker-ok".

Accessibility features

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

Back to top