Date input

[govuk-design-system]

Use this issue to discuss this component in the GOV.UK Design System.

Anything else

Related to the 'date picker' component issue

[stagarz]

I was wondering, are there any reasons or research insights that would point against 'masking' non-numbers and/or more than the necessary digits for each field? E.g. should we stop users from adding letters or a 3rd digit on the month field?

[querkmachine]

@EvaHageman @stagarz In a vague attempt to answer those questions without retreading ground too much.

Why not a single input?

Aside from the various problems with datepicker interfaces mentioned earlier in this issue, another problem with using a single input[type=date] field is that the browser becomes solely responsible for defining the date format.

If the user is in another country—such as an expatriate or a person travelling abroad—or their machine has an incorrectly configured locale, the browser may set the input to use a different date format.

The user may not realise that's the case (e.g. being asked for MM/DD/YYYY instead of DD/MM/YYY) or may be confused if it's an unfamiliar format or incorporates non-English text on an otherwise English language page (such an input might read 2023年1月20日 in Japan, for example). This increases the likeliness of confusion, erroneous input, and prevents services from providing meaningful guidance to the user.

(Fun story: I encountered this exact problem a few years ago. The singular date input on a hotel booking website was using MM/DD/YYYY format, despite both being based in the UK. Suffice to say, I spent the night sleeping on a bench in Heathrow Terminal 4.)

Why not auto-tab between the three inputs?

As Joe mentioned, this is unexpected behaviour for many users, and they often don't notice that it's happened. If I remember correctly, not all assistive technologies will announce this change either.

There is also technical and UX complexity involved.

• If a user has typed 2 in the day field, do they mean the 2nd, or are they partway through typing 21? We can't auto-tab if it's the former, but if they type a number between 4 and 9 then we can.
• If a user has typed 2 in the month field, we can assume they mean February, so we can auto-tab, which is inconsistent with the day field. But if they type 1 then we can't, as it could be any one of four different months.
• A bit of a contrived example, but if a user has typed 010 into the month field, it is more likely they intended October, whereas auto-tab functionality would enforce it as being January.
• If the three fields are coded to work 'as one' when the user is typing, it would also stand to reason that pressing backspace or using the left/right arrows on the keyboard should also delete and navigate between the three fields, adding more technical and UX related complexity.

Remember that GOV.UK services are usually accessed infrequently by users—used every few months or years when a particular task needs to be completed—so they are unlikely to develop a mental model for this bespoke behaviour.

Users who are less tech literate are also far more likely to stumble over this kind of functionality, as it often doesn't match their expectations for how forms work.

Why not use a single text input with input masking?

Input masking comes with many of the same complexities and downfalls as auto-tabbing does, the 'tabbing' just happens within a single input instead of between multiple inputs.

Input masking comes with its own technical pitfalls, such as the value of the field usually being harder to parse and validate on the backend compared to having separate inputs. Input masking also won't work if JavaScript is unavailable.

A particular feature that I've not touched on yet is that some service teams do the hard work to make it simple.

Although we give an entirely numerical example of a date format in our examples (e.g. 22 9 1991), some users still try to enter the month as a word (as Frankie described above). Accounting for these situations without resorting to error messages is only possible because we don't apply limitations to the length or format of user input on the frontend—something we would need to do if we were to implement auto-tabbing or input masking.

Ultimately, the date input is a pretty good example of keeping it simple being the option that works best in practice!

[stagarz]

Many thanks for the prompt and extensive response @querkmachine! In our case, we're keeping the 3 input fields, so the only reason to not set maxlength for each field would be for interpreting Oct as 10, right?

I believe masking non-numbers requires js, so that may be a different can of worms.

[EvaHageman]

Thanks so much for taking the time to reply and going into so much detail. This is super helpful and super interesting to learn your thought proces behind it. 🙌

[joelanman]

@stagarz we don't use maxlength as its an example of silent failure - if the user types or pastes anything over the limit for any reason, maxlength will silently truncate it. The user gets no feedback that this happened and this can introduce errors. Far batter to accept input and then display an error if needed (through form validation).

