diff --git a/docs/components/date-picker-doc.md b/docs/components/date-picker-doc.md new file mode 100644 index 00000000..149c5762 --- /dev/null +++ b/docs/components/date-picker-doc.md @@ -0,0 +1,110 @@ +--- +layout: layouts/component.njk +title: Date picker +--- + +The date picker component allows users to pick a date by entering a date or choosing from a calendar. + +{% example "/examples/search", 200 %} + +## When to use + +A date picker helps users choose a date by using a calendar view. This may help users to choose: +- a relative date - for example, last Tuesday or next Wednesday +- a date they don’t commonly use +- today’s date +- available dates only + +The calendar view is not mandatory - users can still input a date into the text field. + +## When not to use + +Do not use if users need to enter a memorable date (e.g. their date of birth) or a date they can easily look up (e.g. an appointment date on a letter they have received). Instead, use the [date input component](https://design-system.service.gov.uk/components/date-input/) from the GOV.UK Design System. + +## Similar or linked components + +The GOV.UK Design System has a [date input component](https://design-system.service.gov.uk/components/date-input/) and a [pattern for asking users for dates](https://design-system.service.gov.uk/patterns/dates/). + +## Date ranges and disabled dates + +You can set allowed date ranges if you need a user to pick a date within a date range. Individual dates and date ranges can also be disabled in the calendar view. + +Users may type unavailable or disabled dates in the input field, so error messages will be necessary. + +{% example "/examples/search", 200 %} + +## From and to dates + +Allow users to pick to and from dates by stacking 2 date pickers together. + +When stacking 2 date pickers horizontally or vertically, apply padding that is consistent with the rest of your product. + +### Vertically stacked + +Multiple date picker components can be vertically stacked. This is useful when used in vertical filters or forms. + +{% example "/examples/search", 200 %} + +### Horizontally stacked + +Multiple date picker components can be horizontally displayed. This is useful when used in horizontal filters. + +{% example "/examples/search", 200 %} + +## Errors + +Follow the guidance in the [GOV.UK Design System](https://design-system.service.gov.uk/components/error-message/) for error messages. + +{% example "/examples/search", 200 %} + +### Error messages in English and Welsh + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error stateEnglish error messageWelsh error message
If no date is entered or picked from the calendarEnter or pick a dateNodwch neu dewiswch ddyddiad
If the date entered is in the wrong formatEnter the date in the correct format, for example, 17/5/2024Rhowch y dyddiad yn y fformat cywir, er enghraifft, 17/5/2024
If the date entered does not existThe date you entered must be a real dateRhaid i'r dyddiad a roesoch fod yn ddyddiad go iawn
If the date entered is incompleteEnter a complete date, for example, 17/5/2024Nodwch ddyddiad cyflawn, er enghraifft, 17/5/2024
+ +### If you are using multiple date pickers + +Make sure you use error summaries and error messages for each text field. Even if the same errors occur for multiple date pickers. + +## Examples + +Text + +## Considerations + +Whilst the date picker is fully navigable using a keyboard, date pickers can be slow and difficult to use for keyboard only users. + +Another challenge for users, especially those with poor vision or colour blindness, is seeing the unavailable or disabled dates. + +## Contributors + +Thanks to **Dom Billington**, **Eddie Shannon**, **David Middleton**, and the **DPS Connect team** for contributing this component.