Timezone Picker
Last updated
Last updated
Do you need users to pick a timezone as part of an interactive flow? With the Timezone Picker, Symphony users can easily select a timezone from a selection of possible values. It recognises both cities and countries so the user can quickly filter and find the right timezone.
The Timezone Picker is represented by the <timezone-picker> tag, as you can see in the examples at the bottom of the page.
You can see below the designs of the timezone picker.
For a list of all the available elements, refer to Elements.
Attribute | Type | Required? | Description |
| String | Yes | Identifies the timezone picker. |
| String Restricted to the tz database timezones + empty string | No | Timezone displayed by default when the user receives or resets the form. Please note that if it is not defined by the developer, the value will be based on the user's browser setting. You need to enter value="" to enforce the timezone to be empty. |
| String (accepting | No | The description that will be displayed when clicking the tooltip icon located on top of the timezone picker Element. |
| String | Not required but it is recommended if | Definition of the label that will be displayed on top of the timezone picker Element. |
| Boolean (true or false) | No | If |
| String | No | Specifies a short hint in the timezone picker input. Accepts any string value but is overridden by the value if a value is defined: it will show only if value attribute is enforced to empty. Please note that a default placeholder is displayed as: "Choose a timezone". |
| Array of Strings | No | Items can be disabled from the timezone picker list so that the user cannot pick them. See the examples below for more details. Important: single quote Please note that if you want to propose only a list of a few timezones to the users, then a simple dropdown menu might be more adequate. |
For the purpose of accessibility, Symphony users can interact with the timezone picker via their keyboard:
First, using "Tab" to enter the component
Using "Enter", "Arrow-up", or "Arrow-down" to open the timezone list
Using "Arrow-up" and "Arrow-down" to navigate in the list
Using any key to erase the field and write in it
Using "Enter" to set the selected timezone and close the list
Using "Escape" to keep pre-selected value and close the list
Finally using "Tab" to exit the component
The max length of any timezone picker attribute is 256 characters except disabled-timezone attribute which max length is set to 1024 characters.
All timezone values are displayed in English only.
You can add a default timezone in your text field by including it in the value parameter. Please note that unlike the placeholder text, the default timezone will be sent in the formReply when the form is submitted if not edited by the user.
Please note that if the default timezone (value attribute) matches a value from the disabled-timezone array, then the value is left empty.
The timezone-picker will be supported on the following versions of clients:
20.14 for Client 2.0
20.13 for Client 1.5 (a beta version is released in Client 20.12 for Client 1.5)
When the value attribute is not defined by the developer, please note that the default value will be based on the user's browser setting.
If you want however to force the default value to be displayed as empty for the user when sending the form, please enforce value="" in the messageML.
The following examples show the timezone picker being used as follows:
The first timezone-picker (init) shows how to display an empty timezone-picker ("With empty default value"). Note in the messageML sent the value was enforced to empty with value="".
The second timezone-picker (specific_value) shows how to display, by default, a value specifically chosen by the developer. Note that the default value would have been sent to the payload if it had not been deleted before submitting the form. You can see how users can remove a pre-selected value from the timezone-picker, thanks to the cross on the right side of the input.
The third timezone-picker (default_value) shows how to display, by default, the user browser timezone value. Note that the default value is sent to the payload when submitting the form.
The fourth timezone-picker (placeholder) shows how a placeholder text ("Only Placeholder") is displayed in the timezone-picker. Please note the placeholder text is not sent in the payload if no value has been chosen by the enduser.
The fifth timezone-picker (label) shows how a label text ("My Label") is displayed.
The sixth timezone-picker (tooltip) shows how a title text ("My Tooltip/n With a second line") is inserted in the UI under the (i) icon, and how the text entered in the title parameter is displayed when the enduser clicks on the icon.
The seventh timezone-picker (noreq) shows how a user can interact with a non-required field. Even if the field is empty (only a placeholder text is present but does not count as a value), it does not prevent the user from submitting the form.
The eighth timezone-picker (req) shows the behavior of the unique required field of the form, which cannot be submitted in case it is not filled; an error is displayed under the field in case the user submits the form with this field as empty.
The ninth timezone-picker (disabled) shows how users interact with disabled values from the timezone-picker.
Main features introduced | Agent needed to parse message sent by the bot | Client 2.0 release | Backward client-compatibility behavior (e.g. external rooms) |
Beta version | 20.12 | Not supported | |
Initial release | 20.12 | 20.14 | Not supported (except for 20.12 client 1.5) |
The possible values of the timezone-picker are restricted to the Canonical values of the tz database.
Please note in the examples above that the values are displayed to users according to the following rules:
The country name only is displayed if it has a single timezone (see Israel)
A list of cities are displayed under their country title if this country has multiple timezones (see United States of America)
