Date picker

<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" name="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. Users can select a specific date from a calendar. The date picker works with keyboard, mouse or touch screen.

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.

Being able to choose a date from a calendar 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. You can disable individual dates.

In this example, a latest date of 28th May 2023 has been set and two days in May 2023 are not available.

<div data-maxdate="28/05/2023" data-disableddates="18/05/2023 19/05/2023" 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" name="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. 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" name="day" class="ds_input ds_input--fixed-2  js-datepicker-date">
            </div>
            <div>
                <label class="ds_label" for="month">Month</label>
                <input id="month" name="month" class="ds_input ds_input--fixed-2  js-datepicker-month">
            </div>
            <div>
                <label class="ds_label" for="year">Year</label>
                <input id="year" name="year" class="ds_input ds_input--fixed-4  js-datepicker-year">
            </div>
        </div>
    </div>
</fieldset>

Website analytics

To understand user behaviour, you can track clicks on date picker items through the original page path, the click text, and a data attribute showing the element interacted with.

You can track clicks on buttons inside a date picker using the standard Button tracking.

The Design System’s ‘tracking’ script adds these data attributes.

Accessibility

The date picker’s calendar dialog has an ARIA role of ‘grid’ to give semantic meaning to its content. This helps users of assistive technology understand how to interact with the component.

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. The default is DMY.

This is how each format would show the date 14th March 2020:

• DMY - 14/03/2020
• MDY - 03/14/2020
• YMD - 2020/03/14

The values for data-mindate, data-maxdate and data-disableddates all use this date format.

Allowed date ranges

Use an attribute of data-mindate to specify the earliest possible date for the calendar. Users can not select dates before this date.

Use an attribute of data-maxdate to specify the latest possible date for the calendar. Users can not select dates before this date.

These attributes should be set on the date picker element. 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. These dates should be 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 called when a user selects a date from the date picker. It expects a ‘date’ parameter, which is a JavaScript date object.
• disabledDates: an array of dates to disable 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

Dates that have been set using JavaScript will override values for these dates that you have set using data attributes.

Example JavaScript

const datePicker = new window.DS.components.DSDatePicker(
    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();

Live example

Create a tenancy agreement (mygov.scot)