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
Name Type Default Required Bindable Description
id text req Stable id used as the national input id and as the id-prefix for the dropdown.
value text '' bind Bindable E.164 value. Defaults to an empty string.
country 'AC''AD''AE''AF''AG''AI''AL''AM''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' bind Bindable selected country. Defaults to 'US'.
countries readonly 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.
hideLabel boolean false Visually hide the rendered label 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.
onchange (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.