Date and time picker

Date and time 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 and time picker is an input field that allows you to select dates and time through textual input or interaction with a calendar and time options overlay. It is one of the most frequently used elements in forms.

Anatomy

Date and time 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 and backward, one month at a time.
7. Selected day: the day that the user has clicked on.
8. Time select: column within the dropdown menu with list of times.

Best practices

• Date and time pickers must include labels that describe the purpose of the selection.
• Date and time format, by default, uses month/day/year and the 12-hour clock.
• Adjust date and time format depending on location. Some countries, for example, use the format day/month/year and the 24-hour clock.
• Field labels should include the date and time format in the form of help text. This text can either appear inline or below the label. Including only the date and time format as placeholder text increases cognitive burden.
• The expected date format suggestion should be visible when the user activates the input field.
• When users begin typing in the text input field, the placeholder text disappears. This response underscores the need to include permanent help text.
• Date and time format are automated when selecting from the calendar menu.
• Include the current day so that users won't need to access a calendar for today's date.
• The transition between day, month, and year should happen automatically, without any effort from the user.
• Keep the delimiters displayed as the user manually inputs the date.
• 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 and time 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 and times into the text input field using their keyboards.

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 cycle through past and future months.
• In the calendar menu, users can also select month and year by clicking on the chevrons.
• The time select column appears within the calendar dropdown menu. Users can select a time by scrolling up or down within the column and clicking on the time.

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 and time format as permanent help text. Date and time 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 and time of policy activation").
• Keep in mind that not all regions use the same format for dates and times. Europe, for example, uses day/month/year and the 24-hour clock. 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, a calendar widget, a time picker and a 'Today' link.

• 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 calendar 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 as, for example, "Choose the 1st of January 2021". 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 time picker section nor 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

DateTimeField is used to select date and time. It consists of two separate inputs. One for choosing date and another one for choosing time.

Implementation

In general DateTimeField uses the same props as standard field component.

• Props (disabled, readOnly, labelPosition and custom classes) are shared between the two fields, meaning that if the prop disabled is set to true, the fields is disabled.

• Most of the field props (like label, hideLabel and required) are applied to date component along with its specific props (format, minDate, maxDate). Equivalent props for time component are suffixed with Time (like labelTime, hideLabelTime and requiredTime). The time specific props are:

  • timeInterval determine the time interval between values on list.
  • timeFormat determine time format. It can be 12h or 24h. If not defined, the time format is determined based on the current locale.

• The DateTimeField also accepts the inputformat prop, which can be used to format the date and time.

• The dataType prop determine format of returned value.

• It is important to note that the DateTimeField returned value is always in UTC.

• Displayed values are in the user's local timezone. You can override this by passing defaultTimeZone to localeSettings in src/config/config.json. If you do, the displayed dates are in timezone from the defaultTimeZone setting.

Layout

For desktop and tablet, when the label is set to be shown on the top, the field is displayed in a grid layout, using three fractions of available space. Two fractions for date picker and one fraction for time picker. In any other situation the fields is stacked vertically.

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.

Usage in metadata

{
    "id": "datetime",
    "type": "field",
    "component": "DateTime",
    "componentProps": {
        "path": "path.toBeUsed"
    }
}