Date picker
Allows users to enter or select a date.
Examples
Usage
Use a date picker when users need to enter or select a specific date.
Do:
- show the expected date format in the help text
- let users enter the date into the field manually as well as selecting it from the calendar
- show a clear error message when a date is invalid or cannot be used and explain how to correct it
- only restrict date choices when there is a clear reason to do so
- explain why users cannot select a date when this may not be obvious
- use separate date pickers for a start and end date when users need to enter a date range
- show an error if the end date is earlier than the start date
- clearly show the selected start and end dates
Avoid:
- pre-populating the field with a date unless there is a good reason to expect users to choose that date
References
Nielsen Norman Group
Date-Input Form Fields: UX Design Guidelines
Parameters for turas-date-picker
- asp-for - Binds the date picker to a model property
- guidance-text - Provides guidance text for the user
- field-column-widths - Sets the column width for the date picker
- additional-classes - Allows adding custom CSS classes
- hide-today-button - Hides the button to select today's date
- hide-clear-button - Hides the button to clear the selected date
- hide-validation-message - Suppresses validation messages
- readonly - Makes the date picker read-only
- asp-is-disabled - Disables the date picker
- hide-label - Hides the label for the date picker
Close without saving
Are you sure you want to close without saving?
Any information you have entered will be lost!
Testing
Check that the date picker:
- allows users to navigate the calendar using only the keyboard (arrow and tab keys to navigate, ESC to close and return to select date)
- allows users to enter a date using only the keyboard
- shows a visible focus state on the input and calendar controls
- focus moves logically in and out of the calendar
- announces the label, role and selected date correctly with screen readers
- hint text or instructions are read out (for example, formatting guidance) by screen readers
- provide date format guidance, for example dd/mm/yyyy
- communicates unavailable dates or date ranges clearly
- calendar button has an accessible name
- error messages are announced by screen readers and associated with the date picker
- input does not trigger unexpected changes while typing or clicking on the calendar component
- required fields are clearly communicated
- remains usable at 400% zoom and supports reflow without horizontal scrolling
- behaves consistently across supported browsers and devices
Developer considerations
When using the date picker component in your form:
- always provide a visible label using <label for=""> and an ID
- ensure the date picker has a programmatic name (via label or aria-labelledby)
- use aria-describedby to associate hint text and error messages with the date picker
- write error messages that explain what went wrong and how to fix it
- do not rely on placeholder text as a label
- ensure the control works without JavaScript where possible
- avoid blocking manual typing
- ensure a visible focus state that meets contrast requirements
- allow text resizing and reflow without losing functionality
- avoid auto-submitting or triggering unexpected changes while typing
- ensure sufficient touch target size and spacing, with a target size of at least 24 × 24 CSS pixels
Required fields
If your form contains fields that users must complete:
- clearly indicate when the date picker is required by using a visual indicator such as an asterisk
- do not rely on the visual indicator alone (for example, an asterisk) to communicate that a field is required and include the help text “Required fields are marked with an asterisk *” at the top of every page of the form
- ensure the required state of the date picker is programmatically available to assistive technologies using aria-required="true"