Phone numbers, one file.

<script src="https://cdn.jsdelivr.net/gh/vanilla-ui-kit/components/phone/phone.js"></script>
new PhoneInput('#phone', { country: 'ae' })

new PhoneInput('#basic', {
  country: 'us',
  onChange: v => show(v)   // {e164, national, country, valid}
})

new PhoneInput('#preferred', {
  country: 'ae',
  preferredCountries: ['ae','sa','kw','qa','bh','om']
})

// typing '+9715…' switches the flag to 🇦🇪
// longest-prefix match, +1/+7/+44 area-aware

new PhoneInput('#a', { validate: 'blur' })  // Maz-style
new PhoneInput('#b', { validate: 'live',
  onValidityChange: ok => … })

<div id="form-phone"></div>
new PhoneInput('#form-phone', { name: 'phone' })
// <input type="hidden" name="phone" value="+9715…">

new PhoneInput('#a', { nationalMode: true })
// shows  050 123 4567
new PhoneInput('#b', { nationalMode: false })
// shows  +971 50 123 4567

---

API reference

Complete reference for PhoneInput v1.0.0, generated from the component source (phone.js) and README. Zero dependencies; UMD (browser global, CommonJS, AMD); SSR-safe — constructing without a DOM returns an inert handle, and the pure helpers work in Node.

• Constructor & usage
• Options
• Instance methods
• Statics & helpers
• Events & callbacks
• Declarative init
• Theming
• Accessibility

Constructor & usage

var phone = new PhoneInput(target, options)   // or PhoneInput.create(target, options)

target is a CSS selector string or a DOM element. Two modes, decided by the target's tag:

• Anchor mode — target is an <input>: the input is adopted in place (wrapped in the .vph control, coerced to type="tel", given the vph-input class). destroy() unwraps and restores it.
• Container mode — target is any other element: the whole control, including its own tel input, is built inside it; with options.name a hidden input carrying the E.164 value is added for form submission.

• Throws Error('PhoneInput: target element not found: …') when the selector matches nothing.
• Re-initializing on an element that already has an instance destroys the old instance first.
• Without a DOM (SSR/Node) the constructor returns an inert no-op handle with the same method surface.
• A pre-filled input value is adopted on init; a leading-+ value also switches the country from its dial code.
• Typing or pasting + + dial code auto-detects the country (longest-prefix match, area-code aware for shared codes like +1/+7/+44) and switches the flag. Input is restricted to digits and + ( ) - . space (+ only leading).

Useful instance properties: phone.el (original target), phone.input (the tel input), phone.root (the .vph wrapper), phone.button (country button), phone.country (current country record), phone.isOpen, phone.opts.

Options

All options with their defaults, exactly as in PhoneInput.defaults (mutable — change it to set global defaults before constructing).

Note: the pure helper functions (PhoneInput.parse etc.) do not take an options object — where they accept a second parameter it is an iso2 country code string. See Statics & helpers.

Instance methods

All setters return the instance for chaining.

Statics & helpers

Pure helpers — no DOM needed, usable in Node. None takes an options object; the optional second parameter is always an ISO-3166 alpha-2 string.

Other statics

Events & callbacks

The component does not dispatch custom DOM events — all notifications go through the three option callbacks:

The underlying <input type="tel"> is a real input, so native input/blur/focus events from user interaction behave normally; programmatic setValue() does not fire native events.

Declarative init (data attributes)

Any element with data-vph is auto-initialized on DOMContentLoaded (or immediately if the script loads after). Call PhoneInput.autoInit(root) for content added later. The attribute value itself is a country shorthand: data-vph="ae" ≡ data-vph data-country="ae".

<input data-vph data-country="gb" data-preferred="gb,ie,us">

* Boolean attributes: "false" and "0" parse as false; anything else (including empty) as true. Callback options (onChange etc.), validator and labels have no data-attribute form — use the JS API.

Theming

