Forms

PhoneInput

Combines localized country metadata, calling codes, formatting, validation, and E.164 output.

View preview API reference View in Figma

FrameworksAstro · React · Elements

Registry commandlumen add PhoneInput

InteractionNative markup

Design sourceLinked component node

See it and copy it

Framework example

Choose Astro, React, or Elements to compare native usage against the shared visual output. Each example assumes the framework-level setup is already complete.

Phone number

Small

Large

Disabled

Read only

Field error

Check this contact number.

+576015550123

View PhoneInput code

Framework usage

Switch targets to compare the adapter code. This live preview runs the Astro example. React and Elements use their own behavior APIs; complete the matching framework setup before copying an example.

---
import { Label, PhoneInput, PhoneNumber } from '@santi020k/lumen-astro'
import { getLumenPhoneCountry, resolveLumenPhoneNumber } from '@santi020k/lumen-core'

const colombia = getLumenPhoneCountry('CO', { locale: 'en-US' })

if (!colombia) throw new Error('Missing Colombia phone metadata')

const contact = resolveLumenPhoneNumber(colombia, '+576015550123')
---

<div style="display: grid; gap: 1rem; width: 100%; max-width: 24rem;">
  <div>
    <Label for="ex-phone">Phone number</Label>
    <PhoneInput countryValue="CO" id="ex-phone" name="phone" placeholder="601 5550123" locale="en-US" required />
  </div>
  <div>
    <Label for="ex-phone-sm">Small</Label>
    <PhoneInput countryValue="GB" id="ex-phone-sm" name="phone-sm" placeholder="Mobile number" visualSize="sm" />
  </div>
  <div>
    <Label for="ex-phone-lg">Large</Label>
    <PhoneInput countryValue="ES" id="ex-phone-lg" name="phone-lg" placeholder="Work number" visualSize="lg" value="612345678" />
  </div>
  <div>
    <Label for="ex-phone-disabled">Disabled</Label>
    <PhoneInput countryValue="CO" disabled id="ex-phone-disabled" name="phone-disabled" value="6015550123" />
  </div>
  <div>
    <Label for="ex-phone-readonly">Read only</Label>
    <PhoneInput countryValue="CO" id="ex-phone-readonly" name="phone-readonly" readOnly value="6015550123" />
  </div>
  <div>
    <Label for="ex-phone-error">Field error</Label>
    <PhoneInput countryValue="CO" errorMessage="Check this contact number." id="ex-phone-error" name="phone-error" value="601" />
  </div>
  <PhoneNumber value={contact} link />
</div>

import { Label, PhoneInput, PhoneNumber } from '@santi020k/lumen-react'

import { getLumenPhoneCountry, resolveLumenPhoneNumber } from '@santi020k/lumen-core'

const colombia = getLumenPhoneCountry('CO', { locale: 'en-US' })

if (!colombia) throw new Error('Missing Colombia phone metadata')

const contact = resolveLumenPhoneNumber(colombia, '+576015550123')

export const Example = () => (
  <>
    <div style={{ "display": "grid", "gap": "1rem", "width": "100%", "maxWidth": "24rem" }}>
      <div>
        <Label htmlFor="ex-phone">Phone number</Label>
        <PhoneInput defaultCountryValue="CO" id="ex-phone" name="phone" placeholder="601 5550123" locale="en-US" required />
      </div>
      <div>
        <Label htmlFor="ex-phone-sm">Small</Label>
        <PhoneInput defaultCountryValue="GB" id="ex-phone-sm" name="phone-sm" placeholder="Mobile number" visualSize="sm" />
      </div>
      <div>
        <Label htmlFor="ex-phone-lg">Large</Label>
        <PhoneInput defaultCountryValue="ES" id="ex-phone-lg" name="phone-lg" placeholder="Work number" visualSize="lg" defaultValue="612345678" />
      </div>
      <div>
        <Label htmlFor="ex-phone-disabled">Disabled</Label>
        <PhoneInput defaultCountryValue="CO" disabled id="ex-phone-disabled" name="phone-disabled" defaultValue="6015550123" />
      </div>
      <div>
        <Label htmlFor="ex-phone-readonly">Read only</Label>
        <PhoneInput defaultCountryValue="CO" id="ex-phone-readonly" name="phone-readonly" readOnly defaultValue="6015550123" />
      </div>
      <div>
        <Label htmlFor="ex-phone-error">Field error</Label>
        <PhoneInput defaultCountryValue="CO" errorMessage="Check this contact number." id="ex-phone-error" name="phone-error" defaultValue="601" />
      </div>
      <PhoneNumber value={contact} link />
    </div>
  </>
)

