Input Time Zone | Calcite Design System

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.

Sample

Usage

Choosing a time zone

Accessibility

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 \| undefined`
label	label	Specifies an accessible label for the component.	`string \| undefined`
labelText	label-text	Specifies the component's label text.	`string \| undefined`
maxItems	max-items	Specifies the component's maximum number of options to display before displaying a scrollbar.	`number`	`0`
messageOverrides		Replace localized message strings with your own strings. Note: Individual message keys may change between releases.	`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 \| undefined`
offsetStyle	offset-style	When `mode` is `"offset"`, specifies how the offset will be displayed. `"user"` uses `UTC` or `GMT` depending on the user's locale. `"gmt"` always uses `GMT`. `"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. `"absolute"` works for most cases - positioning the component inside of overflowing parent containers, which affects the container's layout. `"fixed"` is used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.	`OverlayPositioning`	`"absolute"`
placeholder	placeholder	Specifies placeholder text for the component.	`string \| undefined`
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 \| undefined`
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 \| undefined`
validationMessage	validation-message	Specifies the validation message to display under the component.	`string \| undefined`
validityread-only		The component's current validation state.	`ValidityState`
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 \| undefined`

Slots

Name	Description
label-content	A slot for rendering content next to the component's `labelText`.

Styles

Name	Description
--calcite-input-time-zone-corner-radius	Specifies the component's corner radius.

Events

Name	Description	Behavior
calciteInputTimeZoneBeforeClose	Fires when the component is requested to be closed and before the closing transition begins.	bubblescomposed
calciteInputTimeZoneBeforeOpen	Fires when the component is added to the DOM but not rendered, and before the opening transition begins.	bubblescomposed
calciteInputTimeZoneChange	Fires when the component's `value` changes.	bubblescomposed
calciteInputTimeZoneClose	Fires when the component is closed and animation is complete.	bubblescomposed
calciteInputTimeZoneOpen	Fires when the component is opened and animation is complete.	bubblescomposed

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`
setFocus	Sets focus on the component.	`setFocus(options?: FocusOptions): Promise<void>`