TimePicker JAVASCRIPT UI Component API

TimePicker Javascript API

Class

TimePicker

TimePicker

Time Picker component allows the user to select time from spinners.

Selector

smart-time-picker

Properties

AanimationControls the animation mode for the component. When set to 'none', all animations are disabled. When set to other supported values, animations will be enabled according to the specified mode. This property can be used to either retrieve the current animation mode or update it dynamically.
AautoSwitchToMinutesDetermines whether, after selecting the hour, the component will automatically advance to the minute selection view. When enabled, users will be guided directly to choose minutes immediately after choosing an hour, streamlining the time selection process. This option can be set or retrieved programmatically.
DdisabledSpecifies whether the element is active and can be interacted with by the user. When enabled, the element responds to user actions; when disabled, the element appears visually inactive and does not accept user input or interaction.
FfooterSpecifies whether the footer section of the element is displayed to the user. If set to true, the footer will be visible; if false, the footer will be hidden.
FfooterTemplateSpecifies or retrieves the footer template used by the component. This property accepts either the ID of an existing HTMLTemplateElement or a direct reference to an HTMLTemplateElement object. When assigning an ID, the component will search the DOM for a template with the corresponding ID and use it as the footer template. If a direct reference is provided, that template will be used. If the value is set to null, the component will revert to its default behavior by applying an empty template to the footer area.
FformatSpecifies the format used for selecting hours, such as 12-hour (AM/PM) or 24-hour (military) time.
UunlockKeySets or retrieves the unlockKey, a unique value required to activate or grant access to the product's features. This key is used to validate and unlock product functionality.
LlocaleSpecifies or retrieves the current language setting. This property is typically used together with the messages property to determine which language version of the messages should be displayed or retrieved. When setting the language, the corresponding localized messages from the messages collection will be used.
LlocalizeFormatFunctionA callback function that allows you to customize the formatting of messages returned by the Localization Module. Use this to modify how localized text is structured, such as adding dynamic values, adjusting syntax, or applying custom formatting rules before the message is displayed to the user.
MmessagesDefines or retrieves an object containing string resources used throughout the widget interface, which can be localized to support different languages and regions. This property works in tandem with the language property to display text in the user's preferred language, enabling comprehensive internationalization of the widget's UI elements and messages.
MminuteIntervalSpecifies or retrieves the increment value (in minutes) used when adjusting or selecting the minute portion of a time input. This determines the intervals by which minutes can be increased or decreased, such as allowing selection at every 5 minutes (e.g., 0, 5, 10, 15, etc.) instead of every 1 minute.
NnameSets or retrieves the name attribute of the element. The name attribute identifies the element when submitting HTML forms, allowing its value to be included as a key in the form data sent to the server. This is essential for server-side processing and distinguishing between multiple form fields.
RreadonlyPrevents any user interactions with the element, such as clicking, tapping, focusing, or selecting content. While disabled, the element will not respond to mouse, keyboard, or touch events, and interactive features (like links or form inputs) will not be accessible.
RrightToLeftGets or sets a value that specifies whether the element is aligned to support right-to-left (RTL) languages and scripts, such as Arabic or Hebrew. When enabled, the element's alignment and layout are adjusted to accommodate right-to-left text direction for proper localization.
SselectionSpecifies which view is currently displayed to the user. By default, the hours view is initially shown unless a different view is set. This property controls the visible section of the interface, such as hours, minutes, or other available views.
TthemeSpecifies the visual theme to be applied to the element. The selected theme controls the overall appearance, including colors, fonts, and styling, ensuring a consistent look and feel for the element within the user interface.
UunfocusableWhen set to true, this property makes the element unfocusable, preventing it from receiving keyboard or mouse focus during user interaction or via scripting.
VvalueSets or retrieves the value of the element. The value can be provided as a valid Date object or as a string formatted to represent a valid time (e.g., "14:30" for 2:30 PM). When setting, ensure the input matches the expected format; when getting, the returned value will reflect the current time value of the element.
VviewDetermines the current orientation of the element, indicating whether its width is greater than its height (landscape mode) or its height is greater than its width (portrait mode). This property allows developers to adapt layout and styles based on how the element is displayed.

Events

CchangeThis event is triggered whenever the value associated with the component or input field is modified, either by user interaction or programmatically. It is dispatched after the change has occurred, allowing event handlers to respond to updates in the value.

Methods

SsetHoursSpecifies the hour component of the time value, typically as an integer ranging from 0 (midnight) to 23 (11 PM). This property or method updates the hours portion while leaving the minutes, seconds, and milliseconds unchanged, unless otherwise specified.
SsetMinutesSpecifies the value for the minutes component of a time, typically as an integer between 0 and 59. This is used to set or update the minute portion of a time-related field.

