Date with time zone

Date with time zone in Storybook

note

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

Usage

Overview

The date with time zone component enables users to input a date, time, and time zone when completing a form.

Anatomy

The date with time zone component consists of the following elements:

1. Date picker: enables the user to input a particular date into a form.

2. Time picker: enables the user to input a particular time into a form.

3. Time zone picker: enables the user to input a particular time zone into a form.

Best practices

• The date with time zone component should only be used when the use case warrants it.

• Do not leave the time or the time zone fields empty. If the user only needs to specify a date, see the date picker component.

• Set defaults wherever possible to prevent errors.

• Set formatting help, wherever possible, to prevent errors and enable faster data entry.

Interactions

Each of the elements that make up this component have their own interaction patterns and associated behaviors.

For date picker interactions, refer to the date picker component.

1. Time picker

   a. When the user selects the time control, text entry is enabled. Alpha-numeric text is accepted in the field. Users may enter numeric time values and the alphabetic abbreviations AM/PM.

   b. The separators, as dictated by the required time format, will be added automatically.

   c. A dropdown with preformatted time intervals will be enabled, from which users may also choose a specific time.

   d. All standard interaction patterns for the dropdown component will apply here.

2. Time zone picker

   a. When the user selects the time zone control, text entry is enabled. Only alphabetic text is accepted in the field to enable entry of time zones.

   b. A dropdown with preformatted time zones will be enabled, from which users may choose a specific time zone.

   c. All standard interaction patterns for the dropdown component will apply here.

UX writing considerations

• Field labels should be clear, concise, and specify the use case.

  • Labels appear above the input fields and are left-aligned.

  • Use sentence case for field labels.

• When representing the date as a numeric value or label, best practice is to use ISO Standard 8601: YYYY-MM-DD.

note

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

Code

Date Time Zone Field is a component that consists of three different fields: date, time and time zone. It is essentially the same as a Date Time Field, but it also allows the user to assign a time zone to the selected value.

Implementation

• It takes the same props as the Date Time Field component, and includes showTimeZone, timeZoneLabel, timeZoneSecondaryLabel, timeZoneTooltip, timeZoneHideLabel, timeZones and defaultTimeZone.

• Most of the field props (like disabled, readOnly and required) are shared between the three fields, meaning that if the prop disabled is set to true, the fields shown will all be disabled.

• There are, however, a set of field properties (label, secondaryLabel, tooltip, placeholder and hideLabel) that will be applied individually for each subcomponent: the ones with no prefix are assigned to the date time component and the ones with a prefix are applied to the time zone input (e.g. timeZoneLabel, timeZoneSecondaryLabel, etc.).

• The value prop consists of an object containing a datetime property, that contains a date shape exactly like the one used in the Date and Date Time fields, and a timezone property that specifies the current or selected IANA time zone. It is important to note that the datetime value will always be in UTC, with the offset of the timezone. Example:

  {
    "datetime": dateShape,
    "timezone": "Europe/Berlin"
  }

• The Time Zone field will always have a value, which will be the user's current time zone if none is provided. It can be overridden with the prop defaultTimeZone using a IANA value or setting defaultTimeZone from localeSettings in src/config/config.json.

• The prop timeZones can be used to specify the time zones that will be displayed in the time zone, it consists of an array of IANA codes. If the user's time zone is not part of the provided list, it will be appended and also displayed in the dropdown.

Layout

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

Usage in metadata

The component can be used in metadata as displayed in this example:

{
  "id": "datetimezone",
  "type": "field",
  "component": "DateTimeZone",
  "componentProps": {
    "path": "path.toBeUsed"
  }
}