Input Time Zone is an input-driven component containing a list of worldwide time zones.
Overview
Input Time Zone enables a user to select a time zone. Where no value is provided, the user's time zone will be selected by default.
Usage
- Choosing a time zone
Sample
Accessibility
Keyboard navigation
| Key | Function |
|---|---|
Tab | Moves focus in and out of the component. |
Tab and Shift | Moves focus in and out of the component. |
Arrow down | When the component is not open, opens the component. When open, focus shifts to the next value. |
Arrow up | When the component is open, focus shifts to the previous value. |
Home | When the component is open, focus shifts to the first value. |
End | When the component is open, focus shifts to the last value. |
Esc | When the component is open, closes the component and shifts focus back to the input. |
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
| clearable | clearable | When true, an empty value (null) will be allowed as a value.
When false, an offset or name value is enforced, and clearing the input or blurring will restore the last valid value. | boolean | false |
| disabled | disabled | When true, prevents interaction and decreases the component's opacity. | boolean | false |
| form | form | Specifies the id of the component's associated form.
When not set, the component is associated with its ancestor form element, if one exists. | string | |
| labelText | label-text | Specifies the component's label text. | string | |
| maxItems | max-items | Specifies the component's maximum number of options to display before displaying a scrollbar. | number | 0 |
| messageOverrides | Overrides individual strings used by the component. | Record<string, unknown> | undefined | ||
| mode | mode | This specifies the type of value and the associated options presented to the user:
Using "offset" will provide options that show timezone offsets.
Using "name" will provide options that show the IANA time zone names. | TimeZoneMode | "offset" |
| name | name | Specifies the name of the component. Required to pass the component's value on form submission. | string | |
| offsetStyle | offset-style | When mode is "offset", specifies how the offset will be displayed, where
"user" uses UTC or GMT depending on the user's locale,
"gmt" always uses GMT, and
"utc" always uses UTC. | OffsetStyle | "user" |
| open | open | When true, displays and positions the component. | boolean | false |
| overlayPositioning | overlay-positioning | Specifies the type of positioning to use for overlaid content, where:
"absolute" works for most cases - positioning the component inside of overflowing parent containers, which affects the container's layout, and
"fixed" is used to escape an overflowing parent container, or when the reference element's position CSS property is "fixed". | OverlayPositioning | "absolute" |
| readOnly | read-only | When true, the component's value can be read, but controls are not accessible and the value cannot be modified. | boolean | false |
| referenceDate | reference-date | This date will be used as a reference to Daylight Savings Time when creating time zone item groups.
It can be either a Date instance or a string in ISO format ("YYYY-MM-DD", "YYYY-MM-DDTHH:MM:SS.SSSZ"). | Date | string | |
| scale | scale | Specifies the size of the component. | Scale | "m" |
| status | status | Specifies the input field's status, which determines message and icons. | Status | "idle" |
| topLayerDisabled | top-layer-disabled | When true and the component is open, disables top layer placement.
Only set this if you need complex z-index control or if top layer placement causes conflicts with third-party components. | boolean | false |
| validationIcon | validation-icon | Specifies the validation icon to display under the component. | IconName | boolean | |
| validationMessage | validation-message | Specifies the validation message to display under the component. | string | |
| validity | The component's current validation state. | MutableValidityState | ||
| value | value | The component's value, where the value is the time zone offset or the difference, in minutes, between the selected time zone and UTC. If no value is provided, the user's time zone offset will be selected by default. | string |
Slots
| Name | Description |
|---|---|
| label-content | A slot for rendering content next to the component's labelText. |
Events
| Name | Description | Behavior |
|---|---|---|
| calciteInputTimeZoneBeforeClose | Fires when the component is requested to be closed and before the closing transition begins. | |
| calciteInputTimeZoneBeforeOpen | Fires when the component is added to the DOM but not rendered, and before the opening transition begins. | |
| calciteInputTimeZoneChange | Fires when the component's value changes. | |
| calciteInputTimeZoneClose | Fires when the component is closed and animation is complete. | |
| calciteInputTimeZoneOpen | Fires when the component is opened and animation is complete. |
Methods
| Name | Description | Signature |
|---|---|---|
| componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<this> |
| setFocus | Sets focus on the component. | setFocus(options?: FocusOptions): Promise<void> |