Date pickerStatusdevelopment

Help users enter a date into a form with a calendar interface using the Scottish Government Design System date picker.

Guidance

This pattern progressively enhances a text input that a user can enter a date into by adding a selectable calendar interface. The date picker pattern is suitable for date fields that require a user to:

pick a date in the near future or recent past
know the exact day of the week, or week of the month, in addition to the date
see dates in relation to other dates
select a date constrained by range

This pattern is not recommended for memorable dates (e.g. date of birth), dates from documents or cards (e.g. passport or credit card), or for approximate or partial dates (e.g. January 1970), or relative dates (e.g. 2 days ago). For these kinds of date fields consider the GOV.UK Design System date input, or a simple text field.

Full documentation of all options for the date picker component, including date ranges, min and max dates, and disabling dates is available on the Scottish Government Design System website.

Example

Open in a new tab

Code

<form class="form" novalidate><div class="ds_datepicker js-date-picker"><label class="label" for="date">Start date<span class="label__hint">Use dd/mm/yyyy format. For example, 31/01/2023.</span></label><div class="ds_input__wrapper"><input id="date" name="date" class="input"/></div></div></form>

import DSDatePicker from '@scottish-government/pattern-library/src/components/date-picker/date-picker';

const datepicker = new DSDatePicker(document.querySelector('.js-date-picker'), { imagePath: '/static/img/' });
datepicker.init();

Three input example

Open in a new tab

Code

<form class="form" novalidate><fieldset><legend class="legend">Start date<span class="legend__hint">For example, 31 01 2023</span></legend><div class="ds_datepicker ds_datepicker--multiple js-date-picker" data-module="ds-datepicker"><div class="ds_datepicker__input-wrapper"><div><label class="label" for="day">Day</label><input id="day" name="day" class="input ds_input ds_input--day js-datepicker-date"/></div><div><label class="label" for="month">Month</label><input id="month" name="month" class="input ds_input ds_input--month js-datepicker-month"/></div><div><label class="label" for="year">Year</label><input id="year" name="year" class="input ds_input ds_input--year js-datepicker-year"/></div></div></div></fieldset></form>

import DSDatePicker from '@scottish-government/pattern-library/src/components/date-picker/date-picker';

const datepicker = new DSDatePicker(document.querySelector('.js-date-picker'), { imagePath: '/static/img/' });
datepicker.init();

Dependencies and installation

Package	Installation
@scottish-government/pattern-library	`npm i -S @scottish-government/pattern-library`

Acceptance criteria

The following is a list of example acceptance criteria to test against when using this pattern. These critera should test that the specific markup requirements are met, and that the date picker behave visually and functionally as expected.

For validation in developer tools / web inspector

The text
```
<input>
```
element must have a matching
```
<label>
```
element or
```
aria-label
```
All buttons should use an HTML
```
<button>
```
element
Each day in the calendar should have an accessible label describing the full date

For visual validation

The text
```
<input>
```
element should have a clearly visible focus style which meets accessibility contrast requirements
The date format expected by the text input should be described in the label
Buttons should have a clearly visible focus style which meets accessibility contrast requirements
Buttons should be appropriately labelled to describe their functionality. If the design requires no visible text, the button should contain a hidden label or an
```
aria-label
```
attribute

For functional validation

The input must allow the user to enter a date manually without using the calendar interface
The user must not be able to interact with the calendar unless they open it
The calendar interface should be reachable and operable using the keyboard only
Focus should move to the selected date or current date if none selected when the calendar opens
The current date, selected date, and focused date should be visually distinguishable from each other
Space/enter keys should select the focused date, close calendar, focus back on the calendar button, and update the accessible name of the button to indicate the date
Left/right keys should navigate previous/next days
Up/down keys should navigate to the same day in the previous/next week
it should be possible to close the calendar without selecting a date

UI Patterns

Date pickerStatusdevelopment

Guidance

Example

Code

Three input example

Code

Dependencies and installation

Acceptance criteria

For validation in developer tools / web inspector

For visual validation

For functional validation

References