Auto light/dark with the family's resolution order (<html data-theme> / data-bs-theme / .dark/.light class → prefers-color-scheme, re-resolved live; via VC.theme when the core is loaded). Pin per instance with theme: 'light' | 'dark'. All colors are CSS custom properties, defined on .vph, .vph-panel (and overridden under [data-theme=dark]):

CSS isolation: the control renders as class="vph vc1" and all structural rules ship salted (.vph.vc1 .vph-input { … }) so host design systems cannot override the widget, while --vph-* variable definitions stay unsalted so .vph { --vph-accent: … } page overrides keep working. Custom token: PhoneInput.salt = 'acme' before the first instance; disable with PhoneInput.salt = false. With the VC core loaded, VC.config({ accent: '#b45309' }) themes the whole family at once.

Headless: pass styles: false (or set PhoneInput.defaults.styles = false) and no CSS is injected — behavior, ARIA and the .vph-* markup contract are kept; style them from your own CSS, starting from the PhoneInput.css string if you like.

.vph[data-theme=dark].vph-invalid     ← .vph-valid when valid (after blur)
  .vph-country[aria-expanded]         ← button: flag + dial + caret
    .vph-flag > svg                   ← 20×15 flag
    .vph-dial
    .vph-caret
  input.vph-input[type=tel]
  input[type=hidden]                  ← only when opts.name given
  .vph-sr[aria-live=polite]           ← validation announcements
.vph-panel                            ← portaled to <body> while open
  .vph-search > input[role=combobox]
  .vph-list[role=listbox]
    .vph-opt[role=option].is-active.is-selected
    .vph-sep / .vph-empty

Accessibility

• The tel input is a real <input type="tel">; autocomplete="tel" is preserved (or added when absent).
• The country button carries aria-label ("Choose country: … +971"), aria-haspopup="listbox" and aria-expanded.
• The dropdown is an ARIA listbox driven by aria-activedescendant (set on the search box — a role="combobox" with aria-autocomplete="list" and aria-controls — or on the list itself when searchable: false); options carry role="option" and aria-selected.
• Invalid state sets aria-invalid on the input and announces labels.invalid through a polite live region — only after blur by default, so users aren't scolded mid-typing.
• :focus-visible outlines throughout; prefers-reduced-motion disables all transitions and animations.

new PhoneInput('#phone', {
  country: 'gb',
  styles: false   // no CSS injected
})

.vph { @apply inline-flex w-80 items-stretch overflow-hidden
  rounded-xl border-2 border-amber-300 bg-white shadow-sm
  focus-within:border-amber-500 focus-within:ring-4
  focus-within:ring-amber-200/60; }
.vph.vph-invalid { @apply border-rose-400; }
.vph.vph-valid { @apply border-emerald-400; }
.vph-country { @apply flex items-center gap-1.5 bg-amber-50
  px-3 text-sm cursor-pointer; }
.vph-flag svg { @apply block h-[15px] w-5 rounded-[2px]; }
.vph-dial { @apply font-semibold text-amber-700; }
.vph-input { @apply w-full border-0 bg-transparent px-3
  py-2.5 text-sm outline-none; }
.vph-panel { @apply z-50 mt-1 w-72 overflow-hidden rounded-xl
  border border-amber-200 bg-white shadow-2xl; }
.vph-search input { @apply w-full rounded-lg bg-amber-50
  px-3 py-1.5 text-sm outline-none; }
.vph-list { @apply m-0 max-h-52 list-none overflow-y-auto p-1.5; }
.vph-opt { @apply flex items-center gap-2.5 rounded-lg
  px-2.5 py-1.5 text-sm cursor-pointer; }
.vph-opt.is-active { @apply bg-amber-100/70; }
.vph-opt.is-selected { @apply font-semibold text-amber-700; }
.vph-opt-dial { @apply text-xs text-slate-400; }
.vph-sep { @apply my-1 h-px bg-amber-100; }
.vph-empty { @apply px-3 py-6 text-center text-slate-400; }
.vph-sr { @apply sr-only; }