Date picker
Date pickers help a user to enter 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>
<p class="ds_hint-text">Use dd/mm/yyyy format. For example, 31/01/2023.</p>
<div class="ds_input__wrapper">
<input id="start-date" type="text" class="ds_input ds_input--fixed-10" />
</div>
</div>
About this component
The date picker is a component that helps users to complete date input fields by selecting a specific date from a calendar. To help with accessibility, it can be used with a keyboard, as well as mouse or touchscreen.
Why we use this component
The date picker is a progressive enhancement to text inputs that lets users choose a date from a calendar interface. This can be helpful when the day of the week is important to the choice of date.
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 latest date of 28th May 2023 has been set and two days in May 2023 have been disabled.
Sample HTML
<div data-module="ds-datepicker" class="ds_datepicker" data-disableddates="17/05/2023 18/05/2023" data-maxdate="28/05/2023" data-mindate="11/08/2020">
<label class="ds_label" for="start-date">Start date</label>
<p class="ds_hint-text">Use dd/mm/yyyy format. For example, 31/01/2023.</p>
<div class="ds_input__wrapper">
<input id="start-date" type="text" class="ds_input ds_input--fixed-10" />
</div>
</div>
These options can be set either with data attributes or in JavaScript. See the implementation section of this page for instructions.
Individual date inputs for day, month and year
By default, a date picker uses a single text input for the date. However, you can also use separate text fields for each part of the date if you prefer.
Sample HTML
<fieldset>
<legend>What is your date of birth?</legend>
<p class="ds_hint-text">For example, 31 3 1980</p>
<div class="ds_datepicker ds_datepicker--multiple" data-module="ds-datepicker">
<div class="ds_datepicker__input-wrapper">
<div>
<label class="ds_label" for="day">Day</label>
<input id="day" class="ds_input ds_input--fixed-2 js-datepicker-date" />
</div>
<div>
<label class="ds_label" for="month">Month</label>
<input id="month" class="ds_input ds_input--fixed-2 js-datepicker-month" />
</div>
<div>
<label class="ds_label" for="year">Year</label>
<input id="year" class="ds_input ds_input--fixed-4 js-datepicker-year" />
</div>
</div>
</div>
</fieldset>
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
The date picker’s calendar dialog has an ARIA role of ‘grid’ to give semantic meaning to its content. This helps screen readers and other assistive technology to present and support interaction in a way that users will expect.
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. |
Implementation
The date picker component needs JavaScript enabled in the user’s browser. If a user does not have JavaScript enabled the text field will behave as normal, without the date picker enhancements.
Date formats
The date picker component can use a variety of date formats, with the UK style of date/month/year used by default.
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
This date format is used for the values provided as data-mindate
, data-maxdate
, and data-disableddates
.
Allowed date ranges
Use an attribute of data-mindate
on the date picker 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 date picker 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 what you specify in data-dateformat
or the default, DMY
.
Disabled dates
Use an attribute of data-disableddates
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-dateformat
or the default, DMY
.
JavaScript
Set up a date picker by creating a new DatePicker object. It takes two parameters:
- the DOM element of the date picker (element with class
ds_datepicker
) - an optional object of customisation settings
The customisation settings can have the following properties:
dateSelectCallback
: an optional function that will be called when a date is selected from the date picker. It expects a ‘date’ parameter, which is a JavaScript date object.disabledDates
: an array of dates that will be disabled in the date pickerimagePath
: the path to the location of your icons sprite. Default is/assets/images/icons/
maxDate
: a JavaScript date object for the latest selectable dateminDate
: a JavaScript date object for the earliest selectable date
Example JavaScript
const datePicker = new window.DS.components.DatePicker(
document.getElementById('my-date-picker'),
{
dateSelectCallback: function (date) {
console.log(`the selected date is ${date}`);
},
disabledDates: [
new Date(2023, 4, 12),
new Date(2023, 4, 13)
],
imagePath: '/my/image/path/',
maxDate: new Date(),
minDate: new Date(2019, 1, 1)
}
);
datePicker.init();
Feedback, help or support
If you need any help or want to give any feedback you can e-mail us at: designsystem@gov.scot