Date input

How the date input works

The date input is made up of three text inputs that are grouped together in a <fieldset> and contain a <legend>. Each of the three fields has a <label>.

<fieldset class="p-form__fieldset">
  <legend class="p-form__fieldset-legend">Legend</legend>
  <div class="p-form__date-input">
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-standard-day">Day</label>
      <input
        type="text"
        inputmode="numeric"
        name="date-standard-day"
        id="date-standard-day"
        class="p-form__input p-form__date-item-input--day"
      />
    </div>
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-standard-month">
        Month
      </label>
      <input
        type="text"
        inputmode="numeric"
        name="date-standard-month"
        id="date-standard-month"
        class="p-form__input p-form__date-item-input--month"
      />
    </div>
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-standard-year">
        Year
      </label>
      <input
        type="text"
        inputmode="numeric"
        name="date-standard-year"
        id="date-standard-year"
        class="p-form__input p-form__date-item-input--year"
      />
    </div>
  </div>
</fieldset>

Hint text

The date input can display hint text. Use hint text when you need to give users guidance on how to input dates correctly.

Using hint text is optional.

See how to write hint text further down this page for best practice guidance.

<fieldset class="p-form__fieldset">
  <legend class="p-form__fieldset-legend">Legend</legend>
  <span class="p-form__hint">Hint text</span>
  <div class="p-form__date-input">
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-hint-day">Day</label>
      <input
        type="text"
        inputmode="numeric"
        name="date-hint-day"
        id="date-hint-day"
        class="p-form__input p-form__date-item-input--day"
      />
    </div>
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-hint-month">Month</label>
      <input
        type="text"
        inputmode="numeric"
        name="date-hint-month"
        id="date-hint-month"
        class="p-form__input p-form__date-item-input--month"
      />
    </div>
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-hint-year">Year</label>
      <input
        type="text"
        inputmode="numeric"
        name="date-hint-year"
        id="date-hint-year"
        class="p-form__input p-form__date-item-input--year"
      />
    </div>
  </div>
</fieldset>

Error messages

The date input can display an error message. It appears below the legend or hint text. This creates a clear link between the error and:

• what is being asked
• any guidance on what information is required
• how to enter the information

Only display error messages after a user submits the form or clicks to continue to the next step. Do not validate inputs as users are typing as it can cause stress and frustration.

If the error is with two or three of the fields, then highlight all the fields.

<fieldset class="p-form__fieldset">
  <legend class="p-form__fieldset-legend">Legend</legend>
  <span class="p-form__hint">Hint text</span>
  <span class="p-form__error">Error message text</span>
  <div class="p-form__date-input">
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-error-all-day">
        Day
      </label>
      <input
        type="text"
        inputmode="numeric"
        name="date-error-all-day"
        id="date-error-all-day"
        class="p-form__input p-form__date-item-input--day p-form__input--error"
      />
    </div>
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-error-all-month">
        Month
      </label>
      <input
        type="text"
        inputmode="numeric"
        name="date-error-all-month"
        id="date-error-all-month"
        class="p-form__input p-form__date-item-input--month p-form__input--error"
      />
    </div>
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-error-all-year">
        Year
      </label>
      <input
        type="text"
        inputmode="numeric"
        name="date-error-all-year"
        id="date-error-all-year"
        class="p-form__input p-form__date-item-input--year p-form__input--error"
      />
    </div>
  </div>
</fieldset>

If the error is with one field, then only highlight that field and tailor the message to help the user enter the correct information.

<fieldset class="p-form__fieldset">
  <legend class="p-form__fieldset-legend">Legend</legend>
  <span class="p-form__hint">Hint text</span>
  <span class="p-form__error">Error message text</span>
  <div class="p-form__date-input">
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-error-single-day">
        Day
      </label>
      <input
        type="text"
        inputmode="numeric"
        name="date-error-single-day"
        id="date-error-single-day"
        class="p-form__input p-form__date-item-input--day p-form__input--error"
      />
    </div>
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-error-single-month">
        Month
      </label>
      <input
        type="text"
        inputmode="numeric"
        name="date-error-single-month"
        id="date-error-single-month"
        class="p-form__input p-form__date-item-input--month"
      />
    </div>
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-error-single-year">
        Year
      </label>
      <input
        type="text"
        inputmode="numeric"
        name="date-error-single-year"
        id="date-error-single-year"
        class="p-form__input p-form__date-item-input--year"
      />
    </div>
  </div>
</fieldset>

See how to write error text further down this page for best practice guidance.

If your product is already handling errors in a different way

If you work in Parliament and need advice on presenting errors in this way, contact the Improving User Experience team on the #design-system Slack channel.

How to use a date input

Update the relevant fields

To create a clear and accessible relationship between the <label> and the input:

• you must use the <label> element to clearly associate text with the input
• the for attribute of the <label> must exactly match the id of the input
• the id used for the <label> must also be unique from other form elements on the page

You must also update the <legend> to describe the group of inputs.

Use autocomplete for date of birth

When you are asking for a date of birth, use the autocomplete attribute on the date input. This allows browsers to autofill the information if a user has entered it before.

To do this, set the autocomplete attribute on the relevant fields to:

• bday-day
• bday-month
• bday-year

Make sure to add the appropriate autocomplete attribute values. This ensures screen readers can read the autocomplete form fields.

<fieldset class="p-form__fieldset">
  <legend class="p-form__fieldset-legend">Legend</legend>
  <span class="p-form__hint">Hint text</span>
  <div class="p-form__date-input">
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-auto-day">Day</label>
      <input
        type="text"
        inputmode="numeric"
        name="date-auto-day"
        id="date-auto-day"
        class="p-form__input p-form__date-item-input--day"
        autocomplete="bday-day"
      />
    </div>
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-auto-month">Month</label>
      <input
        type="text"
        inputmode="numeric"
        name="date-auto-month"
        id="date-auto-month"
        class="p-form__input p-form__date-item-input--month"
        autocomplete="bday-month"
      />
    </div>
    <div class="p-form__date-item">
      <label class="p-form__date-item-label" for="date-auto-year">Year</label>
      <input
        type="text"
        inputmode="numeric"
        name="date-auto-year"
        id="date-auto-year"
        class="p-form__input p-form__date-item-input--year"
        autocomplete="bday-year"
      />
    </div>
  </div>
</fieldset>

Do not use the disabled state attribute

Do not use the disabled state attribute as it can cause issues for users. Disabled inputs are often not distinguishable from active ones, and they do not tell users why they cannot interact with them.

Instead, allow users access to all inputs, even if that means that after trying to submit or continue with a form it fails. Use error messages to then help users understand what they need to do to fix the problem. Using error messages also follows best practice guidance for creating accessible interfaces.

If users must submit information in a specific order, consider using a multistep form.

Displaying previously submitted information

Do not use the disabled state to display previously submitted information. This can confuse users as they may not realise that they cannot change the information.

Instead, consider displaying the information as standard text.

Date pickers

Date pickers allow users to select dates from a calendar view. This functionality is not yet supported by the design system.

If you need to use a date picker, contact the Improving User Experience team on the #design-system Slack channel to discuss your requirements.

How to write hint text

Keep hint text to a single short sentence, without any full stops.

Make sure that any example dates you use in hint text are valid for the question. For example, a date of birth field might have the hint text ‘For example 21 8 1990'.

Do not include links within hint text. While screen readers will read out the link text when describing the field, they will not tell users that the text is a link.

How to write error text

Error messages must explain what went wrong and how to fix it.

Make sure to follow the error message guidance or use the specific error messages below to help your users.

If there is more than one error, show the highest priority error message. In order of priority, show error messages about:

• missing or incomplete information
• information that cannot be correct (for example, the number ‘13’ in the month field)
• information that fails validation for another reason

Specific error messages for specific error states

If nothing is entered

Highlight the date input as a whole.

Say ‘Enter [whatever it is]’. For example, ‘Enter your start date’.

If the date is incomplete

Highlight the day, month or year field where the information is missing or incomplete. If more than one field is missing information, highlight the fields the user needs to fill in.

Say ‘[whatever it is] must include a [whatever is missing]’.

For example, ‘Date of birth must include a month’, ‘Date of birth must include a day and month’ or ‘Year must include 4 numbers’.

If the date entered cannot be correct

For example, ‘13’ in the month field cannot be correct.

Highlight the day, month or year field with the incorrect information. Or highlight the date as a whole if there is incorrect information in more than one field, or it is not clear which field is incorrect.

Say ‘[Whatever it is] must be a real date’. For example, ‘Date of birth must be a real date’.

If the date is in the future when it needs to be in the past

Highlight the date input as a whole.

Say ‘[whatever it is] must be in the past’. For example, ‘Date of birth must be in the past’.

If the date is in the future when it needs to be today or in the past

Highlight the date input as a whole.

Say ‘[whatever it is] must be today or in the past’. For example, ‘Sickness absence must be today or in the past’.

If the date is in the past when it needs to be in the future

Highlight the date input as a whole.

Say ‘[whatever it is] must be in the future’. For example, ‘The date your course ends must be in the future’.

If the date is in the past when it needs to be today or in the future

Highlight the date input as a whole.

Say ‘[whatever it is] must be today or in the future’. For example, ‘The date your course ends must be today or in the future’.

If the date must be the same as or after another date

Highlight the date input as a whole.

Say ‘[whatever it is] must be the same as or after [date and optional description]’. For example, ‘The date your course ends must be the same as or after 1 February 2024 when you started the course’.

If the date must be after another date

Highlight the date input as a whole.

Say ‘[whatever it is] must be after [date and optional description]’. For example, ‘The day your course ends must be after 1 February 2024’.

If the date must be the same as or before another date

Highlight the date input as a whole.

Say ‘[whatever it is] must be the same as or before [date and optional description]’. For example, ‘The date of your last review must be the same as or before 31 August 2024’.

If the date must be before another date

Highlight the date input as a whole.

Say ‘[whatever it is] must be before [date and optional description]’. For example, ‘The date of your last review must be before 31 August 2024’.

If the date must be between two dates

Highlight the date input as a whole.

Say ‘[whatever it is] must be between [date] and [date and optional description]’. For example, ‘The date your contract started must be between 1 September 2024 and 30 September 2024’.