Properties

animation"none" | "simple" | "advanced"

Controls the animation mode for the component. When set to 'none', all animations are disabled. When set to other supported values, animations will be enabled according to the specified mode. This property can be used to either retrieve the current animation mode or update it dynamically.

Allowed Values

  • "none" - animation is disabled
  • "simple" - ripple animation is disabled
  • "advanced" - all animations are enabled

Default value

"advanced"

Example

Set the animation property. 

 <smart-time-picker animation='none'></smart-time-picker>

Set the animation property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.animation = 'simple';

Get the animation property. 

 const timepicker = document.querySelector('smart-time-picker');
 let animation = timepicker.animation;

autoSwitchToMinutesboolean

Determines whether, after selecting the hour, the component will automatically advance to the minute selection view. When enabled, users will be guided directly to choose minutes immediately after choosing an hour, streamlining the time selection process. This option can be set or retrieved programmatically.

Default value

false
Try a demo showcasing the autoSwitchToMinutes property.

Example

Set the autoSwitchToMinutes property. 

 <smart-time-picker auto-switch-to-minutes></smart-time-picker>

Set the autoSwitchToMinutes property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.autoSwitchToMinutes = false;

Get the autoSwitchToMinutes property. 

 const timepicker = document.querySelector('smart-time-picker');
 let autoSwitchToMinutes = timepicker.autoSwitchToMinutes;

disabledboolean

Specifies whether the element is active and can be interacted with by the user. When enabled, the element responds to user actions; when disabled, the element appears visually inactive and does not accept user input or interaction.

Default value

false

Example

Set the disabled property. 

 <smart-time-picker disabled></smart-time-picker>

Set the disabled property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.disabled = false;

Get the disabled property. 

 const timepicker = document.querySelector('smart-time-picker');
 let disabled = timepicker.disabled;

Specifies whether the footer section of the element is displayed to the user. If set to true, the footer will be visible; if false, the footer will be hidden.

Default value

false
Try a demo showcasing the footer property.

Example

Set the footer property. 

 <smart-time-picker footer></smart-time-picker>

Set the footer property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.footer = false;

Get the footer property. 

 const timepicker = document.querySelector('smart-time-picker');
 let footer = timepicker.footer;

footerTemplatestring | HTMLTemplateElement

Specifies or retrieves the footer template used by the component. This property accepts either the ID of an existing HTMLTemplateElement or a direct reference to an HTMLTemplateElement object. When assigning an ID, the component will search the DOM for a template with the corresponding ID and use it as the footer template. If a direct reference is provided, that template will be used. If the value is set to null, the component will revert to its default behavior by applying an empty template to the footer area.

Try a demo showcasing the footerTemplate property.

Example

Set the footerTemplate property. 

 <smart-time-picker footer-template='template1'></smart-time-picker>

Set the footerTemplate property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.footerTemplate = document.getElementsByTagName('template')[0];

Get the footerTemplate property. 

 const timepicker = document.querySelector('smart-time-picker');
 let footerTemplate = timepicker.footerTemplate;

format"12-hour" | "24-hour"

Specifies the format used for selecting hours, such as 12-hour (AM/PM) or 24-hour (military) time.

Allowed Values

  • "12-hour" - Shows the hours from 0 to 12 and uses AM/PM button in the header.
  • "24-hour" - Shows the hours from 0 to 23

Default value

"12-hour"
Try a demo showcasing the format property.

Example

Set the format property. 

 <smart-time-picker format='24-hour'></smart-time-picker>

Set the format property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.format = '12-hour';

Get the format property. 

 const timepicker = document.querySelector('smart-time-picker');
 let format = timepicker.format;

unlockKeystring

Sets or retrieves the unlockKey, a unique value required to activate or grant access to the product's features. This key is used to validate and unlock product functionality.

Default value

""

Example

Set the unlockKey property. 

 <smart-time-picker unlock-key=''></smart-time-picker>

Set the unlockKey property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.unlockKey = '1111-2222-3333-4444-5555';

Get the unlockKey property. 

 const timepicker = document.querySelector('smart-time-picker');
 let unlockKey = timepicker.unlockKey;

localestring

Specifies or retrieves the current language setting. This property is typically used together with the messages property to determine which language version of the messages should be displayed or retrieved. When setting the language, the corresponding localized messages from the messages collection will be used.

Default value

"en"

Example

Set the locale property. 

 <smart-time-picker locale='de'></smart-time-picker>

Set the locale property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.locale = 'fr';

Get the locale property. 

 const timepicker = document.querySelector('smart-time-picker');
 let locale = timepicker.locale;

localizeFormatFunctionfunction | null

