Forms

PhoneInput

International phone-number input pairing a country-code dropdown with an as-you-type national number input and emitting E.164 values.

import { PhoneInput } from '@lostgradient/cinder/phone-input';
formphone
01

Overview

International phone-number input pairing a country-code dropdown with an as-you-type national number input and emitting E.164 values.

Usage

svelte 
<script lang="ts">
  import PhoneInput from '@lostgradient/cinder/phone-input';
  let phone = $state('');
</script>

<PhoneInput id="phone" bind:value={phone} label="Phone number" />
Live preview
02

When to use

Use when
  • Collecting an international phone number that must be stored in a canonical E.164 form.
  • Letting the user pick a calling country and a national number side-by-side.
Avoid when
  • Collecting a free-form local number with no country context — use input type="tel" instead.
  • Collecting an SMS verification code — use pin-input instead.
03

Examples

Basic phone input

Country selector plus national number with E.164 emission.

Country switching

Narrowed country allow-list — typed digits reformat when the user switches countries.

With error message

Error state surfaces a message and marks both controls invalid.

04

Props

Props for phone-input
NameTypeDefaultDescription
id required text Stable id used as the national input id and as the id-prefix for the dropdown.
value bindable text '' Bindable E.164 value. Defaults to an empty string.
country bindable 'AC''AD''AE''AF''AG''AI''AL''AM'
237 more members 'AO''AR''AS''AT''AU''AW''AX''AZ''BA''BB''BD''BE''BF''BG''BH''BI''BJ''BL''BM''BN''BO''BQ''BR''BS''BT''BW''BY''BZ''CA''CC''CD''CF''CG''CH''CI''CK''CL''CM''CN''CO''CR''CU''CV''CW''CX''CY''CZ''DE''DJ''DK''DM''DO''DZ''EC''EE''EG''EH''ER''ES''ET''FI''FJ''FK''FM''FO''FR''GA''GB''GD''GE''GF''GG''GH''GI''GL''GM''GN''GP''GQ''GR''GT''GU''GW''GY''HK''HN''HR''HT''HU''ID''IE''IL''IM''IN''IO''IQ''IR''IS''IT''JE''JM''JO''JP''KE''KG''KH''KI''KM''KN''KP''KR''KW''KY''KZ''LA''LB''LC''LI''LK''LR''LS''LT''LU''LV''LY''MA''MC''MD''ME''MF''MG''MH''MK''ML''MM''MN''MO''MP''MQ''MR''MS''MT''MU''MV''MW''MX''MY''MZ''NA''NC''NE''NF''NG''NI''NL''NO''NP''NR''NU''NZ''OM''PA''PE''PF''PG''PH''PK''PL''PM''PR''PS''PT''PW''PY''QA''RE''RO''RS''RU''RW''SA''SB''SC''SD''SE''SG''SH''SI''SJ''SK''SL''SM''SN''SO''SR''SS''ST''SV''SX''SY''SZ''TA''TC''TD''TG''TH''TJ''TK''TL''TM''TN''TO''TR''TT''TV''TW''TZ''UA''UG''US''UY''UZ''VA''VC''VE''VG''VI''VN''VU''WF''WS''XK''YE''YT''ZA''ZM''ZW'
 'US' Bindable selected country. Defaults to 'US'.
countries PhoneInputCountryCode[] Optional allow-list constraining which countries appear in the dropdown.
locale text BCP-47 locale used to resolve Intl.DisplayNames. Defaults to the nearest LocaleProvider locale, then navigator.language after mount and 'en-US' during SSR.
label text Visible group label rendered above the controls.
labelVisible boolean true Whether the label is visibly rendered. Set false to visually hide it while keeping it programmatically associated.
description text Optional description text rendered below the controls.
error text Optional error message; sets aria-invalid="true" on the inputs.
disabled boolean Disable every control and the hidden input.
required boolean Mark the group as required for assistive technology.
name text Form-control name applied to the hidden <input> that submits with the form.
onValueChange (detail: PhoneInputChange) => void Fires only for user-initiated committed value changes (editing the national number, switching the country). Never fires for external value or country synchronization. The detail object carries the E.164 string on detail.value.