Form elements – Date input

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

HTML code for date input
Nunjucks code for date input

<div class="nhsuk-form-group">
  <fieldset class="nhsuk-fieldset" role="group" aria-describedby="date-of-birth-hint">
    <legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--l">
      <h1 class="nhsuk-fieldset__heading">
        What is your date of birth?
      </h1>
    </legend>
    <div id="date-of-birth-hint" class="nhsuk-hint">
      For example, 15 3 1984
    </div>
    <div id="date-of-birth" class="nhsuk-date-input">
      <div class="nhsuk-date-input__item">
        <div class="nhsuk-form-group">
          <label class="nhsuk-label nhsuk-date-input__label" for="date-of-birth-day">
            Day
          </label>
          <input class="nhsuk-input nhsuk-date-input__input nhsuk-input--width-2" id="date-of-birth-day" name="dateOfBirth[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="date-of-birth-month">
            Month
          </label>
          <input class="nhsuk-input nhsuk-date-input__input nhsuk-input--width-2" id="date-of-birth-month" name="dateOfBirth[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="date-of-birth-year">
            Year
          </label>
          <input class="nhsuk-input nhsuk-date-input__input nhsuk-input--width-4" id="date-of-birth-year" name="dateOfBirth[year]" type="text" inputmode="numeric">
        </div>
      </div>
    </div>
  </fieldset>
</div>

Nunjucks

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.

Primary options
Name	Type	Description
id	string	Required. This is used for the main component and to compose the `id` attribute for each item.
namePrefix	string	Optional prefix. This is used to prefix each date input `name` attribute, wrapped in `[` and `]`. For example, setting `namePrefix: "dob"` will output the `name` attributes `dob[day]`, `dob[month]` and `dob[year]` respectively.
items	array	The inputs within the date input component. See macro options for items.
hint	object	Can be used to add a hint to a date input component. See macro options for hint.
errorMessage	object	Can be used to add an error message to the date input component. The error message component will not display if you use a falsy value for `errorMessage`, for example `false` or `null`. See macro options for errorMessage.
formGroup	object	Additional options for the form group containing the date input component. See macro options for formGroup.
fieldset	object	Can be used to add a fieldset to the date input component. See macro options for fieldset.
values	object	An optional object use to specify `value` attributes for the date parts without setting items. See macro options for values.
classes	string	Classes to add to the date-input container.
attributes	object	HTML attributes (for example data attributes) to add to the date-input container.

Options for `items` array objects
Name	Type	Description
id	string	Item-specific `id` attribute. If provided, it will be used instead of the generated ID.
name	string	Required. Item-specific `name` attribute.
label	string	Item-specific label text. If provided, this will be used instead of `name` for item label text.
inputmode	string	Optional value for the `inputmode` attribute. Defaults to `"numeric"`.
value	string	If provided, it will be used as the initial `value` attribute of the input.
autocomplete	string	Attribute to meet WCAG success criterion 1.3.5: Identify input purpose, for instance `"bday-day"`. See the Autofill section in the HTML standard for a full list of attributes that can be used.
pattern	string	Attribute to provide a regular expression pattern, used to match allowed character combinations for the input value.
classes	string	Classes to add to date input item.
attributes	object	HTML attributes (for example data attributes) to add to the date input tag.

Options for `formGroup` object
Name	Type	Description
classes	string	Classes to add to the form group (for example to show error state for the whole group).
attributes	object	HTML attributes (for example data attributes) to add to the form group.
beforeInputs	object	Content to add before the inputs used by the date input component. See macro options for formGroup beforeInputs.
afterInputs	object	Content to add after the inputs used by the date input component. See macro options for formGroup afterInputs.

Options for formGroup `beforeInputs` object
Name	Type	Description
text	string	Required. Text to add before the inputs. If `html` is provided, the `text` option will be ignored.
html	string	Required. HTML to add before the inputs. If `html` is provided, the `text` option will be ignored.

Options for formGroup `afterInputs` object
Name	Type	Description
text	string	Required. Text to add after the inputs. If `html` is provided, the `text` option will be ignored.
html	string	Required. HTML to add after the inputs. If `html` is provided, the `text` option will be ignored.

Options for `values` object
Name	Type	Description
day	string	The `value` attribute for the day input.
month	string	The `value` attribute for the month input.
year	string	The `value` attribute for the year input.

{% from "date-input/macro.njk" import dateInput %}

{{ dateInput({
  id: "date-of-birth",
  namePrefix: "dateOfBirth",
  fieldset: {
    legend: {
      text: "What is your date of birth?",
      size: "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"
    }
  ]
}) }}

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 example in a new tab

HTML code for date input with errors
Nunjucks code for date input with errors

HTML

