Ask users for Dates

Help users enter or select a 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",
  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"
  }
}) }}

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" 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",
  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"
  }
}) }}

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

How to write dates

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

Error messages

Error messages should be styled 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 govuk-input--error" 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",
  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"
  },
  errorMessage: {
    text: "Date of birth 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

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.

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 ‘Dates’ on GitHub