A callback function that allows you to customize the formatting of messages returned by the Localization Module. Use this to modify how localized text is structured, such as adding dynamic values, adjusting syntax, or applying custom formatting rules before the message is displayed to the user.

Example

Set the localizeFormatFunction property. 

 <smart-time-picker localize-format-function='function(defaultMessage, message, messageArguments){return '...'}'></smart-time-picker>

Set the localizeFormatFunction property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.localizeFormatFunction = function(defaultMessage, message, messageArguments){return '...'};

Get the localizeFormatFunction property. 

 const timepicker = document.querySelector('smart-time-picker');
 let localizeFormatFunction = timepicker.localizeFormatFunction;

messagesobject

Defines or retrieves an object containing string resources used throughout the widget interface, which can be localized to support different languages and regions. This property works in tandem with the language property to display text in the user's preferred language, enabling comprehensive internationalization of the widget's UI elements and messages.

Default value




"en": {

"propertyUnknownType": "'{{name}}' property is with undefined 'type' member!",

"propertyInvalidValue": "Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!",

"propertyInvalidValueType": "Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!",

"elementNotInDOM": "Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.",

"moduleUndefined": "Module is undefined.",

"missingReference": "{{elementType}}: Missing reference to {{files}}.",

"htmlTemplateNotSuported": "{{elementType}}: Browser doesn't support HTMLTemplate elements.",

"invalidTemplate": "{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."

}

Example

Set the messages property. 

 <smart-time-picker messages='{"de":{"propertyUnknownType":"Die Eigenschaft '{{name}}' hat ein nicht definiertes 'type'-Member!","propertyInvalidValue":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualValue}}, Erwarteter Wert: {{value}}!","propertyInvalidValueType":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualType}}, Erwarteter Wert: {{type}}!","elementNotInDOM":"Element existiert nicht in DOM! Bitte fugen Sie das Element zum DOM hinzu, bevor Sie eine Methode aufrufen.","moduleUndefined":"Modul ist nicht definiert.","missingReference":"{{elementType}}: Fehlender Verweis auf {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser unterstutzt keine HTMLTemplate-Elemente.","invalidTemplate":"{{elementType}}: '{{property}}' Die Eigenschaft akzeptiert eine Zeichenfolge, die mit der ID eines HTMLTemplate-Elements aus dem DOM ubereinstimmen muss."}}'></smart-time-picker>

Set the messages property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.messages = {"en":{"propertyUnknownType":"'{{name}}' property is with undefined 'type' member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Module is undefined.","missingReference":"{{elementType}}: Missing reference to {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser doesn't support HTMLTemplate elements.","invalidTemplate":"{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."}};

Get the messages property. 

 const timepicker = document.querySelector('smart-time-picker');
 let messages = timepicker.messages;

minuteIntervalnumber

Specifies or retrieves the increment value (in minutes) used when adjusting or selecting the minute portion of a time input. This determines the intervals by which minutes can be increased or decreased, such as allowing selection at every 5 minutes (e.g., 0, 5, 10, 15, etc.) instead of every 1 minute.

Default value

1
Try a demo showcasing the minuteInterval property.

Example

Set the minuteInterval property. 

 <smart-time-picker minute-interval='5'></smart-time-picker>

Set the minuteInterval property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.minuteInterval = 15;

Get the minuteInterval property. 

 const timepicker = document.querySelector('smart-time-picker');
 let minuteInterval = timepicker.minuteInterval;

namestring

Sets or retrieves the name attribute of the element. The name attribute identifies the element when submitting HTML forms, allowing its value to be included as a key in the form data sent to the server. This is essential for server-side processing and distinguishing between multiple form fields.

Default value

""

Example

Set the name property. 

 <smart-time-picker name='time'></smart-time-picker>

Set the name property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.name = 'timepicker';

Get the name property. 

 const timepicker = document.querySelector('smart-time-picker');
 let name = timepicker.name;

readonlyboolean

Prevents any user interactions with the element, such as clicking, tapping, focusing, or selecting content. While disabled, the element will not respond to mouse, keyboard, or touch events, and interactive features (like links or form inputs) will not be accessible.

Default value

false

Example

Set the readonly property. 

 <smart-time-picker readonly></smart-time-picker>

Set the readonly property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.readonly = false;

Get the readonly property. 

 const timepicker = document.querySelector('smart-time-picker');
 let readonly = timepicker.readonly;

rightToLeftboolean

Gets or sets a value that specifies whether the element is aligned to support right-to-left (RTL) languages and scripts, such as Arabic or Hebrew. When enabled, the element's alignment and layout are adjusted to accommodate right-to-left text direction for proper localization.

Default value

false
Try a demo showcasing the rightToLeft property.

Example

Set the rightToLeft property. 

 <smart-time-picker right-to-left></smart-time-picker>

