PhoneInput JAVASCRIPT UI Component API

PhoneInput Javascript API

Class

PhoneInput

The Phone Input specifies an input field where the user can enter and validate a phone number.

Determines whether the element is interactive or inactive. When enabled, the element can be interacted with by the user; when disabled, the element becomes unresponsive to user actions, often appearing visually distinct (e.g., grayed out).

Default value

false

Try a demo showcasing the disabled property.

Example

Set the disabled property.

 <smart-phone-input disabled></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.disabled = false;

Get the disabled property.

 const phoneinput = document.querySelector('smart-phone-input');

 let disabled = phoneinput.disabled;

dropDownClassListarray

Specifies extra CSS class names to be applied to the Input dropdown element, allowing for customized styling and theming beyond the default classes.

Example

Set the dropDownClassList property.

 <smart-phone-input drop-down-class-list='my-custom-input-class-name'></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.dropDownClassList = [];

Get the dropDownClassList property.

 const phoneinput = document.querySelector('smart-phone-input');

 let dropDownClassList = phoneinput.dropDownClassList;

dropDownButtonPosition"none" | "left" | "right"

Specifies the placement of the dropdown button relative to its associated element, such as positioning it to the left, right, above, or below the target UI component.

Allowed Values

"none" - The drop down button is hidden and the element acts as a simple input.
"left" - A drop down button is displayed on the left side of the element. The element acts as a DropDownList or a ComboBox depending on the readonly property.
"right" - A drop down button is displayed on the right side of the element. The element acts as a DropDownList or a ComboBox depending on the readonly property.

Default value

"none"

Try a demo showcasing the dropDownButtonPosition property.

Example

Set the dropDownButtonPosition property.

 <smart-phone-input drop-down-button-position='top'></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.dropDownButtonPosition = 'bottom';

Get the dropDownButtonPosition property.

 const phoneinput = document.querySelector('smart-phone-input');

 let dropDownButtonPosition = phoneinput.dropDownButtonPosition;

dropDownHeightstring | number

Specifies the height of the dropdown menu. By default, this property is set to an empty string, which means the dropdown's height will be determined by a corresponding CSS variable. If a specific value is provided, it will override the CSS variable and explicitly set the dropdown's height.

Default value

Example

Set the dropDownHeight property.

 <smart-phone-input drop-down-height='300'></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.dropDownHeight = 500;

Get the dropDownHeight property.

 const phoneinput = document.querySelector('smart-phone-input');

 let dropDownHeight = phoneinput.dropDownHeight;

dropDownWidthstring | number

Specifies the width of the dropdown menu. By default, this value is an empty string (""). When left empty, the dropdown's width is determined by a CSS variable, allowing the width to be managed through external stylesheets rather than being hardcoded. This provides flexibility for responsive design and consistent styling across your application. If a specific width is provided (e.g., "200px" or "50%"), it will override the CSS variable and explicitly set the dropdown's width.

Default value

Example

Set the dropDownWidth property.

 <smart-phone-input drop-down-width='300'></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.dropDownWidth = 500;

Get the dropDownWidth property.

 const phoneinput = document.querySelector('smart-phone-input');

 let dropDownWidth = phoneinput.dropDownWidth;

messagesobject

Defines or retrieves an object containing string values used throughout the widget’s user interface, allowing for easy localization of text. This property works together with the locale setting to display the widget’s content in different languages, based on the specified translations. Use this object to provide or customize all user-facing strings for multilingual support.

Default value

Example

Set the messages property.

 <smart-phone-input messages=''></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.messages = ;

Get the messages property.

 const phoneinput = document.querySelector('smart-phone-input');

 let messages = phoneinput.messages;

unlockKeystring

Sets or retrieves the unlockKey property, which serves as a unique key required to unlock access to the product. When assigning a value, the unlockKey enables authorized usage; when retrieving, it provides the current key associated with the product’s access permissions.

Default value

Example

Set the unlockKey property.

 <smart-phone-input unlock-key=''></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.unlockKey = '1111-2222-3333-4444-5555';

Get the unlockKey property.

 const phoneinput = document.querySelector('smart-phone-input');

 let unlockKey = phoneinput.unlockKey;

namestring

Defines or retrieves the value of the name attribute for the element. The name attribute uniquely identifies the element within an HTML form, allowing its data to be included and referenced when the form is submitted to a server. This is essential for processing form data on the server side.

Default value

Example

Set the name property.

 <smart-phone-input name='dropdown'></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.name = 'dropDown2';

Get the name property.

 const phoneinput = document.querySelector('smart-phone-input');

 let name = phoneinput.name;

nationalModeboolean

Specifies whether the input should be in international or national format. In international mode, the input should begin with a '+' followed by the country code (e.g., +1 555-1234). In national mode, the input should omit the '+' and country code, using only the local number format.

Default value

false

Example

Set the nationalMode property.

 <smart-phone-input national-mode></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.nationalMode = false;

Get the nationalMode property.

 const phoneinput = document.querySelector('smart-phone-input');

 let nationalMode = phoneinput.nationalMode;

openedboolean

Specifies whether the dropdown menu is currently visible (open) or hidden (closed).

Default value

false

Example

Set the opened property.

 <smart-phone-input opened></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.opened = false;

Get the opened property.

 const phoneinput = document.querySelector('smart-phone-input');

 let opened = phoneinput.opened;

onlyCountriesarray

Specifies or retrieves an array of country codes to customize the set of countries used, replacing the default list that includes all countries. Each country code must be a valid ISO 3166-1 alpha-2 code (see: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2), which consists of two uppercase letters (e.g., 'US' for the United States, 'FR' for France). Use this property to limit available options to a specific set of countries as needed.

Default value

[]

Try a demo showcasing the onlyCountries property.

Example

Set the onlyCountries property.

 <smart-phone-input only-countries='de,us'></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.onlyCountries = de,jp,us;

Get the onlyCountries property.

 const phoneinput = document.querySelector('smart-phone-input');

 let onlyCountries = phoneinput.onlyCountries;

placeholderstring

Specifies the placeholder text that appears inside the input field before the user enters any value, providing a hint or example of the expected input format.

Default value

Try a demo showcasing the placeholder property.

Example

Set the placeholder property.

 <smart-phone-input placeholder='Empty'></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.placeholder = 'Enter:';

Get the placeholder property.

 const phoneinput = document.querySelector('smart-phone-input');

 let placeholder = phoneinput.placeholder;

selectedCountrystring

Gets or sets the selected country for the element using a country code. The country code must conform to the ISO 3166-1 alpha-2 standard (see: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2), which consists of a two-letter, uppercase code representing each country (e.g., "US" for United States, "FR" for France).

Default value

Try a demo showcasing the selectedCountry property.

Example

Set the selectedCountry property.

 <smart-phone-input selected-country='de'></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.selectedCountry = 'us';

Get the selectedCountry property.

 const phoneinput = document.querySelector('smart-phone-input');

 let selectedCountry = phoneinput.selectedCountry;

rightToLeftboolean

Gets or sets a value that determines whether the element's alignment is configured for right-to-left (RTL) languages (such as Arabic or Hebrew), enabling proper display and layout of text and content for those locales.

Default value

false

Try a demo showcasing the rightToLeft property.

Example

Set the rightToLeft property.

 <smart-phone-input right-to-left></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.rightToLeft = true;

Get the rightToLeft property.

 const phoneinput = document.querySelector('smart-phone-input');

 let rightToLeft = phoneinput.rightToLeft;

themestring

Specifies the visual theme to be applied to the element. The selected theme controls the element's overall appearance, including colors, fonts, spacing, and other stylistic properties, ensuring a consistent look and feel across the user interface.

Default value

Example

Set the theme property.

 <smart-phone-input theme='blue'></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.theme = 'red';

Get the theme property.

 const phoneinput = document.querySelector('smart-phone-input');

 let theme = phoneinput.theme;

unfocusableboolean

When set to true, this property prevents the element from receiving keyboard focus, making it inaccessible via tab navigation and standard focus events.

Default value

false

Example

Set the unfocusable property.

 <smart-phone-input unfocusable></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.unfocusable = false;

Get the unfocusable property.

 const phoneinput = document.querySelector('smart-phone-input');

 let unfocusable = phoneinput.unfocusable;

valuestring

Retrieves the current value of the element or assigns a new value to it. This property can be used to access the data contained within form elements (such as input, textarea, or select) or to update their content programmatically.

Default value

Try a demo showcasing the value property.

Example

Set the value property.

 <smart-phone-input value='value1'></smart-phone-input>

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

 const phoneinput = document.querySelector('smart-phone-input');

 phoneinput.value = 'value2';

Get the value property.

 const phoneinput = document.querySelector('smart-phone-input');

 let value = phoneinput.value;

Events

changeCustomEvent

This event is triggered whenever the user modifies the current selection, such as highlighting different text or choosing another item from a selectable list. It helps you detect and respond to any change in what is selected within the relevant user interface component.

Bubbles Yes
Cancelable No
Interface CustomEvent
Event handler property onChange

Arguments

evCustomEvent

ev.detailObject

ev.detail.label - The label of the new selected item.

ev.detail.oldLabel - The label of the item that was previously selected before the event was triggered.

ev.detail.oldValue - The value of the item that was previously selected before the event was triggered.

ev.detail.value - The value of the new selected item.

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.

Example

Set up the event handler of change event.

const phoneinput = document.querySelector('smart-phone-input');
phoneinput.addEventListener('change', function (event) {
    const detail = event.detail,
        label = detail.label,
        oldLabel = detail.oldLabel,
        oldValue = detail.oldValue,
        value = detail.value;

	// event handling code goes here.
})

changingCustomEvent

This event is triggered each time a key is released (on key up) within the input field, but only if the input's value has changed as a result of the key press.

Bubbles Yes
Cancelable Yes
Interface CustomEvent
Event handler property onChanging

Arguments

evCustomEvent

ev.detailObject

ev.detail.oldValue - The previous value before it was changed.

ev.detail.value - The new value.

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.

Example

Set up the event handler of changing event.

const phoneinput = document.querySelector('smart-phone-input');
phoneinput.addEventListener('changing', function (event) {
    const detail = event.detail,
        oldValue = detail.oldValue,
        value = detail.value;

	// event handling code goes here.
})

itemClickCustomEvent

This event is triggered whenever the user selects an item by clicking on it within the popup list. It allows you to respond to user interaction by executing specific actions or updating the interface based on the selected item.

Bubbles Yes
Cancelable No
Interface CustomEvent
Event handler property onItemClick

Arguments

evCustomEvent

ev.detailObject

ev.detail.item - The item that was clicked.

ev.detail.label - The label of the item that was clicked.

ev.detail.value - The value of the item that was clicked.

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.

Example

Set up the event handler of itemClick event.

const phoneinput = document.querySelector('smart-phone-input');
phoneinput.addEventListener('itemClick', function (event) {
    const detail = event.detail,
        item = detail.item,
        label = detail.label,
        value = detail.value;

	// event handling code goes here.
})

Methods

close(): void

Closes the dropdown menu, hiding its visible options from the user and collapsing the interface element.

Invoke the close method.

const phoneinput = document.querySelector('smart-phone-input');
phoneinput.close();

Try a demo showcasing the close method.

ensureVisible(): void

Guarantees that the currently active (selected) item remains visible within the viewport by automatically scrolling the container as needed. This ensures users can always see and interact with their selection, even as the list or content changes.

Invoke the ensureVisible method.

const phoneinput = document.querySelector('smart-phone-input');
phoneinput.ensureVisible();

getNumber( isInternational?: boolean): string

Returns the provided phone number as a formatted string, applying standard formatting conventions (such as adding parentheses, spaces, or dashes) based on the specified locale or default format. Ensures consistency and improves readability for display or storage purposes.

Arguments

isInternational?boolean

When you use 'false', the national phone number will be returned and the international phone number, when you use 'true' as parameter.

Returnsstring

Invoke the getNumber method.

const phoneinput = document.querySelector('smart-phone-input');
const result = phoneinput.getNumber();

getItemByDialCode( dialCode?: string): any

Retrieves an object representing a country based on its dial code. The returned object contains the following properties:

- **label**: The local or English name of the country (e.g., "United States").
- **value**: A unique identifier for the country (commonly the country name or abbreviation).
- **iso2**: The two-letter ISO 3166-1 alpha-2 country code (e.g., "US").
- **dialCode**: The international telephone dialing code associated with the country (e.g., "+1").

Arguments

dialCode?string

Returns the national or international phone number

Returnsany

Invoke the getItemByDialCode method.

const phoneinput = document.querySelector('smart-phone-input');
const result = phoneinput.getItemByDialCode();

getSelectedItem(): any

Returns the currently selected item as an object.
This object contains the following properties:
- `label`: A string representing the display name of the item (e.g., country name).
- `value`: A string or identifier associated with the item (e.g., country code).
- `iso2`: A two-letter ISO 3166-1 alpha-2 country code string (e.g., 'US' for United States).
- `dialCode`: A string representing the country’s international dialing code (e.g., '+1').

Returnsany

Invoke the getSelectedItem method.

const phoneinput = document.querySelector('smart-phone-input');
const result = phoneinput.getSelectedItem();

isValidNumber(): boolean

Determines if the provided phone number meets the required format and validation rules, returning true for a valid phone number and false if the input is invalid.

Returnsboolean

Invoke the isValidNumber method.

const phoneinput = document.querySelector('smart-phone-input');
const result = phoneinput.isValidNumber();

validate(): void

Validates whether the entered phone number is in the correct format and meets specified criteria, such as required length, allowed characters, and country or area code compliance.

Invoke the validate method.

const phoneinput = document.querySelector('smart-phone-input');
phoneinput.validate();

open(): void

Displays the drop-down menu, making its list of selectable options visible to the user.

Invoke the open method.

const phoneinput = document.querySelector('smart-phone-input');
phoneinput.open();

Try a demo showcasing the open method.

select(): void

Enhances the behavior of an input field by selecting its text content when it is editable. If the input field is marked as readonly, it will instead focus the element without selecting the text. This ensures that users can easily interact with editable inputs, while still providing focus to readonly fields for accessibility or further actions.

Invoke the select method.

const phoneinput = document.querySelector('smart-phone-input');
phoneinput.select();

PhoneInput Javascript API

disabledboolean

Default value

Example

dropDownClassListarray

Example

dropDownButtonPosition"none" | "left" | "right"

Default value

Example

dropDownHeightstring | number

Default value

Example

dropDownWidthstring | number

Default value

Example

messagesobject

Default value

Example

unlockKeystring

Default value

Example

namestring

Default value

Example

nationalModeboolean

Default value

Example

openedboolean

Default value

Example

onlyCountriesarray

Default value

Example

placeholderstring

Default value

Example

selectedCountrystring

Default value

Example

rightToLeftboolean

Default value

Example

themestring

Default value

Example

unfocusableboolean

Default value

Example

valuestring

Default value

Example

changeCustomEvent

Arguments

evCustomEvent

ev.detailObject

ev.detail.label - The label of the new selected item.

ev.detail.oldLabel - The label of the item that was previously selected before the event was triggered.

ev.detail.oldValue - The value of the item that was previously selected before the event was triggered.

ev.detail.value - The value of the new selected item.

isDefaultPrevented

Returns

preventDefault

stopPropagation

Example

changingCustomEvent