[jessdenney]

My project is planning to add a date picker to the date input component to allow a user to select a future date.

Context: Scheduling a future payment to HMRC using open banking

User need: as the date entered is likely to not be a 'known date' having a date picker helps the user plan. The calendar view allows the dates to be seen in context . The user can avoid scheduling a payment on a Saturday or Sunday for example when payments may take longer to process, or can plan around incoming and out going payments to manage cash flow.

We have decided to go with a version similar to the Digital Scotland one as this one is the most accessible I have been able to find, it fits in well with the style of GDS and you can select a date range.

We are making a few changes:

• Adding the button for the date picker on to the standard date input component to be consistent with GDS and more accessible
• Changing the styling of the buttons from Scottish blue to Gov green
• Adding in additional labels to make it more accessible

We are interested to monitor this to see how users interact with the page

This is a screenshot of our design

[frankieroberto]

I’ve opened pull request #2889 to suggest adding guidance that full or abbreviated month names should be accepted, based on the conversations here.

Would welcome any input from @cjforms @joelanman @calvin-lau-sig7 and others!

[cjforms]

Thanks @frankieroberto for opening the pull request, I'm really pleased to see that this might become a thing.

[stevenjmesser]

🆕 We've updated the guidance for Date input based on observed user behaviour and insights shared by @frankieroberto. We recommend accepting month names as well as month numbers, which can also helps users with dyscalculia (thanks @cjforms).

[36degrees]

With a bit of time to kill on the way back from Design System Day in Edinburgh, I did a little spike to 'scratch an itch' and investigating whether we could intelligently handle paste events on the date input and split clipboard data across the three fields.

https://github.com/alphagov/govuk-design-system-backlog/assets/121939/b7f43e87-ae3f-4e03-b2f1-a1b6f39b16b0

The sort of use case I'm imagining is a user copying and pasting saved dates from their notes, password managers etc.

The idea would be to listen for the paste event within the component and intercept it if ALL of the following are true:

• all inputs within the date input are currently empty
• the pasted clipboard data matches the format of the date input, so the correct number of groups of numbers (or letters for the month, to allow for the month name to be used) punctuated by separators (currently '/', '.' or '-')
• the separators match

Once intercepted, we then split the clipboard data across the three fields.

Observations and findings so far:

• The spike doesn't currently 'support' using only two inputs (i.e. only day and month, or month and year). The macro supports this, but we don't know which fields the user is providing. We could infer it from e.g. looking at the field names, but we can't be certain. If we want to 'strictly' match the pasted data against the field type, we'd need to be able to tell what sort of date is being asked for.
• Because we're intercepting the native paste event and then programatically setting the input values, undo doesn't work.
• This would be a lot easier to do with named regex groups and back references (to check the separators match) but not all browsers we care about support them. If we're happy to treat this as an enhancement, we might be able to use them if we wrap them in a try/catch block.
• I'm not sure what we should do in terms of focus management. Arguably it makes sense to move focus to the last field in the date input, but that might be disorientating to e.g. screen reader users.

The branch for the spike is here: https://github.com/alphagov/govuk-frontend/tree/spike-date-input-paste

[jen-scott]

The error message for 'If the date must be between two dates' is ambiguous.

'Between 1 September 2017 and 30 September 2017' does not make it clear if these dates are inclusive, or if only 2 - 29 September would be accepted.

Consider instead: 'The date your contract started must be from 1 September 2017 to 30 September 2017 when you were self-employed’.

Thanks :)

[andrewscrivener]

The accessibility audit we've had has fed back that we should validate on a per input basis and not the whole date component.

We're using a standard GDS date component that displays the following validation messages should the user try to enter an invalid date;

blank: Enter a date of birth
future: Enter a date of birth that is in the past, for example 31 3 1980
under16: Enter a valid date of birth, trainee cannot be younger than 16 years old
hint_html: For example, 31 3 %{year}
invalid: Enter a valid date
invalid_year: The year must include 4 numbers
past: Enter a valid date of birth

