Form elements - Date input

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

Open this default date input example in a new tab
Copy default date input code 
<div class="nhsuk-form-group">

  <fieldset class="nhsuk-fieldset" aria-describedby="example-hint" role="group">
    <legend class="nhsuk-fieldset__legend nhsuk-label--l">
      <h1 class="nhsuk-fieldset__heading">
        What is your date of birth?
      </h1>
    </legend>
    <div class="nhsuk-hint" id="example-hint">
      For example, 15 3 1984
    </div>

    <div class="nhsuk-date-input" id="example">
      <div class="nhsuk-date-input__item">
        <div class="nhsuk-form-group">
          <label class="nhsuk-label nhsuk-date-input__label" for="example-day">
            Day
          </label>
          <input class="nhsuk-input nhsuk-date-input__input nhsuk-input--width-2" id="example-day" name="example[day]" type="text" inputmode="numeric">
        </div>
      </div>
      <div class="nhsuk-date-input__item">
        <div class="nhsuk-form-group">
          <label class="nhsuk-label nhsuk-date-input__label" for="example-month">
            Month
          </label>
          <input class="nhsuk-input nhsuk-date-input__input nhsuk-input--width-2" id="example-month" name="example[month]" type="text" inputmode="numeric">
        </div>
      </div>
      <div class="nhsuk-date-input__item">
        <div class="nhsuk-form-group">
          <label class="nhsuk-label nhsuk-date-input__label" for="example-year">
            Year
          </label>
          <input class="nhsuk-input nhsuk-date-input__input nhsuk-input--width-4" id="example-year" name="example[year]" type="text" inputmode="numeric">
        </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
id string false This is used for the main component and to compose id attribute for each item.
namePrefix string false Optional prefix. This is used to prefix each `item.name` using `-`.
items array false An array of input objects with name, value and classes.
items[].id string false Item-specific id. If provided, it will be used instead of the generated id.
items[].name string true Item-specific name attribute.
items[].label string false Item-specific label text. If provided, this will be used instead of `name` for item label text.
items[].value string false If provided, it will be used as the initial value of the input.
hint object false Options for the hint component.
errorMessage object false 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`.
fieldset object false Options for the fieldset component (for example legend).
classes string false Classes to add to the date-input container.
attributes object false HTML attributes (for example data attributes) to add to the date-input container.
values object false An optional object use to specify value attributes for the date parts without setting rows.
values.day string false Value attribute for the day input.
values.month string false Value attribute for the month input.
values.year string false Value attribute for the year input.
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: "nhsuk-label--l",
      isPageHeading: true
    }
  },
  hint: {
    text: "For example, 15 3 1984"
  },
  items: [
    {
      name: "day",
      classes: "nhsuk-input--width-2"
    },
    {
      name: "month",
      classes: "nhsuk-input--width-2"
    },
    {
      name: "year",
      classes: "nhsuk-input--width-4"
    }
  ]
}) }}
Close default date input code

When to use date input

We follow the GOV.UK Design System. 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 are unlikely to 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, month and year.

Group the 3 date fields together in a <fieldset> with a <legend> that describes them. You can see an example at the top of this page. The legend is usually a question, like "What is your date of birth?".

If you are asking just 1 question per page as we recommend, 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.

Read more on the GOV.UK Design System about how to ask users for dates and making labels and legends headings.

Error messages

Style error messages like this:

Open this with errors date input example in a new tab
Copy with errors date input code 
<div class="nhsuk-form-group nhsuk-form-group--error">

  <fieldset class="nhsuk-fieldset" aria-describedby="dob-errors-hint dob-errors-error" role="group">
    <legend class="nhsuk-fieldset__legend nhsuk-label--l">
      <h1 class="nhsuk-fieldset__heading">
        What is your date of birth?
      </h1>
    </legend>
    <div class="nhsuk-hint" id="dob-errors-hint">
      For example, 15 3 1984
    </div>

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

    <div class="nhsuk-date-input" id="dob-errors">
      <div class="nhsuk-date-input__item">
        <div class="nhsuk-form-group">
          <label class="nhsuk-label nhsuk-date-input__label" for="dob-errors-day">
            Day
          </label>
          <input class="nhsuk-input nhsuk-date-input__input nhsuk-input--width-2 nhsuk-input--error" id="dob-errors-day" name="day" type="text" inputmode="numeric">
        </div>
      </div>
      <div class="nhsuk-date-input__item">
        <div class="nhsuk-form-group">
          <label class="nhsuk-label nhsuk-date-input__label" for="dob-errors-month">
            Month
          </label>
          <input class="nhsuk-input nhsuk-date-input__input nhsuk-input--width-2 nhsuk-input--error" id="dob-errors-month" name="month" type="text" inputmode="numeric">
        </div>
      </div>
      <div class="nhsuk-date-input__item">
        <div class="nhsuk-form-group">
          <label class="nhsuk-label nhsuk-date-input__label" for="dob-errors-year">
            Year
          </label>
          <input class="nhsuk-input nhsuk-date-input__input nhsuk-input--width-4 nhsuk-input--error" id="dob-errors-year" name="year" type="text" inputmode="numeric">
        </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
id string false This is used for the main component and to compose id attribute for each item.
namePrefix string false Optional prefix. This is used to prefix each `item.name` using `-`.
items array false An array of input objects with name, value and classes.
items[].id string false Item-specific id. If provided, it will be used instead of the generated id.
items[].name string true Item-specific name attribute.
items[].label string false Item-specific label text. If provided, this will be used instead of `name` for item label text.
items[].value string false If provided, it will be used as the initial value of the input.
hint object false Options for the hint component.
errorMessage object false 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`.
fieldset object false Options for the fieldset component (for example legend).
classes string false Classes to add to the date-input container.
attributes object false HTML attributes (for example data attributes) to add to the date-input container.
values object false An optional object use to specify value attributes for the date parts without setting rows.
values.day string false Value attribute for the day input.
values.month string false Value attribute for the month input.
values.year string false Value attribute for the year input.
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: "nhsuk-label--l",
      isPageHeading: true
    }
  },
  hint: {
    text: "For example, 15 3 1984"
  },
  errorMessage: {
    text: "Enter your date of birth"
  },
  items: [
    {
      name: "day",
      classes: "nhsuk-input--width-2 nhsuk-input--error"
    },
    {
      name: "month",
      classes: "nhsuk-input--width-2 nhsuk-input--error"
    },
    {
      name: "year",
      classes: "nhsuk-input--width-4 nhsuk-input--error"
    }
  ]
}) }}
Close with errors date input code

Follow:

Research

Our date input is based on the component in the GOV.UK Design System. 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.

If you've used this component, get in touch to share your user research findings.

Help us improve this guidance

Share insights or feedback and take part in the discussion. We use GitHub as a collaboration space. All the information on it is open to the public.

Feedback or share insights on GitHub

Read more about how to feedback or share insights.

If you have any questions, get in touch with the service manual team.

Updated: June 2021