Form elements - Date input

Use date input to help users enter a date, like their date of birth.

Open this default date input example in new window
Copy default date input code 
<div class="hse-form-group">
  <fieldset class="hse-fieldset" aria-describedby="example-hint" role="group">
    <legend class="hse-fieldset__legend hse-label--l">
      <h1 class="hse-fieldset__heading">
        What is your date of birth?
      </h1>
    </legend>
    <span class="hse-hint" id="example-hint">
      For example, 15 3 1984
    </span>

    <div class="hse-date-input" id="example">
      <div class="hse-date-input__item">
        <div class="hse-form-group">
          <label class="hse-label hse-date-input__label" for="example-day">
            Day
          </label>
          <input class="hse-input hse-date-input__input hse-input--width-2" id="example-day" name="example-day" type="number" pattern="[0-9]*">
        </div>
      </div>
      <div class="hse-date-input__item">
        <div class="hse-form-group">
          <label class="hse-label hse-date-input__label" for="example-month">
            Month
          </label>
          <input class="hse-input hse-date-input__input hse-input--width-2" id="example-month" name="example-month" type="number" pattern="[0-9]*">
        </div>
      </div>
      <div class="hse-date-input__item">
        <div class="hse-form-group">
          <label class="hse-label hse-date-input__label" for="example-year">
            Year
          </label>
          <input class="hse-input hse-date-input__input hse-input--width-4" id="example-year" name="example-year" type="number" pattern="[0-9]*">
        </div>
      </div>
    </div>
  </fieldset>

</div>
Close default date input code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for default date input
Name Type Required Description
Name id Type string Required false Description This is used for the main component and to compose id attribute for each item.
Name namePrefix Type string Required false Description Optional prefix. This is used to prefix each `item.name` using `-`.
Name items Type array Required false Description An array of input objects with name, value and classes.
Name items[].id Type string Required false Description Item-specific id. If provided, it will be used instead of the generated id.
Name items[].name Type string Required true Description Item-specific name attribute.
Name items[].label Type string Required false Description Item-specific label text. If provided, this will be used instead of `name` for item label text.
Name items[].value Type string Required false Description If provided, it will be used as the initial value of the input.
Name hint Type object Required false Description Options for the hint component.
Name errorMessage Type object Required false Description Options for the error message component. The error message component will not display if you use a falsy value for `errorMessage`, for example `false` or `null`.
Name fieldset Type object Required false Description Options for the fieldset component (for example legend).
Name classes Type string Required false Description Classes to add to the date-input container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the date-input container.
Copy default date input code 
{% from 'date-input/macro.njk' import dateInput %}

{{ dateInput({
  "id": "example",
  "namePrefix": "example",
  "fieldset": {
    "legend": {
      "text": "What is your date of birth?",
      "classes": "hse-label--l",
      "isPageHeading": true
    }
  },
  "hint": {
    "text": "For example, 15 3 1984"
  },
  "items": [
    {
      "name": "day",
      "classes": "hse-input--width-2"
    },
    {
      "name": "month",
      "classes": "hse-input--width-2"
    },
    {
      "name": "year",
      "classes": "hse-input--width-4"
    }
  ]
}) }}
Close default date input code

When to use date input

Use date input when you’re asking users for a date they already know.

When not to use date input

Do not use date input if users may not know the exact date you're asking about.

How to use date input

Date input consists of 3 fields to let users enter a day, a month and a year.

Group the 3 date fields together in a <fieldset> with a <legend> that describes them. The legend is usually a question like "What is your date of birth?".

If you are asking just 1 question per page, you can set the contents of the <legend> as the page heading. This is good practice as it means that screen reader users will only hear the contents once.

Error messages

Style error messages like this:

Open this with errors date input example in new window
Copy with errors date input code 
<div class="hse-form-group hse-form-group--error">
  <fieldset class="hse-fieldset" aria-describedby="dob-errors-hint dob-errors-error" role="group">
    <legend class="hse-fieldset__legend hse-label--l">
      <h1 class="hse-fieldset__heading">
        What is your date of birth?
      </h1>
    </legend>
    <span class="hse-hint" id="dob-errors-hint">
      For example, 15 3 1984
    </span>

    <span class="hse-error-message" id="dob-errors-error">
      <span class="hse-u-visually-hidden">Error:</span> Enter your date of birth
    </span>

    <div class="hse-date-input" id="dob-errors">
      <div class="hse-date-input__item">
        <div class="hse-form-group">
          <label class="hse-label hse-date-input__label" for="dob-errors-day">
            Day
          </label>
          <input class="hse-input hse-date-input__input hse-input--width-2 hse-input--error" id="dob-errors-day" name="day" type="number" pattern="[0-9]*">
        </div>
      </div>
      <div class="hse-date-input__item">
        <div class="hse-form-group">
          <label class="hse-label hse-date-input__label" for="dob-errors-month">
            Month
          </label>
          <input class="hse-input hse-date-input__input hse-input--width-2 hse-input--error" id="dob-errors-month" name="month" type="number" pattern="[0-9]*">
        </div>
      </div>
      <div class="hse-date-input__item">
        <div class="hse-form-group">
          <label class="hse-label hse-date-input__label" for="dob-errors-year">
            Year
          </label>
          <input class="hse-input hse-date-input__input hse-input--width-4 hse-input--error" id="dob-errors-year" name="year" type="number" pattern="[0-9]*">
        </div>
      </div>
    </div>
  </fieldset>

</div>
Close with errors date input code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for with errors date input
Name Type Required Description
Name id Type string Required false Description This is used for the main component and to compose id attribute for each item.
Name namePrefix Type string Required false Description Optional prefix. This is used to prefix each `item.name` using `-`.
Name items Type array Required false Description An array of input objects with name, value and classes.
Name items[].id Type string Required false Description Item-specific id. If provided, it will be used instead of the generated id.
Name items[].name Type string Required true Description Item-specific name attribute.
Name items[].label Type string Required false Description Item-specific label text. If provided, this will be used instead of `name` for item label text.
Name items[].value Type string Required false Description If provided, it will be used as the initial value of the input.
Name hint Type object Required false Description Options for the hint component.
Name errorMessage Type object Required false Description Options for the error message component. The error message component will not display if you use a falsy value for `errorMessage`, for example `false` or `null`.
Name fieldset Type object Required false Description Options for the fieldset component (for example legend).
Name classes Type string Required false Description Classes to add to the date-input container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the date-input container.
Copy with errors date input code 
{% from 'date-input/macro.njk' import dateInput %}

{{ dateInput({
  "id": "dob-errors",
  "fieldset": {
    "legend": {
      "text": "What is your date of birth?",
      "classes": "hse-label--l",
      "isPageHeading": true
    }
  },
  "hint": {
    "text": "For example, 15 3 1984"
  },
  "errorMessage": {
    "text": "Enter your date of birth"
  },
  "items": [
    {
      "name": "day",
      "classes": "hse-input--width-2 hse-input--error"
    },
    {
      "name": "month",
      "classes": "hse-input--width-2 hse-input--error"
    },
    {
      "name": "year",
      "classes": "hse-input--width-4 hse-input--error"
    }
  ]
}) }}
Close with errors date input code

Research

The date input is based on the component in the GOV.UK design system.

Date input - design-system.service.gov.uk.

GOV.UK says that they need to do more research to understand if users struggle to enter months as numbers and whether it's more helpful to let them enter months as text.

They say that they need to do more research to understand:

  • if users struggle to enter months as numbers
  • whether it's more helpful to let them enter months as text

Updated: September 2023