<script type="module">
  import { defineLumenElements } from '@santi020k/lumen-elements/define'

  defineLumenElements()
</script>

<div style="display: grid; gap: 1rem; width: 100%; max-width: 24rem;">
  <div>
    <lumen-label for="ex-phone">Phone number</lumen-label>
    <lumen-phone-input country-value="CO" id="ex-phone" name="phone" placeholder="601 5550123" locale="en-US" required></lumen-phone-input>
  </div>
  <div>
    <lumen-label for="ex-phone-sm">Small</lumen-label>
    <lumen-phone-input country-value="GB" id="ex-phone-sm" name="phone-sm" placeholder="Mobile number" visual-size="sm"></lumen-phone-input>
  </div>
  <div>
    <lumen-label for="ex-phone-lg">Large</lumen-label>
    <lumen-phone-input country-value="ES" id="ex-phone-lg" name="phone-lg" placeholder="Work number" visual-size="lg" value="612345678"></lumen-phone-input>
  </div>
  <div>
    <lumen-label for="ex-phone-disabled">Disabled</lumen-label>
    <lumen-phone-input country-value="CO" disabled id="ex-phone-disabled" name="phone-disabled" value="6015550123"></lumen-phone-input>
  </div>
  <div>
    <lumen-label for="ex-phone-readonly">Read only</lumen-label>
    <lumen-phone-input country-value="CO" id="ex-phone-readonly" name="phone-readonly" read-only value="6015550123"></lumen-phone-input>
  </div>
  <div>
    <lumen-label for="ex-phone-error">Field error</lumen-label>
    <lumen-phone-input country-value="CO" error-message="Check this contact number." id="ex-phone-error" name="phone-error" value="601"></lumen-phone-input>
  </div>
  <PhoneNumber value={contact} link/>
</div>

Edit PhoneInput in browser

Framework differences

React: Use defaultCountryValue and defaultValue for initial values. Controlled value and onValueChange use the structured LumenPhoneNumber contract.

Choose your target

Add this component

Choose the package for your runtime. All adapters share the Lumen stylesheet. Use the matching registry command when you want a local wrapper for that framework.

pnpm add @santi020k/lumen-astro

pnpm add @santi020k/lumen-astro

lumen add PhoneInput

lumen add PhoneInput

pnpm add @santi020k/lumen-react

pnpm add @santi020k/lumen-react

lumen add PhoneInput --target react

lumen add PhoneInput --target react

pnpm add @santi020k/lumen-elements

pnpm add @santi020k/lumen-elements

lumen add PhoneInput --target elements

lumen add PhoneInput --target elements

API reference

Lumen-specific props and runtime attributes for the Astro primitive. Use the framework differences above and the copyable examples for React composition and Elements attributes; the public adapter types define their supported contracts.

Attribute	Values	Default	Description
id / input-id	string	Generated	Associates a visible label with the number input; Web Components use input-id.
inputProps	input attributes	-	Passes native number-input attributes without DOM patches.
inputRef	React ref	-	Exposes the native number-input ref.
disabled / readOnly / required	boolean	false	Locks both controls when disabled or read-only and supports native required validation.
errorMessage / showValidationError	string / boolean	- / true	Shows an associated field error or metadata validation feedback.
countries	Array<string \| { label, value, disabled? }>	International metadata	Overrides the generated country choices for legacy or specialized forms.
countryOptions	LumenPhoneCountry[]	Generated metadata	Overrides localized country metadata while retaining formatting and E.164 behavior.
countryName	string	"country"	Sets the name of the country dial-code select.
countryLabel	string	"Country code"	Sets the accessible label for the dial-code select.
countryValue	ISO region or calling code	"US"	Selects the initial country by region or calling code.
locale	string \| string[]	Runtime locale	Localizes generated country names.
name	string	"phone"	Sets the name of the telephone number input.
placeholder	string	"Phone number"	Sets the placeholder for the number input.
value	string (Astro / Elements) \| LumenPhoneNumber (React)	Uncontrolled	Sets the national input value; React accepts the structured phone-number contract.
onValueChange	(value: LumenPhoneNumber) => void	-	Receives formatting, validity, and E.164 changes in React.
size	"default" \| "sm" \| "lg"	"default"	Controls the height and font size of both controls.
class, className	string	""	Merges custom classes with the generated ui-* root classes.
...native attributes	HTML attributes	-	Forwards standard attributes to the root element unless the component consumes them.

Framework example

Add this component

API reference

Help improve PhoneInput