Skip to main content
  1. X-GOVUK projects
  2. GOV.UK Form Builder
  3. Date input

Date input

Date inputs allow the user to enter the day, month and year of an event.

The date input’s parameters match those used by Rails’ date_select helper. To access the parameters in your controller you should just need to permit the attribute, for example:

# in UsersController

def user_params
  params.require(:user).permit(:date_of_birth, ...)
end

Three inputs for day, month and year respectively are used to capture the dates rather than a date picker. This is because:

  • some users find date pickers difficult to use
  • often users will be expected to enter a date they know rather than to pick a date

Exact date input with legend and hint and birth date autocompletion

Input

= f.govuk_date_field :date_of_birth,
  date_of_birth: true,
  legend: { text: 'Enter your date of birth' },
  hint: { text: 'For example, 31 3 1980' }
<%= f.govuk_date_field :date_of_birth, date_of_birth: true, legend: { text: 'Enter your date of birth' }, hint: { text: 'For example, 31 3 1980' } %>

Output

Enter your date of birth
For example, 31 3 1980
<div class="govuk-form-group">
  <fieldset class="govuk-fieldset" aria-describedby="person-date-of-birth-hint">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      Enter your date of birth
    </legend>
    <div class="govuk-hint" id="person-date-of-birth-hint">
      For example, 31 3 1980
    </div>
    <div class="govuk-date-input">
      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="person_date_of_birth_3i">
            Day
          </label>
          <input id="person_date_of_birth_3i" class="govuk-input govuk-date-input__input govuk-input--width-2" name="person[date_of_birth(3i)]" type="text" inputmode="numeric" autocomplete="bday-day">
        </div>
      </div>
      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="person_date_of_birth_2i">
            Month
          </label>
          <input id="person_date_of_birth_2i" class="govuk-input govuk-date-input__input govuk-input--width-2" name="person[date_of_birth(2i)]" type="text" inputmode="numeric" autocomplete="bday-month">
        </div>
      </div>
      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="person_date_of_birth_1i">
            Year
          </label>
          <input id="person_date_of_birth_1i" class="govuk-input govuk-date-input__input govuk-input--width-4" name="person[date_of_birth(1i)]" type="text" inputmode="numeric" autocomplete="bday-year">
        </div>
      </div>
    </div>
  </fieldset>
</div>

Approximate dates – recording the closest month

When asking for dates that the user might not know or could struggle to remember, such as their graduation date, the exact date might not be necessary. The day can be optionally omitted by providing the omit_day parameter.

When mapped to a Date attribute, Ruby will automatically set the Day to be 1 when none is provided. This should be taken into account when displaying the data or using it for analysis.

!WarningDate inputs without a day field are not currently part of the GOV.UK Design System

Input

= f.govuk_date_field :graduation_month,
  omit_day: true,
  legend: { text: 'When did you graduate?' },
  hint: { text: 'For example, 3 2014' }
<%= f.govuk_date_field :graduation_month, omit_day: true, legend: { text: 'When did you graduate?' }, hint: { text: 'For example, 3 2014' } %>

Output

When did you graduate?
For example, 3 2014
<div class="govuk-form-group">
  <fieldset class="govuk-fieldset" aria-describedby="person-graduation-month-hint">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      When did you graduate?
    </legend>
    <div class="govuk-hint" id="person-graduation-month-hint">
      For example, 3 2014
    </div>
    <div class="govuk-date-input">
      <input id="person_graduation_month_3i" name="person[graduation_month(3i)]" type="hidden" value="1">
      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="person_graduation_month_2i">
            Month
          </label>
          <input id="person_graduation_month_2i" class="govuk-input govuk-date-input__input govuk-input--width-2" name="person[graduation_month(2i)]" type="text" inputmode="numeric">
        </div>
      </div>
      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="person_graduation_month_1i">
            Year
          </label>
          <input id="person_graduation_month_1i" class="govuk-input govuk-date-input__input govuk-input--width-4" name="person[graduation_month(1i)]" type="text" inputmode="numeric">
        </div>
      </div>
    </div>
  </fieldset>
</div>

Specifying client side length restrictions on date inputs with maxlength

To enable client side restrictions on the number of characters each input requires, you can use the maxlength_enabled parameter. This will default the day and month inputs to 2 characters and the year input to 4 characters.

Input

= f.govuk_date_field :date_of_trade,
  maxlength_enabled: true,
  legend: { text: 'When are you planning to trade the goods?' },
  hint: { text: 'Use the format day, month, year, for example 27 3 2021' }
<%= f.govuk_date_field :date_of_trade, maxlength_enabled: true, legend: { text: 'When are you planning to trade the goods?' }, hint: { text: 'Use the format day, month, year, for example 27 3 2021' } %>

Output

When are you planning to trade the goods?
Use the format day, month, year, for example 27 3 2021
<div class="govuk-form-group">
  <fieldset class="govuk-fieldset" aria-describedby="person-date-of-trade-hint">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      When are you planning to trade the goods?
    </legend>
    <div class="govuk-hint" id="person-date-of-trade-hint">
      Use the format day, month, year, for example 27 3 2021
    </div>
    <div class="govuk-date-input">
      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="person_date_of_trade_3i">
            Day
          </label>
          <input id="person_date_of_trade_3i" class="govuk-input govuk-date-input__input govuk-input--width-2" name="person[date_of_trade(3i)]" type="text" inputmode="numeric" maxlength="2">
        </div>
      </div>
      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="person_date_of_trade_2i">
            Month
          </label>
          <input id="person_date_of_trade_2i" class="govuk-input govuk-date-input__input govuk-input--width-2" name="person[date_of_trade(2i)]" type="text" inputmode="numeric" maxlength="2">
        </div>
      </div>
      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="person_date_of_trade_1i">
            Year
          </label>
          <input id="person_date_of_trade_1i" class="govuk-input govuk-date-input__input govuk-input--width-4" name="person[date_of_trade(1i)]" type="text" inputmode="numeric" maxlength="4">
        </div>
      </div>
    </div>
  </fieldset>
</div>