Getting started

@telixon/web-sdk binds the core input controller to a DOM <input> element. It ships no CSS and no image assets; rendering stays yours.

Install

pnpm add @telixon/web-sdk @telixon/core

Create a phone input

import { ensureEngineReady } from '@telixon/core';
import { createPhoneInput } from '@telixon/web-sdk';

await ensureEngineReady();

const input = document.querySelector('input');
if (!(input instanceof HTMLInputElement)) throw new Error('input element not found');

const phoneInput = createPhoneInput({
  mode: 'national',
  input,
  defaultRegion: 'US',
});

phoneInput.subscribe((state) => {
  state.value; // formatted value currently in the input
  state.region; // resolved region, or null
  state.validationError; // structured error, or null
});

createPhoneInput requires a ready engine and an <input> of type="text" or type="tel". One phone input attaches per element; a second createPhoneInput on the same element throws.

Editing

The adapter drives the input through its native editing intents: typing, deletion in both directions, word and line deletion, selection replacement, cut, paste, drop, and IME composition. The caret stays correct through every reformat, and the platform’s own undo and redo gestures run through the controller’s history.

Modes

mode: 'national' formats in the national convention of defaultRegion, which this mode requires.

mode: 'international' resolves the region from the digits. The calling code is part of the value by default; display controls how it appears:

• display: { callingCodeInInput: true, plusPrefix } keeps the calling code inside the value. plusPrefix is 'none' (no plus), 'fixed' (a permanent plus), or 'erasable' (a plus the user can delete and retype). Omitting display means { callingCodeInInput: true, plusPrefix: 'none' }.
• display: { callingCodeInInput: false } keeps the calling code out of the value and requires a defaultRegion.

const phoneInput = createPhoneInput({
  mode: 'international',
  input,
  display: { callingCodeInInput: true, plusPrefix: 'fixed' },
});

State

Every change emits a PhoneInputState with value, region, selectionStart, selectionEnd, regionFilter, numberTypeFilter, placeholder, and validationError. The adapter writes value and the caret range to the DOM; the rest is data for your rendering.

The initial state is applied to the DOM at construction and not emitted to subscribers; call getState() after subscribe to read it.

placeholder carries an example number for the resolved region, shaped by the active mode and display configuration. The placeholderNumberType option selects which number type the example represents; the default is 'MOBILE'.

Controller methods

setValue, setRegion, undo, redo, canUndo, canRedo, clearHistory, getState, getPhoneNumber, setRegionFilter, setNumberTypeFilter, and destroy. getPhoneNumber() builds a PhoneNumber from the current digits, the same interface parsePhoneNumber returns. Call destroy() when the input leaves the DOM; it detaches all listeners and clears subscribers.

Next steps

• The web-sdk reference lists the full API surface, including createRegionList and regionToFlagEmoji for region pickers.
• The core reference documents the PhoneNumber returned by getPhoneNumber().