<div class="nhsuk-form-group nhsuk-form-group--error">
  <fieldset class="nhsuk-fieldset" role="group" aria-describedby="date-of-birth-hint date-of-birth-error">
    <legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--l">
      <h1 class="nhsuk-fieldset__heading">
        What is your date of birth?
      </h1>
    </legend>
    <div id="date-of-birth-hint" class="nhsuk-hint">
      For example, 15 3 1984
    </div>
    <span id="date-of-birth-error" class="nhsuk-error-message">
      <span class="nhsuk-u-visually-hidden">Error:</span> Enter your date of birth
    </span>
    <div id="date-of-birth" class="nhsuk-date-input">
      <div class="nhsuk-date-input__item">
        <div class="nhsuk-form-group">
          <label class="nhsuk-label nhsuk-date-input__label" for="date-of-birth-day">
            Day
          </label>
          <input class="nhsuk-input nhsuk-date-input__input nhsuk-input--width-2 nhsuk-input--error" id="date-of-birth-day" name="dateOfBirth[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="date-of-birth-month">
            Month
          </label>
          <input class="nhsuk-input nhsuk-date-input__input nhsuk-input--width-2 nhsuk-input--error" id="date-of-birth-month" name="dateOfBirth[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="date-of-birth-year">
            Year
          </label>
          <input class="nhsuk-input nhsuk-date-input__input nhsuk-input--width-4 nhsuk-input--error" id="date-of-birth-year" name="dateOfBirth[year]" type="text" inputmode="numeric">
        </div>
      </div>
    </div>
  </fieldset>
</div>

Nunjucks

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.

Primary options
Name	Type	Description
id	string	Required. This is used for the main component and to compose the `id` attribute for each item.
namePrefix	string	Optional prefix. This is used to prefix each date input `name` attribute, wrapped in `[` and `]`. For example, setting `namePrefix: "dob"` will output the `name` attributes `dob[day]`, `dob[month]` and `dob[year]` respectively.
items	array	The inputs within the date input component. See macro options for items.
hint	object	Can be used to add a hint to a date input component. See macro options for hint.
errorMessage	object	Can be used to add an error message to the date input component. The error message component will not display if you use a falsy value for `errorMessage`, for example `false` or `null`. See macro options for errorMessage.
formGroup	object	Additional options for the form group containing the date input component. See macro options for formGroup.
fieldset	object	Can be used to add a fieldset to the date input component. See macro options for fieldset.
values	object	An optional object use to specify `value` attributes for the date parts without setting items. See macro options for values.
classes	string	Classes to add to the date-input container.
attributes	object	HTML attributes (for example data attributes) to add to the date-input container.

Options for `items` array objects
Name	Type	Description
id	string	Item-specific `id` attribute. If provided, it will be used instead of the generated ID.
name	string	Required. Item-specific `name` attribute.
label	string	Item-specific label text. If provided, this will be used instead of `name` for item label text.
inputmode	string	Optional value for the `inputmode` attribute. Defaults to `"numeric"`.
value	string	If provided, it will be used as the initial `value` attribute of the input.
autocomplete	string	Attribute to meet WCAG success criterion 1.3.5: Identify input purpose, for instance `"bday-day"`. See the Autofill section in the HTML standard for a full list of attributes that can be used.
pattern	string	Attribute to provide a regular expression pattern, used to match allowed character combinations for the input value.
classes	string	Classes to add to date input item.
attributes	object	HTML attributes (for example data attributes) to add to the date input tag.

Options for `formGroup` object
Name	Type	Description
classes	string	Classes to add to the form group (for example to show error state for the whole group).
attributes	object	HTML attributes (for example data attributes) to add to the form group.
beforeInputs	object	Content to add before the inputs used by the date input component. See macro options for formGroup beforeInputs.
afterInputs	object	Content to add after the inputs used by the date input component. See macro options for formGroup afterInputs.

Options for formGroup `beforeInputs` object
Name	Type	Description
text	string	Required. Text to add before the inputs. If `html` is provided, the `text` option will be ignored.
html	string	Required. HTML to add before the inputs. If `html` is provided, the `text` option will be ignored.

Options for formGroup `afterInputs` object
Name	Type	Description
text	string	Required. Text to add after the inputs. If `html` is provided, the `text` option will be ignored.
html	string	Required. HTML to add after the inputs. If `html` is provided, the `text` option will be ignored.

Options for `values` object
Name	Type	Description
day	string	The `value` attribute for the day input.
month	string	The `value` attribute for the month input.
year	string	The `value` attribute for the year input.

{% from "date-input/macro.njk" import dateInput %}

{{ dateInput({
  id: "date-of-birth",
  namePrefix: "dateOfBirth",
  fieldset: {
    legend: {
      text: "What is your date of birth?",
      size: "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"
    }
  ]
}) }}

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.

Feed back or share insights on GitHub

Read more about how to feed back or share insights.

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

Updated: June 2021