Date picker

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

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

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

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

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

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 picker
• imagePath: the path to the location of your icons sprite. Default is /assets/images/icons/
• maxDate: a JavaScript date object for the latest selectable date
• minDate: 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();