Components

Date input

Use the date input component to help users enter a memorable date.

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset" aria-describedby="dob-hint" role="group">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--xl">
      <h1 class="govuk-fieldset__heading">
        What is your date of birth?
      </h1>
    </legend>
    <span id="dob-hint" class="govuk-hint">
      For example, 31 3 1980
    </span>
    <div class="govuk-date-input" id="dob">

      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="dob-day">
            Day
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-2 " id="dob-day" name="dob-day" type="number" pattern="[0-9]*">
        </div>
      </div>

      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="dob-month">
            Month
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-2 " id="dob-month" name="dob-month" type="number" pattern="[0-9]*">
        </div>
      </div>

      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="dob-year">
            Year
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-4 " id="dob-year" name="dob-year" type="number" pattern="[0-9]*">
        </div>
      </div>
    </div>
  </fieldset>
</div>
{% from "date-input/macro.njk" import govukDateInput %}

{{ govukDateInput({
  id: "dob",
  name: "dob",
  fieldset: {
    legend: {
      text: "What is your date of birth?",
      isPageHeading: true,
      classes: "govuk-fieldset__legend--xl"
    }
  },
  hint: {
    text: "For example, 31 3 1980"
  },
  items: [
    {
      name: "day"
    },
    {
      name: "month"
    },
    {
      name: "year"
    }
  ]
}) }}

You can configure this component using the Nunjucks macro arguments.

When to use this component

Use the date input component when you’re asking users for a date they’ll already know, or can look up without using a calendar.

When not to use this component

Don’t use the date input component if users are unlikely to know the exact date of the event you’re asking about.

Read more about how to ask users for dates.

How it works

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

The 3 date fields are grouped together in a <fieldset> with a <legend> that describes them, as shown in the examples on this page. This is usually a question, like ‘What is your date of birth?’.

If you’re asking one question per page, you can set the contents of the <legend> as the page heading. This is good practice as it means that users of screen readers will only hear the contents once.

Read more about why and how to set legends as headings.

There are 2 ways to use the date input component. You can use HTML or, if you’re using Nunjucks or the GOV.UK Prototype Kit, you can use the Nunjucks macro.

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset" aria-describedby="dob-hint" role="group">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--xl">
      <h1 class="govuk-fieldset__heading">
        What is your date of birth?
      </h1>
    </legend>
    <span id="dob-hint" class="govuk-hint">
      For example, 31 3 1980
    </span>
    <div class="govuk-date-input" id="dob">

      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="dob-day">
            Day
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-2 " id="dob-day" name="dob-day" type="number" pattern="[0-9]*">
        </div>
      </div>

      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="dob-month">
            Month
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-2 " id="dob-month" name="dob-month" type="number" pattern="[0-9]*">
        </div>
      </div>

      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="dob-year">
            Year
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-4 " id="dob-year" name="dob-year" type="number" pattern="[0-9]*">
        </div>
      </div>
    </div>
  </fieldset>
</div>
{% from "date-input/macro.njk" import govukDateInput %}

{{ govukDateInput({
  id: "dob",
  name: "dob",
  fieldset: {
    legend: {
      text: "What is your date of birth?",
      isPageHeading: true,
      classes: "govuk-fieldset__legend--xl"
    }
  },
  hint: {
    text: "For example, 31 3 1980"
  },
  items: [
    {
      name: "day"
    },
    {
      name: "month"
    },
    {
      name: "year"
    }
  ]
}) }}

You can configure this component using the Nunjucks macro arguments.

Don’t automatically tab users between the fields of the Date input because this can be confusing and may clash with normal keyboard controls.

Error states

Check that a valid date is entered by the user. Invalid dates should be reported to the user like this:

<div class="govuk-form-group govuk-form-group--error">
  <fieldset class="govuk-fieldset" aria-describedby="dob-hint dob-error" role="group">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--xl">
      <h1 class="govuk-fieldset__heading">
        What is your date of birth?
      </h1>
    </legend>
    <span id="dob-hint" class="govuk-hint">
      For example, 31 3 1980
    </span>
    <span id="dob-error" class="govuk-error-message">
      Date of birth must be in the past
    </span>
    <div class="govuk-date-input" id="dob">

      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="dob-day">
            Day
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-2 " id="dob-day" name="dob-day" type="number" value="6" pattern="[0-9]*">
        </div>
      </div>

      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="dob-month">
            Month
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-2 " id="dob-month" name="dob-month" type="number" value="3" pattern="[0-9]*">
        </div>
      </div>

      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="dob-year">
            Year
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-4 " id="dob-year" name="dob-year" type="number" value="2076" pattern="[0-9]*">
        </div>
      </div>
    </div>
  </fieldset>
</div>
{% from "date-input/macro.njk" import govukDateInput %}

{{ govukDateInput({
  id: "dob",
  name: "dob",
  fieldset: {
    legend: {
      text: "What is your date of birth?",
      isPageHeading: true,
      classes: "govuk-fieldset__legend--xl"
    }
  },
  hint: {
    text: "For example, 31 3 1980"
  },
  errorMessage: {
    text: "Date of birth must be in the past"
  },
  items: [
    {
      name: "day",
      value: "6"
    },
    {
      name: "month",
      value: "3"
    },
    {
      name: "year",
      value: "2076"
    }
  ]
}) }}

You can configure this component using the Nunjucks macro arguments.

Research on this component

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

More research is needed to determine the extent to which users struggle to enter months as numbers, and whether allowing them to enter months as text is helpful.

Get in touch

If you’ve got a question, idea or suggestion share it in #govuk-design-system on cross-government Slack (open in app) or email the Design System team on govuk-design-system-support@digital.cabinet-office.gov.uk

Discuss ‘Date input’ on GitHub