The specific response from the accessibility audit team is as follows;

Tester has observed that text descriptions are not provided for error fields. It is expected that text descriptions are clear. The error message should be as specific as possible. In the case of an unsuccessful form submission, re-displaying the form and indicating the fields in error is insufficient for some users to perceive that an error has occurred.

Its been identified on the ‘Trainee personal details’ and ‘Supply Other withdrawal date’ webpages that ‘Date Of Birth’ and ‘On What Date’ fields provide errors when incorrect data is submitted. However, they do not provide specific suggestions relating to which part of the date is incorrect. It is important that suggestions are provided that help the user identify the errors (Please see screenshot/video)

This does not comply with WCAG Level A 2.2: 3.3.1 Error Identification - https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html

I've responded outlining the validation that we do and have been told it's insufficient resulting in a "Major Impact on Functionality" flag. I'm interested to understand if there's a general consensus whether this is a reasonable request and if so the guidance for the GDS date component will need revising?

[joelanman]

@andrewscrivener the guidance says you should highlight the field that is wrong if it is clear, as it is in this case (13 cannot be a month):

https://design-system.service.gov.uk/components/date-input/#if-the-date-entered-cannot-be-correct

[jen-scott]

@andrewscrivener If one of the date fields is left blank, this field must be highlighted when the error is displayed.

"If you’re highlighting just one field - either the day, month or year - only style the field that has an error. The error message must say which field has an error". See: https://design-system.service.gov.uk/components/date-input/

So if year is missing, this field is highlighted and the error message refers to that field. Eg. 'Date of birth must include a year.'

[andrewscrivener]

Thanks very much @joelanman and @jen-scott for the quick response. We've also been advised to include the hint text in the error message so it's repeated for screen readers.

[tomyems]

Date error messages.pdf

I've had a go at writing out the logic for date error messages and making some tweaks along the way:

• I think I've manage to remove 'Date must be a real date'
• Made it clearer about when to highlight which fields
• adapted the 'between' error message to be 'after x date' and 'before y date'

Would welcome any feedback on this approach, experience from trying to do this in services, and whether you felt it would be a helpful addition to the guidance on error messages for date inputs

[cjforms]

Thank you @tomyems for this analysis, much appreciated.

Recently I've been revisiting some old blog posts and one of them prompted me to return to thinking about the difference between 'mechanical help' (how to get through an interaction process based on achieving inputs acceptable to a validation process) and 'decision help' (how to review and think about providing an answer that is acceptable both to the user and to the further processes in the service).

In my mind, your analysis covers the possibilities for mechanical help with dates, very thoroughly. A helpful addition.

I'm not quite so sure that it deals with decision help. For example, what happens when:

• the user doesn't know the date required?
• the user knows the year, but not the day or month?
• the user knows the day and month, but not exactly the year ("I can definitely recall it was on Valentine's Day, but was that 2011 or 2012?")
• the date required is relative to another date (as illustrated in your flow chart - 'must be in the future' / 'can't be in the future' and so on) but the user knows that the other date is incorrect (this one happens to me a lot in practice, for example where I may be trying to book sometime, try a pair of dates in the future, and then go back to amend the start date to after the (previous) end date and get reprimanded for (not yet) changing the old end date before I have a chance to do the amendment).
• the user DOES know the date required, but is reluctant to reveal it for some reason that is private to them or context dependent
• the user doesn't know the date required off by heart, but could ask someone else or look it up, and meanwhile they'd like to get on with the rest of the form to assess the information-gathering requirements
• and so on.

I appreciate that many of these can only be dealt with by knowing a lot more about the context, and then embedding the date in other patterns.

[tomyems]

You are entirely correct @cjforms, I was only helping to assist mechanical help rather than decision help. Still on the mechanical side, some identity documents (passports and so on), have 'XX' for the day or month of the date of birth, for exactly the situation that their date of birth is unknown.

On dates that depend on each other, on a staff facing system, we ended up with both the start date and the end date on the same page, which makes error correction much easier.

[cjforms]

Thanks @tomyems and the XX example on passports nicely illustrates that mechanical help and decision help can both be needed at the same time.

Maybe consider adding something to the flow chart to help to get people to think about decision help as well?

[tomyems]

I've made a bit of progress in thinking about this, and have some thoughts to suggest updates to the guidance on date input based on the flow chart. I've added some decision help guidance, it's not super helpful in terms of answers or necessarily complete, but at least should get service teams thinking about it.

Additions to date input shown not in quotes. https://github.com/alphagov/govuk-design-system/pull/3956 has full diff.

If nothing is entered

Highlight the date input as a whole.

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

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’.

Consider that a user might intentionally leave part of the date blank because they do not know the exact day, or they remember the day and month but not the year. Could you provide more help to these users?

If the day, month or year cannot be correct

Accept all unambiguous inputs.

For day, accept:

• the numbers 1 to 31
• single digits with a leading zero, 01 to 09
• ordinals, 1st, 2nd, ... 31st
• ordinals written, first, second, ... thirty-first

For month, accept:

• the numbers 1 to 12
• single digits with a leading zero, 01 to 09
• English long month names, January, February ... December
• English short month names, Jan, Feb, ... Dec

For day ordinals, and month names, accept any case. For example, 'jan', 'JAN', 'Jan'.

For year, accept any 4 digits.

If day cannot be correct but month and year can, say: ‘Day must be a number between 1 and 31’ If month cannot be correct, by day and year can, say: ‘Month must be a number between 1 and 12’ If year cannot be correct, but day and month can, say: ‘Year must include 4 numbers’

If more than one of day, month and year cannot be correct, then combine the error messages. For example, if day and month cannot be correct, but year can say: ‘Day must be a number between 1 and 31. Month must be a number between 1 and 12.’

If day, month and year all cannot be correct, say: ‘Day must be a number between 1 and 31. Month must be a number between 1 and 12. Year must include 4 numbers.’

Highlight the day, month or year fields with the information that cannot be correct.

If the date as a whole does not exist

If the month is April, June, September, November, then check the day is between 1 and 30. If not, say ‘Day must be a number between 1 and 30 for [month]’. Highlight the day and month.

If the month is February and the year is a leap year, then check the day is between 1 and 29. If not, say ‘Day must be a number between 1 and 29 for February [year]’. Highlight the date input as a whole.

If the month is February and the year is not a leap year, then check the day is between 1 and 28. If not, say ‘Day must be a number between 1 and 28 for February [year]’. Highlight the date input as a whole.

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, ‘Date of birth 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 September 2017 when you started the course’.

Consider that the other date, in this example 1 September 2017, might be wrong instead. If this is possible, provide help to users to change this date too.

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 September 2017’.

Consider that the other date, in this example 1 September 2017, might be wrong instead. If this is possible, provide help to users to change this date too.

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 Gordon’s last exam must be the same as or before 31 August 2017 when they left school’.

Consider that the other date, in this example 31 August 2017, might be wrong instead. If this is possible, provide help to users to change this date too.

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 Gordon’s last exam must be the same as or before 31 August 2017’.

Consider that the other date, in this example 31 August 2017, might be wrong instead. If this is possible, provide help to users to change this date too.

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 2017 and 30 September 2017 when you were self-employed’.

Consider that these dates, in this example 1 September 2017 and 30 September 2017, might be wrong instead. If this is possible, provide help to users to change these dates too.

[rjmunro]

The guide at https://design-system.service.gov.uk/patterns/dates/ has a section on "relative dates", like today, tomorrow or yesterday, but doesn't show an example of how this should be done. Should it be integrated with the normal date input - e.g. click a "today" link or button and it auto-fills the date, or is it talking about using a different component completely?

I'm using a gov.uk page where I have to enter an event, including it's date with the date component. Because I'm efficient, I'll always enter it as it happens, or at worst the day after. Having to look up and re-type the date each time is really annoying.