Set the rightToLeft property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.rightToLeft = true;

Get the rightToLeft property. 

 const timepicker = document.querySelector('smart-time-picker');
 let rightToLeft = timepicker.rightToLeft;

selection"hour" | "minute"

Specifies which view is currently displayed to the user. By default, the hours view is initially shown unless a different view is set. This property controls the visible section of the interface, such as hours, minutes, or other available views.

Allowed Values

  • "hour" - Shows the hours view.
  • "minute" - Shows the minutes view.

Default value

"hour"
Try a demo showcasing the selection property.

Example

Set the selection property. 

 <smart-time-picker selection='minute'></smart-time-picker>

Set the selection property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.selection = 'hour';

Get the selection property. 

 const timepicker = document.querySelector('smart-time-picker');
 let selection = timepicker.selection;

themestring

Specifies the visual theme to be applied to the element. The selected theme controls the overall appearance, including colors, fonts, and styling, ensuring a consistent look and feel for the element within the user interface.

Default value

""

Example

Set the theme property. 

 <smart-time-picker theme='blue'></smart-time-picker>

Set the theme property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.theme = 'red';

Get the theme property. 

 const timepicker = document.querySelector('smart-time-picker');
 let theme = timepicker.theme;

unfocusableboolean

When set to true, this property makes the element unfocusable, preventing it from receiving keyboard or mouse focus during user interaction or via scripting.

Default value

false

Example

Set the unfocusable property. 

 <smart-time-picker unfocusable></smart-time-picker>

Set the unfocusable property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.unfocusable = false;

Get the unfocusable property. 

 const timepicker = document.querySelector('smart-time-picker');
 let unfocusable = timepicker.unfocusable;

valueany

Sets or retrieves the value of the element. The value can be provided as a valid Date object or as a string formatted to represent a valid time (e.g., "14:30" for 2:30 PM). When setting, ensure the input matches the expected format; when getting, the returned value will reflect the current time value of the element.

Default value

new Date()

Example

Set the value property. 

 <smart-time-picker value='new Date(2020, 0, 1, 20, 33)'></smart-time-picker>

Set the value property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.value = '12:30';

Get the value property. 

 const timepicker = document.querySelector('smart-time-picker');
 let value = timepicker.value;

view"landscape" | "portrait"

Determines the current orientation of the element, indicating whether its width is greater than its height (landscape mode) or its height is greater than its width (portrait mode). This property allows developers to adapt layout and styles based on how the element is displayed.

Allowed Values

  • "landscape" - The header is positioned next to the time selection area.
  • "portrait" - The header is positioned above the time selection area.

Default value

"portrait"
Try a demo showcasing the view property.

Example

Set the view property. 

 <smart-time-picker view='portrait'></smart-time-picker>

Set the view property by using the HTML Element's instance. 

 const timepicker = document.querySelector('smart-time-picker');
 timepicker.view = 'landscape';

Get the view property. 

 const timepicker = document.querySelector('smart-time-picker');
 let view = timepicker.view;

Events

changeCustomEvent

This event is triggered whenever the value associated with the component or input field is modified, either by user interaction or programmatically. It is dispatched after the change has occurred, allowing event handlers to respond to updates in the value.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onChange

Arguments

evCustomEvent
ev.detailObject
ev.detail.oldValue - The old value before it was changed presented as a Date object.
ev.detail.value - The new value presented as a Date object.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the change event.

Example

Set up the event handler of change event. 

const timepicker = document.querySelector('smart-time-picker');
timepicker.addEventListener('change', function (event) {
    const detail = event.detail,
        oldValue = detail.oldValue,
        value = detail.value;

	// event handling code goes here.
})

Methods

setHours( hours: number): void

Specifies the hour component of the time value, typically as an integer ranging from 0 (midnight) to 23 (11 PM). This property or method updates the hours portion while leaving the minutes, seconds, and milliseconds unchanged, unless otherwise specified.

Arguments

hoursnumber

The hours to set.


Invoke the setHours method.

const timepicker = document.querySelector('smart-time-picker');
timepicker.setHours(5);

Try a demo showcasing the setHours method.

setMinutes( minutes: number): void

Specifies the value for the minutes component of a time, typically as an integer between 0 and 59. This is used to set or update the minute portion of a time-related field.

Arguments

minutesnumber

The minutes to set.


Invoke the setMinutes method.

const timepicker = document.querySelector('smart-time-picker');
timepicker.setMinutes(5);

Try a demo showcasing the setMinutes method.

CSS Variables

--smart-time-picker-default-widthvar()

Default value

"var(--smart-editor-width)"

smartTimePicker default width

--smart-time-picker-default-heightvar()

Default value

"calc(12 * var(--smart-editor-height))"

smartTimePicker default height