Ask users for Dates

Help users enter or select a date.

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset" role="group" aria-describedby="passport-issued-hint">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--xl">
      <h1 class="govuk-fieldset__heading">
        When was your passport issued?
      </h1>
    </legend>
    <span id="passport-issued-hint" class="govuk-hint">
      For example, 27 3 2007
    </span>
    <div class="govuk-date-input" id="passport-issued">
      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="passport-issued-day">
            Day
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-2" id="passport-issued-day" name="passport-issued-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="passport-issued-month">
            Month
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-2" id="passport-issued-month" name="passport-issued-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="passport-issued-year">
            Year
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-4" id="passport-issued-year" name="passport-issued-year" type="number" pattern="[0-9]*">
        </div>
      </div>
    </div>
  </fieldset>
</div>
{% from "govuk/components/date-input/macro.njk" import govukDateInput %}

{{ govukDateInput({
  id: "passport-issued",
  namePrefix: "passport-issued",
  fieldset: {
    legend: {
      text: "When was your passport issued?",
      isPageHeading: true,
      classes: "govuk-fieldset__legend--xl"
    }
  },
  hint: {
    text: "For example, 27 3 2007"
  }
}) }}

When to use this pattern

Follow this pattern whenever you need users to provide or select a date as part of your service.

How it works

The way you should ask users for dates depends on the types of date you’re asking for.

Dates you may need users to provide include:

  • memorable dates, like a date of birth or marriage
  • dates from documents or cards, like a passport or credit card
  • approximate dates, like ‘December 2017’
  • relative dates, like ‘4 days from today’

In some cases you might need users to pick a date from a given selection.

Asking for memorable dates

Ask for memorable dates, like dates of birth, using the date input component.

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset" role="group" aria-describedby="dob-hint">
    <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" autocomplete="bday-day" 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" autocomplete="bday-month" 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" autocomplete="bday-year" pattern="[0-9]*">
        </div>
      </div>
    </div>
  </fieldset>
</div>
{% from "govuk/components/date-input/macro.njk" import govukDateInput %}

{{ govukDateInput({
  id: "dob",
  namePrefix: "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",
      classes: "govuk-input--width-2",
      autocomplete: "bday-day"
    },
    {
      name: "month",
      classes: "govuk-input--width-2",
      autocomplete: "bday-month"
    },
    {
      name: "year",
      classes: "govuk-input--width-4",
      autocomplete: "bday-year"
    }
  ]
}) }}

Use the autocomplete attribute when asking for a date of birth

Use the autocomplete attribute when you’re asking for a date of birth. This lets browsers autofill the information on a user’s behalf if they’ve entered it previously.

To do this, set the autocomplete attribute on the 3 fields to bday-day, bday-month and bday-year. See how to do this in the HTML and Nunjucks tabs in the memorable date example above.

If you are working in production you’ll need to do this to meet WCAG 2.1 Level AA.

You will not normally need to use the autocomplete attribute in prototypes, as users will not generally be using their own devices.

Asking for dates from documents and cards

When asking for a date exactly as it’s shown on a passport, credit card or other document, make the fields match the format of the original. This makes it easier for users to copy the date across accurately.

Asking for approximate dates

Allow users to enter an approximate date when you are asking them for information they may not know or may struggle to remember. For example, allow users to enter ‘December 2017’ for a field that says ‘the date you lost your passport’.

Asking for relative dates

You may need to ask for dates that are relative to today’s date or another date - this is common if a user is setting a reminder.

To do this let users enter or select relative dates like ‘tomorrow’ or ‘1 day before’. If the day of the week is important, show this as well.

Helping users to pick a date

Users might need to pick a date from a selection, for example, to book an appointment.

To do this, you can present dates in a calendar format using a calendar control. Users are typically shown one month’s worth of dates at a time, and can skip through months and years.

Only use a calendar control if users need to:

  • pick a date in the near future or recent past
  • know the day of the week, or the week of the month, as well as the date
  • be able to see dates in relation to other dates

Never make a calendar control that depends on JavaScript as the only input option. Allow users to enter the date into a text input as well as use the control.

How to check that dates are valid

To check that the dates users give you are valid, make sure that:

  • it’s a real date, for example, not 54 July
  • past dates are in the past
  • future dates are in the future
  • the first date in a date range is before the second

Make sure you accept numbers below 10 both with and without a leading zero.

How to write dates

See the GOV.UK style for writing dates and date ranges.

If you give an example date, use 13 or more for the day and 9 or less for the month - for example ‘27 3 2007’. This helps users enter the date in the correct order and shows them they do not need to include leading zeroes.

Error messages

Error messages should be styled like this:

<div class="govuk-form-group govuk-form-group--error">
  <fieldset class="govuk-fieldset" role="group" aria-describedby="passport-issued-hint passport-issued-error">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--xl">
      <h1 class="govuk-fieldset__heading">
        When was your passport issued?
      </h1>
    </legend>
    <span id="passport-issued-hint" class="govuk-hint">
      For example, 27 3 2007
    </span>
    <span id="passport-issued-error" class="govuk-error-message">
      <span class="govuk-visually-hidden">Error:</span> The date your passport was issued must be in the past
    </span>
    <div class="govuk-date-input" id="passport-issued">
      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="passport-issued-day">
            Day
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-2" id="passport-issued-day" name="passport-issued-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="passport-issued-month">
            Month
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-2" id="passport-issued-month" name="passport-issued-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="passport-issued-year">
            Year
          </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-4 govuk-input--error" id="passport-issued-year" name="passport-issued-year" type="number" value="2076" pattern="[0-9]*">
        </div>
      </div>
    </div>
  </fieldset>
</div>
{% from "govuk/components/date-input/macro.njk" import govukDateInput %}

{{ govukDateInput({
  id: "passport-issued",
  namePrefix: "passport-issued",
  fieldset: {
    legend: {
      text: "When was your passport issued?",
      isPageHeading: true,
      classes: "govuk-fieldset__legend--xl"
    }
  },
  hint: {
    text: "For example, 27 3 2007"
  },
  errorMessage: {
    text: "The date your passport was issued must be in the past"
  },
  items: [
    {
      classes: "govuk-input--width-2",
      name: "day",
      value: "6"
    },
    {
      classes: "govuk-input--width-2",
      name: "month",
      value: "3"
    },
    {
      classes: "govuk-input--width-4 govuk-input--error",
      name: "year",
      value: "2076"
    }
  ]
}) }}

Make sure errors follow the guidance in date input and have specific error messages for specific error states.

Research on this pattern

Read a blog post about asking for a date of birth.

If you’ve used this pattern, 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.

Help improve this page

To help make sure the Dates page is useful, relevant and up to date, you can:

Need help?

If you’ve got a question about the GOV.UK Design System you can contact the team: