Props

All props are passed directly to the <TelInput> component. Props marked bindable support Svelte’s bind: syntax.

Core props

Prop	Type	Default	Bindable	Description
value	string	''	Yes	E.164 formatted phone number (e.g. +36301234567). Source of truth for storage.
country	CountryCode | null	null	Yes	ISO 3166 Alpha-2 country code (e.g. 'HU', 'US'). Auto-detected from value when not set.
valid	boolean	true	Yes	Whether the current input is a valid phone number.
validationError	ValidationError	null	Yes	Granular reason when valid is false. See ValidationError.
detailedValue	DetailedValue | null	null	Yes	Full parsed result with multiple formats. See DetailedValue.
el	HTMLInputElement	—	Yes	Reference to the underlying <input> element.
defaultCountry	CountryCode | null	null	No	Country to restore when api.reset() is called. If not set, reset clears country to null.
initialFormat	'international' | 'national'	'international'	No	Controls how the phone number is displayed on initial render and on externally-driven value changes. 'national' strips the dial code from the visible input while keeping value in E.164.
placeholderFormat	'international' | 'national'	undefined	No	Controls the format of the auto-generated placeholder (when autoPlaceholder is enabled). Falls back to initialFormat when not set. See placeholderFormat.
options	TelInputOptions	{}	No	Configuration object. See Options.
validateProps	boolean	false	No	When true, runs runtime type-checking on incoming props and throws a descriptive TypeError on a mismatch. Off by default so it adds nothing to production bundles — enable it during development to catch malformed props early.

HTML input props

Forwarded to the underlying <input type="tel">:

Prop	Type	Default	Description
id	string	Auto-generated	Sets the id attribute.
name	string | null	null	Sets the name attribute.
class	string	''	CSS class(es) applied to the input.
disabled	boolean	false	Disables the input and the parser.
readonly	boolean | null	null	Makes the input read-only.
required	boolean | null	null	Marks the input as required. Empty input = invalid.
placeholder	string | null	null	Custom placeholder. Overrides autoPlaceholder.
size	number | null	null	HTML size attribute.
autocomplete	string | null	null	HTML autocomplete attribute (e.g. 'tel').

Any other standard HTML input attributes are spread onto the element — including aria-* attributes.

Bindable props in detail

value

Always stored in E.164 format — the international standard. Example: +12154567890.

<script>
  let phoneNumber = $state('');
</script>

<TelInput bind:value={phoneNumber} />
<p>Stored: {phoneNumber}</p>

country

Accepts any ISO 3166 Alpha-2 country code. Auto-detection behavior:

• value is +44... and country not set → auto-detects GB
• country explicitly set → used for formatting and validation
• User types a different dial code → country updates to match (unless lockCountry is true)

valid

Behavior depends on validateOn and required:

Input state	required not set	required set
Empty	true	false
Partial / invalid	false	false
Valid number	true	true

validationError

When valid is false, this tells you why:

Error	Meaning
'REQUIRED'	Empty input with required set
'TOO_SHORT'	Not enough digits
'TOO_LONG'	Too many digits
'NOT_A_NUMBER'	Doesn’t look like a phone number
'INVALID_COUNTRY'	Country code not recognized
'INVALID_LENGTH'	Length doesn’t match any valid pattern
'COUNTRY_NOT_ALLOWED'	Country not in allowedCountries
'INVALID'	Fallback
null	No error (valid)

defaultCountry

Country to restore when api.reset() is called without { country: true }:

<TelInput defaultCountry="US" bind:country bind:value />

<!-- reset() restores country to 'US', not null -->

initialFormat

Controls how the phone number is displayed on initial render and whenever the value prop is changed externally by a parent component.

Value	Display	value binding
'international' (default)	+1 215 456 7890	+12154567890
'national'	215 456 7890	+12154567890

The stored value is always E.164 regardless of this setting. initialFormat only affects what the user sees in the input field. So the original format does not affect how the user chooses to enter the phone number; the user can type it in any format (national or international).

Example — show national format on load:

<script>
  let phone = $state('+12154567890');
  let country = $state('US');
</script>

<!-- Input shows "215 456 7890", but phone.value stays "+12154567890" -->
<TelInput
  bind:value={phone}
  bind:country
  initialFormat="national"
/>

External value changes re-apply initialFormat: if the parent sets value programmatically (e.g. via a preset button), the display is updated in the requested format — not left in whatever state the user had reached.

placeholderFormat

Controls the format of the auto-generated example placeholder shown when the input is empty (requires autoPlaceholder: true in options, which is the default).

placeholderFormat	initialFormat	Resulting placeholder
not set	not set / 'international'	+1 201 555 0123
not set	'national'	201 555 0123
'international'	any	+1 201 555 0123
'national'	any	201 555 0123

Priority rule: placeholderFormat always wins when explicitly set. When omitted, initialFormat is used as the fallback.

This lets you decouple the placeholder appearance from how the value is initially displayed:

<!-- Show value in national format, but placeholder in international format -->
<TelInput
  bind:value
  bind:country
  initialFormat="national"
  placeholderFormat="international"
/>

<!-- Show value in international format, but placeholder without the dial code -->
<TelInput
  bind:value
  bind:country
  initialFormat="international"
  placeholderFormat="national"
/>

Note

The placeholder is only shown when the input is empty and autoPlaceholder is enabled. Setting options={{ autoPlaceholder: false }} or providing a custom placeholder prop disables auto-generation entirely — placeholderFormat has no effect in those cases.

Accessibility

aria-invalid is automatically set to "true" when valid is false. You can override it explicitly if needed. All aria-* attributes pass through to the input element.