Upgrade Guide - v1 to v2

UI Elements v2.0.0 shows time zones in one format across every Element. Each label is built from the city, the time zone abbreviation and the UTC offset, taken from the Unicode Common Locale Data Repository (CLDR).

No options have been removed or renamed, so v1 configuration keeps working. The version is major because what your users see changes, and so do some values your callbacks receive. Check each section below against your integration before upgrading.

Time zone labels #

The time zone dropdown in the Date Time Picker and Availability Rules, and the time zone shown in the Availability Viewer, use the new format:

• When CLDR has no abbreviation for a time zone in the chosen locale, the abbreviation is left out, as in Tokyo, +09:00.
• UTC and fixed offsets are shown as UTC, +00:00.
• Labels are localized, for example Nueva York, -05:00 in Spanish and Berlin, MEZ +01:00 in German.
• In the Availability Viewer, the time zone moves below the legend.
• Vancouver, Edmonton and Winnipeg are added to the default time zone list, as they no longer keep the same time as their US neighbors over the winter.

If you style the dropdown options with custom CSS, the city and abbreviation are now in a {PREFIX}__timezone-selector--option-name element and the offset in a {PREFIX}__timezone-selector--option-offset element, replacing the <strong> around the city.

Time zone abbreviations next to slots #

The abbreviation next to each slot in the Date Time Picker now comes from CLDR, so it always agrees with the dropdown. Where CLDR has no abbreviation, the slot shows the UTC offset instead, for example +09:00 for Tokyo, where v1 showed JST.

config.display_slot_timezone now accepts these values:

• abbreviation_or_offset (default, also true): the abbreviation, or the UTC offset when there isn’t one.
• only_abbreviation: the abbreviation, or nothing when there isn’t one.
• never (also false): nothing.

An unsupported value logs a warning and falls back to abbreviation_or_offset.

English locales #

• en is now international English: 24 hour times and the day before the month, as in Tuesday 3 November, 14:00. In v1, en used US formats. If you pass locale: "en" and want US formats, pass locale: "en-US" instead.
• en-US uses US formats, as in Tuesday November 3, 2:00 PM, and US time zone abbreviations such as EST and PST.
• en-GB uses British time zone abbreviations such as GMT, BST and CET. In v1, en-GB showed the same abbreviations as en.

When no locale is given, the Elements still follow the browser’s language setting.

12 hour times now keep the space before AM and PM, as in 9:00 AM. The Availability Viewer previously showed 9:00AM.

Renamed time zones #

Time zones that have been renamed, such as Europe/Kiev to Europe/Kyiv and Asia/Calcutta to Asia/Kolkata, are replaced by their current identifier:

• A renamed identifier in tzid or config.tz_list is shown and selected as the current one.
• A config.tz_list containing both the old and the current identifier lists the time zone once.
• Callbacks return the current identifier, so a tzid of Europe/Kiev comes back as Europe/Kyiv.

If you store the tzid returned by a callback and compare it with your own records, treat the old and current identifiers as the same time zone.