Date picker

Date picker in Storybook

note

This component is being reworked. There will be a new version aligned with the latest guidelines in upcoming releases.

Usage

The date picker enables users to select a date. It consists of a text entry field with a dropdown calendar entry screen.

Anatomy

Date pickers consist of the following elements:

1. Field label: provides the title for the date picker. Labels should be clear and concise, and should specify the purpose of the selection.
2. Input field: text input field where users can type in the date. This field includes placeholder text that models the correct date format.
3. Calendar icon: indicates to users that this is a date field. Users click on the icon to display a calendar dropdown menu and select a date.
4. Dropdown calendar: the menu where users select a date.
5. Month and year selection: enables users to navigate dates in the past or future.
6. Month pagination: enables users to move forward or backward, one month at a time.
7. Selected day: the day that the user has clicked on.

Best practices

• Date pickers must include labels that describe the purpose of the selection.
• Date format by default appears as month/day/year. Adjust the date format depending on location. Some countries, for example, use the format day/month/year.
• Field labels should include the date format in the form of help text. This text can either appear inline or below the label. Including only the date format as placeholder text increases cognitive burden.
• Date format is automated when a user selects from the calendar menu.
• Calendar menus are not ideal for picking dates in the distant past or future, such as birthdates. In these cases, use the text field instead.

Responsiveness/Adaptiveness

• The date picker is responsive for all devices.
• On tablet and mobile, the text input field shrinks to accommodate reduced screen real estate.

Interactions

Text input field

Users can enter dates into the text input field using their keyboards. When users begin typing in the text input field, the placeholder text disappears. This response underscores the need to include permanent help text.

Calendar menu

• Clicking on the calendar icon opens the calendar dropdown menu.
• When users click on a date from the calendar dropdown menu, the date appears highlighted.
• The month pagination controls enable users to move through past and future months.
• In the calendar menu, users can also select month and year by clicking on the chevrons.

Error conditions

Clearly mark invalid fields. When there is more than one field, indicate which field is triggering the error.

UX writing considerations

• Text input fields should not rely solely upon placeholder text.
• When using the text input field, include the date format as permanent help text. Date format can appear inline in parentheses with the label, or below the label.
• Labels for text input fields should be clear and concise, and should specify the use case (for example, "date of birth").
• Keep in mind that not all regions use the same format for dates. Europe, for instance, follows the model of day/month/year. Ensure that placeholder text accurately reflects locale.

Accessibility

Jutro's Date picker component is built on the React datepicker library. It comprises an input field and a calendar widget.

• Screen reader interaction: Users are informed of the pre-populated date value when they tab to the datepicker input field, and that this value is currently selected. The date can be entered manually from this input field. While focus remains on the pre-populated date, a calendar widget is also available. Users can also move focus into the widget by pressing the down arrow key. Navigation through the calendar portion of the widget is accomplished via the arrow keys, and the value currently in focus is voiced by screen readers via a WAI-ARIA aria-label attribute. The 'Previous', 'Month', 'Year' and 'Next' buttons are focusable via the TAB key when the widget is open. React datepicker does not currently enable keyboard navigation to the 'Today' link.
• Keyboard interaction: A calendar widget appears when the user tabs to the datepicker input field. The current date is highlighted and keyboard-only users can enter the date manually here. Users can also place keyboard focus on the widget by pressing the down arrow key when it is expanded. Navigate through the calendar with the arrow keys. 'Previous', 'Month', 'Year' and 'Next' buttons are focusable via the TAB key when the widget is open.
• Color: The contrast ratio of textual elements against their background is at or above 4.5:1, as per WCAG 2.0 AA requirements.
• Zoom: All content is visible and functional up to and including a zoom factor of 200%.

note

This component is being reworked. There will be a new version aligned with the latest guidelines in upcoming releases.

Code

The DateField is used to select a specfic date. There are two ways to provide input, by typing in the date manually or selecting the date from a dropdown calendar. Valid formats for typing in the date are ISO format, YYYY-MM-DD, or MM/DD/YYYY.

Implementation

The DateField has the same props as other field components, with additional date-specific props.

• You can limit the range of dates to select from using the minDate and maxDate props
• The dataType prop determines the format of the returned value from the date picker. The returned value can be an object, a string, or in date-time format
• You can change the text of the "today" button using todayButtonText, or hide it completely by setting hideTodayButton to true
• showCalendar controls whether or not the calender input is active. Set it to false to limit the input to keyboard entry only
• Set openWithIconOnly to true to make the calendar dropdown open only when the icon is clicked, instead of when the input field is clicked
• Use displayFormat to set how the date will be displayed in readonly format. The options are:
  • vshort: 01/01/2022
  • short: Jan 01, 2022
  • long: January 01, 2022
  • abbreviated: Sat, Jan 01, 2022
  • full: Saturday, January 01, 2022
• The format of the date input used for masking is generated by default using your locale. You can change this using the inputFormat prop, but note that this is not recommended

Layout

For all resolutions, the input is displayed horizontally. On desktop and tablet the field is displayed in a grid layout, using two fractions of available space. On mobile the input is compressed to fit the size of the screen.

Auto mask

Date components automatically get a mask that contains separators and matches the selected locale. If you want the mask to disappear when typing, set noMask to true.

warning

Auto masking does not work when the vshort format is applied. There is a console warning about this.

Known issue

There is a known issue with the calendar dropdown in the DateField.

When clicking the input for the first time and then proceeding to click on either the month or the year dropdowns, the earliest month/year option available is displayed instead of months/years that are nearer to the current date. This issue only occurs on the first click, clicking a second time will result in the expected behavior.

This issue is caused by the external library that the DateField uses, and therefore cannot be fixed by the Jutro team. We recomend limiting the date range offered by DateField using the minDate and maxDate props. For more information about this issue, see the official issue thread.