Date picker usage guidelines

Date picker allows users to enter or select a date and time value.

When to use

• Use when an exact date and a specific time of day must be selected.
• Use when a date range must be selected.

When not to use

• If users need to choose from a limited set of known dates or time slots, using radio buttons or a select will ensure quicker and precise selection
• Use number field when user needs to select a relative date like “2 days from today”

Usage

Preview

Date of birth

mm/dd/yyyy

Code

import { DatePicker } from '@cimpress-ui/react';

export default function Demo() {
  return <DatePicker label="Date of birth" granularity="day" />;
}

Formatting and layout

Placement

Date pickers should be left-aligned to the other form fields. Make sure the container is wide enough to fit the date and time. When placed along with other components such as form fields, use the same width for all the form fields. When two date pickers are used together such as in a date range, they can be horizontally or vertically aligned.

Calendar popup

The calendar popup has a fixed width. The popup should be right-aligned with the date picker component.

Spacing

• Date pickers should have at least 16px of horizontal and vertical spacing between them and other elements.

Form alignment

Date pickers can be used in forms alongside other form components (such as single select, checkboxes, and radio buttons). Two date picker components stacked vertically or horizontally should always be aligned, and should have the same height and width.

Do

Name

Date of birth

mm/dd/yyyy

Don't

Name

Date of birth

mm/dd/yyyy

Content writing

Label

• Always provide a label to guide users on what to enter.
• Do use a short description of just one or two words for the label such as “Date and time”.
• Do not format labels in the form of a question such as “Which dates are you looking for?”
• Do not include verbs in your label such as “Enter date and time”.

Description text

• Do provide description text whenever the label might not be enough context for a user to understand the purpose of the date picker.
• Do not provide unnecessary description text when the purpose of the date picker is obvious.
• Do write clear and concise description text. Text should be limited to one sentence.
• End the description text with a period or equivalent punctuation mark. This helps screen reader users understand where the description ends, and it improves readability for all users.

Error text

• Do provide clear and concise error messaging.
• Do explain the issue and let the user know what they need to do to resolve it. Error messages should always provide users with a solution or a path to resolving the error.
• Error messages should use language that is easily understood rather than complex technical terms.
• End the error message with a period or equivalent punctuation mark. This helps screen reader users understand where the error message ends, and it improves readability for all users.

Behaviors

Calendar popup

Press the calendar icon on the right to open the calendar popup. The calendar popup remains open until a date is selected or focus is removed from the popup.

Selecting a date

A date can be selected from the calendar popup, or by manually entering it in the date picker field. The field is divided into segments, with each segment acting as a number input. For date ranges, two separate date pickers should be used - one for the start date and one for the end date.