Date Picker

Overview

Date pickers let a user enter a date or select one from the calendar pop-up.

Other names: Calendar, Date Input

Behaviors

Focus

A focus state replaces the browser default focus state for date pickers. The border also changes color on focus.

Text field

Users enter a value by typing in the text field. Date pickers use input masks that only allow for characters that match what is expected. A date picker should tell the user what the expected date format is.

A calendar icon is inside the text box to the right to show it's a date picker.

Calendar pop-up

Selecting the calendar icon inside the text field opens a pop-up that allows users to pick a date. Users can choose the month and year using the lefthand menu, or by selecting the header. There is also a text button Today that inputs the current date.

A filled circle indicates the selected day. The current date is selected by default. Once the user picks a date, the pop-up closes. When re-opened, today’s date is a different color if the user chose another day.

The calendar does not allow users to select a date outside the range that the date picker was configured for.

Input masking

When typing in the date picker, each section of the value has an input mask to prevent characters that don't match the expected format. The date picker allows only numbers. For example, users must type 1 or 01 for January.

After a user completes a section, focus should jump to the next section. For example, when a user enters a month the focus jumps to the day, then the year.

Error

Error states in a date picker change the color of the border and displays an error message below the field. When the error condition is fixed, the border returns to normal and the error message is immediately removed.

Disabled

When disabled, the date picker field is displayed at 50% opacity. The field and icons cannot be clicked, focused, or interacted with in any way.

Help text

Date picker labels can give extra context or instructions using a help text component.

This appears as a question mark icon to the right of the label.

Instructional text

Instructional text appears below the date picker. It should only be used for very short messages. If more instruction is needed, use help text.

Accessibility

To activate the Kendo calendar using a keyboard, use alt-down arrow.

Usage guidelines

Date format

As outlined in the formatting guidelines, date pickers follow a "month/day/year" format. After entering a valid date with that format, the text field should translate it to a more legible state that is easier to scan and understand. Focusing on the text field returns it to the original format to make editing easier.

Example: 01/03/2002 would be changed to January 3, 2022.

Content guidelines

Label A date picker label should be short — no more than a few words. The label should indicate what will happen on the date the user selects.

👍
Try this

Start Day

Scan Date

Instructional Text You can give more guidance in instructional text, like the earliest and latest date. This helps prevent errors.

👍
Try this

Choose a date after January 1, 1990.

Choose a date between 1/1/1900 and 12/31/2099.

Choose a date before December 31, 2099.

Help Text If there are longer instructions that could give users more context, use help text. Don’t use help text for information that the user needs to know to be successful, like the format.

👍
Try this
This is the date the next batch of computers will update.

❗️
Not this
Month/Day/Year

Error Message Error text appears below the date picker. The message should be short, but it can wrap if it's wider than the field. It should be concise and jargon-free. Be specific to what went wrong and tell the user how to move forward.

👍
Try this

You need to pick a date after 1/1/1900.

You can't pick a date after December 31, 2099.

The selected date must be between 01/01/2023 and 12/31/2023.