GOV.UK React Date Picker User Guide

The GOV.UK Design System is an official design framework produced by the UK Government and defines best practices and rules that must be followed to ensure that your code base is GDS Compliant.

You can find the guide at the GOV.UK Design System website.

Overview

The standard implementation for the GDS Date input uses three separate controls for day, month and year. User feedback indicated that this control did not support fast data entry due to the tabbing required between the components.

Standard HTML5 date inputs provided fast data entry on desktop but the locale of the control is determined by the browser and additionally the control renders differently across different browsers, on mobile devices. Android and IOS now display calendars on a control touch, which did not allow easy entry of historic dates, which was often required by users.

The remit was to develop a react based date picker that would enable keyboard data entry similar to how the HTML5 control works on desktop, for both desktop and mobile, and also include an accessible calendar component that could be activated by the user.

The calendar part of this control has been implemented from the Scottish Government Date Picker, converting the original Javascript to React. The resulting component is shown below:

A working (Demo) can be found under the dates menu option, highlighting the differences between standard HTML5 date controls and the date picker implementation.

Configuration

The below shows one of our example implementations of the date picker integrated with React Hook Form:

<Controller
  control={control}
  name="datePicker"
  render={({ field: { value, onBlur, onChange }, fieldState: { error } }) => (
    <DatePicker
      identifier="datePicker"
      label="When was your passport issued?"
      hint="For example, 27/03/2007"
      width={InputWidth.Char10}
      multiQuestion={true}
      value={value}
      error={error?.message}
      onChange={x => onChange(x)}
      onBlur={onBlur}
    />
  )}
/>

Installation

The package can be installed via npm:

npm install react-govuk-datepicker --save

Or via yarn:

yarn add react-govuk-datepicker

The date picker uses GDS styles which can be installed via the govuk-frontend package:

npm install govuk-frontend --save
yarn add govuk-frontend

Accessibility

Keyboard support for Input

• Left: Move to the previous date part section e.g.: move from month to day.
• Right: Move to the next date part section e.g.: move from day to month.
• Up: Increment the currently selected date part section.
• Down: Decrement the currently selected date part section.

Keyboard support for Calendar

• Left: Move to the previous day.
• Right: Move to the next day.
• Up: Move to the previous week.
• Down: Move to the next week.
• PgUp: Move to the previous month.
• Shift+PgUp: Move to the same day and month of the previous year
• PgDn: Move to the next month.
• Shift+PgDn: Move to the same day and month of the next year
• Home: Move to the first day of the current week.
• End: Move to the last day of the current week.

License

Copyright (c) 2024 Barry Jacobs and individual contributors. Licensed under MIT license, see LICENSE for the full license.