Forms

PhoneInput

A production-grade international phone input component with smart paste handling, country-specific formatting, and E.164 output. Accepts all major formats (E.164, International, National) and cleans them up automatically. Designed for healthcare applications where reliable patient contact data is critical.

Basic Usage

Standard phone input with country selector. Value is always emitted in E.164 format (+14155551234) for consistent storage.

Phone Number

Smart Paste — Try It

Paste any of these formats into the input. The component auto-detects country and normalizes the value. For formats with country code (+1, +44), country is auto-detected. For national-only formats (e.g. UK 020...), select the country first, then paste. Click to copy, then paste into the field below.

Paste here

With Validation

Use validatePhoneInternational() for real-time validation. Empty is allowed; invalid/partial numbers show an error.

Contact Phone

With Success State

Show successMessage when the number is valid. Use validateOnMount to display success immediately without requiring blur.

Verified Phone

Healthcare — Patient Contact

Patient contact form with phone icon, validation, and clearable. Ideal for intake forms and appointment scheduling.

Patient Phone

Sizes

Choose the appropriate size for your form density.

Small

Medium

Large

Hint Visibility

By default, hint text appears only when the field is focused. Use alwaysShowHint to keep it permanently visible — ideal for required credentials or important context. The ? icon is automatically hidden when the text is already shown.

Default (focus to see hint)

Always visible hint

Required with persistent hint

Disabled

Use when the field is not editable (e.g. verified contact on file).

Verified Phone

Usage with Form

When name is provided, the component renders a hidden input that submits the E.164 value. The visible input is for display/typing only.

<form onsubmit={handleSubmit}>
  <PhoneInput
    label="Contact Phone"
    name="phone"
    bind:value={phone}
    error={phoneError}
    defaultCountry="US"
  />
  <button type="submit">Submit</button>
</form>
// Form data will include phone: "+14155551234" (E.164)

Props

Prop	Type	Default	Description
`label`	`string`	'Phone'	Label text for the field
`value`	`string`	''	E.164 format value (bindable)
`name`	`string`	—	Form field name — submits E.164 via hidden input
`error`	`string`	—	Error message to display
`successMessage`	`string`	—	Success message when valid (shows green border)
`hint`	`string`	—	Helper text — shown below on focus by default, always visible with alwaysShowHint
`alwaysShowHint`	`boolean`	false	Always show hint text below the input (not just on focus). Hides the ? icon when enabled.
`required`	`boolean`	false	Marks field as required
`disabled`	`boolean`	false	Disables the input
`defaultCountry`	`CountryCode`	'US'	Default country when empty (e.g. US, GB)
`size`	`'sm' \| 'md' \| 'lg'`	'md'	Input size
`clearable`	`boolean`	false	Show clear button when has value
`iconLeft`	`Snippet`	—	Icon to display on the left (e.g. Phone)
`hideLabel`	`boolean`	false	Hide label visually (still accessible)
`validateOnMount`	`boolean`	false	Show validation state immediately
`alwaysShowFooter`	`boolean`	false	Always render the footer area to prevent layout shift when hint or validation messages appear dynamically.
`testId`	`string`	—	Test ID for e2e (Playwright, Cypress)
`oninput`	`() => void`	—	Called on input
`onblur`	`(e: FocusEvent) => void`	—	Called on blur
`onchange`	`(value: string) => void`	—	Called when E.164 value changes
`onclear`	`() => void`	—	Called when clear button is clicked

Exported Utilities

Function	Description
`validatePhoneInternational(phone, defaultCountry?)`	Returns error message or undefined. Use for form validation.
`parsePhoneForInput(phone, defaultCountry?)`	Parse raw string to object with country and nationalNumber.
`formatNationalWithCountry(digits, country)`	Format digits for display (country-specific).
`toE164(country, nationalDigits)`	Build E.164 string from country + national number.
`normalizeToE164(phone)`	Normalize any format to E.164 for storage.
`getCountryOptions()`	List of countries for custom selectors.

Supported Formats (Paste & Type)

• E.164: +14155551234, +442071234567
• International: +1 415 555 1234, +44 20 7123 4567
• National: (415) 555-1234, 020 7123 4567
• Digits only: 4155551234 (interpreted in selected country)
• With separators: 415-555-1234, 415.555.1234
• Trunk prefix: 0 20 7123 4567 (UK) — stripped automatically

Healthcare Best Practices

• E.164 storage: Always store phone numbers in E.164 for consistency and interoperability
• Forgiving input: Accept various formats — 89% of users ignore format examples (UX research)
• Country detection: When pasting +44..., the component auto-switches to UK
• Validation: Use validatePhoneInternational() for form submission
• autocomplete="tel": Enables mobile numeric keypad and browser autofill
• Clear labeling: Use "Mobile phone" or "Contact number" for clarity in patient forms

Accessibility

• ARIA: aria-label, aria-invalid, aria-errormessage, aria-required
• Keyboard: Escape clears when clearable; full tab order
• Screen readers: Country and number fields properly labeled
• inputmode="numeric": Optimizes mobile keyboard