📞 Vue Tel Num Input

A fully customizable phone number input for Vue 3 with country selection, flags, masking, and localization. Built for flexibility and great DX.

Install

npm i libphonenumber-js vue-tel-num-input
# or
npm i libphonenumber-js vue-tel-num-input
# or
pnpm i libphonenumber-js vue-tel-num-input

Demo ❤️

Playground 🚀

Open the online Playground on StackBlitz

Try out the component live, tweak props, and experiment with integration directly in your browser.

Documentation 📚

View full documentation site — guides, API reference, and more examples.

Features

• Country selector with searchable dropdown
• Multiple flag strategies: emoji / sprite / CDN / custom
• Masking (libphonenumber-js AsYouType or a custom mask)
• Localized placeholders (per-locale strings)
• Global (+1 234…) vs national ((234) …) formatting
• Slots for full UI customization (button, input, list items, search)
• TypeScript-first API (exports useful types)
• Performant lists (optional virtual scroll)
• Opt-in default styles, easy to replace

ℹ️ This component uses libphonenumber-js under the hood for phone number validation and formatting (international and national styles).

Quick Start

<script setup lang="ts">
import { ref } from "vue";
import VueTelNumInput, { type TelInputInitModel } from "vue-tel-num-input";
import "vue-tel-num-input/style.css";
import "vue-tel-num-input/flags.css";

const model = ref<TelInputInitModel>({});
</script>

<template>
  <VueTelNumInput v-model="model" default-country-code="US" />
</template>

Why this component?

• Flexible by default: sensible defaults, but every piece is swappable.
• Composable: bring your data sources, flags, and masks.
• DX > ceremony: clear props, typed model, documented slots & events.
• Performance-aware: lazy assets, lazy api icons loading.

Props

| Prop | Type | Default | Description | | ------------------------------- | --------------------------------------- | ---------------------- | ------------------------------------------------------------- | | size | "sm" \| "md" \| "lg" \| "xl" \| "xxl" | "lg" | Component sizing (affects row/item heights via CSS variables) | | disableSizing | boolean | false | Turn off built-in sizing classes | | displayName | "english" \| "native" | "english" | Country name to display | | countryCodes | string[] | [] | Allowlist of ISO2 codes to show | | excludeCountryCodes | string[] | [] | Blocklist of ISO2 codes to hide | | autoDetectCountry | boolean | false | Detect user country on mount (best effort) | | defaultCountryCode | string | "US" | Initial country ISO2 | | disabled | boolean | false | Disable input | | silent | boolean | false | Suppress component warns | | initialValue | string | "" | Initial input value | | international | boolean | true | Format as international (+XX) if true, national if false | | placeholder | string \| Record<string,string> | "Enter phone number" | Static placeholder or locale map | | locale | string | - | Key to pick from placeholder object | | flagSource | "emoji" \| "sprite" \| "cdn" | "emoji" | Strategy for flag rendering (emoji, sprite, CDN) | | itemHeight | number | size-based | Row height override in px | | animationName | string | fade | Animation name for <Transition> built-in Vue component | | Input options | | | | | input.clearOnCountrySelect | boolean | true | Clear input when selecting a new country | | input.focusAfterCountrySelect | boolean | true | Autofocus input after selecting a new country | | input.formatterEnabled | boolean | true | Enable libphonenumber formatting while typing | | input.lockCountryCode | boolean | false | Prevent user from removing/editing the country code | | input.maxLength | number \| undefined | undefined | Optional character cap for input | | input.required | boolean | false | Default input required attribute | | Search options | | | | | search.hidden | boolean | false | Hide search bar in dropdown | | search.placeholder | string \| Record<string,string> | undefined | Placeholder text or localized map | | search.locale | string | undefined | Key to pick from search.placeholder map | | search.clearOnSelect | boolean | true | Clear search query after selecting a country | | search.autoFocus | boolean | true | Autofocus the search input when dropdown opens | | Prefix options | | | | | prefix.hidden | boolean | false | Hide prefix button entirely | | prefix.hideCode | boolean | false | Hide dialing code in prefix | | prefix.hideFlag | boolean | false | Hide flag in prefix | | prefix.hideChevron | boolean | false | Hide dropdown chevron | | prefix.hideCountryName | boolean | false | Hide country name in prefix | | List options | | | | | list.hidden | boolean | false | Hide country list (disables dropdown) | | list.hideCode | boolean | false | Hide dialing codes inside the list | | list.hideFlag | boolean | false | Hide flags inside the list | | list.hideCountryName | boolean | false | Hide country names inside the list | | list.returnToSelected | boolean | true | Scroll back to selected country when reopening dropdown | | list.itemsPerView | number | 5 | Max visible items in dropdown before scrolling |

Flag strategy notes

• emoji: lightweight, zero-network, varies by OS font rendering.
• sprite: best for consistent visuals offline; bundle your sprite.
• cdn: smallest package size; requires network & CORS-safe CDN.

v-model

This component uses typed object binding. v-model works with a TelInputInitModel, giving you both the phone number and related country metadata.

<script setup lang="ts">
import { ref } from "vue";
import type { TelInputInitModel } from "vue-tel-num-input/types";

const model = ref<TelInputInitModel>({});
</script>

<template>
  <VueTelNumInput v-model="model" default-country-code="US" />
</template>

TelInputInitModel shape

type TelInputModel = {
  iso: string; // Selected country ISO2 (e.g. "US")
  name: string; // Country name (localized)
  code: string; // Country calling code (e.g. "+1")
  value: string; // Raw phone number string (user input)
  search: string; // Current search query in dropdown
  expanded: boolean; // Whether the country list is open
};

This gives you full control over both value and UI state (selected country, search query, expanded state).

Important

• The model is readonly from the outside: you should not manually assign values into it.
• Always initialize your ref with an empty object ({}) — the component will populate and update it.
• Use it for reading only, all changes come from user interaction inside the component.

Events

| Event | Payload | When | | ------------------- | --------------- | --------------------------------------- | | update:modelValue | TelInputModel | After formatting/typing/country change. | | toggle | boolean | Dropdown open/close toggled. | | focus | void | Input focused. | | blur | void | Input blurred. |

Slots

| Slot name | Purpose | | -------------------- | -------------------------------------------- | | prefix:before | Before everything inside the country button. | | prefix:flag | Custom flag in the button. | | prefix:code | Custom code text (+421). | | prefix:countryName | Custom country label. | | prefix:chevron | Chevron / indicator icon. | | prefix:after | After everything inside the button. | | input | Replace the <input> entirely. | | body:search | Replace the whole search container. | | search:icon | Magnifier icon in search. | | search:input | Replace search <input>. | | item:before | Before each list row. | | item:flag | Flag in list rows. | | item:code | Code in list rows. | | item:countryName | Country name in list rows. | | item:after | After each list row. |

📤 Exposed Methods & Refs (defineExpose)

The component exposes an API that can be accessed via ref. This allows you to programmatically control the dropdown, formatting, and access internal refs.

Type

export type VueTelNumInputExpose = {
  /** Open/close the country dropdown programmatically */
  switchDropdown: (value?: boolean) => void;

  /** Select a specific country programmatically */
  selectItem: (data: Country) => void;

  /** Force re-formatting of the current phone number value */
  formatNow: () => void;

  /** References to DOM elements */
  inputEl: HTMLInputElement | null;
  searchEl: HTMLInputElement | null;
  telNumInputEl: HTMLElement | null;

  /** Current user country (if auto-detection is enabled) */
  country: string | null;

  /** Trigger user country detection manually */
  requestUserCountry: () => Promise<string | null>;
};

Example Usage

<script setup lang="ts">
import { ref, onMounted } from "vue";
import VueTelNumInput from "vue-tel-num-input";
import type { VueTelNumInputExpose } from "vue-tel-num-input";

const telRef = ref<VueTelNumInputExpose | null>(null);

onMounted(() => {
  // Open dropdown programmatically
  telRef.value?.switchDropdown(true);

  // Format the current phone number immediately
  telRef.value?.formatNow();
});

const detectCountry = async () => {
  const iso = await telRef.value?.requestUserCountry();
  console.log("Detected country:", iso);
};
</script>

<template>
  <VueTelNumInput ref="telRef" />
  <button @click="detectCountry">Detect country</button>
</template>

🫡 Examples

Control visible countries

<VueTelNumInput
  v-model="phone"
  :country-codes="['US', 'CA', 'GB', 'SK', 'PL']"
/>

Use native names and CDN flags

<VueTelNumInput v-model="phone" display-name="native" :flag-source="'cdn'" />

Custom button (slots)

<VueTelNumInput v-model="phone">
  <template #prefix:flag>
    <MyFlag :iso="model.iso" />
  </template>

  <template #prefix:code>
    <span class="code">Dial {{ model.code }}</span>
  </template>
</VueTelNumInput>

Localized placeholder

<VueTelNumInput
  v-model="phone"
  :placeholder="{ en: 'Phone number', sk: 'Telefónne číslo' }"
  locale="sk"
/>

Input masking via libphonenumber-js

// prop input.formatterEnabled=true enables AsYouType internally

OR bring your own mask by replacing the input slot and binding back to v-model.

💀 Types

The library exports type for model ref:

import type { TelInputModel } from "vue-tel-num-input";

// Example TelInputModel shape:
type TelInputModel = {
  iso: string; // ISO2
  name: string; // country label (native/english)
  code: string; // '+421'
  value: string; // input value
  search: string; // dropdown search query
  expanded: boolean;
};

If you’re building wrappers, re-export these types from your package so users don’t need to reach inside your internals.

✨ CSS Variables

| Var | Default | Notes | | -------------------------------------- | ------------------------- | ----------------------------------------------------- | | --tel-input-height | 40px | Overall control height | | --tel-input-border-radius | 6px | Corner radius for head & dropdown | | --tel-input-font-size | 14px | Base font size for component | | --tel-input-padding-x | 12px | Horizontal padding for the input | | --tel-input-icon-size | 12px | Size for chevrons/search/flag placeholders | | --tel-scrollbar-width | 6px | Dropdown scrollbar width | | --tel-scrollbar-thumb | #bbb | Dropdown scrollbar thumb color | | --tel-scrollbar-track | #f9f9f9 | Dropdown scrollbar track color | | --tel-scrollbar-radius | 12px | Dropdown scrollbar thumb radius | | --tel-input-prefix-padding-x | 12px | Horizontal padding inside the country button | | --tel-input-prefix-gap | 8px | Gap between flag/code/name in the button & list items | | --tel-input-chevron-transition-func | ease | Timing function for chevron rotation | | --tel-input-transition-duration | 0.3s | Shared transition duration | | --tel-input-chevron-transition-delay | 0s | Delay for chevron transition | | --tel-input-chevron-transition-prop | transform | Transitioned property for chevron | | --tel-input-input-width | 200px | Width of the text input | | --tel-input-input-bg | #fff | Input background | | --tel-input-input-color | #333 | Input text color | | --tel-input-body-border | 1px solid #ccc | Border around the dropdown panel | | --tel-input-body-bg | #f9f9f9 | Dropdown background | | --tel-input-search-outline | none | Outline for the search input | | --tel-input-search-border | none | Border for the search input | | --tel-input-search-icon-color | #333 | Color of the search icon | | --tel-input-search-icon-margin-x | 12px | (Preferred) Left margin of search icon | | --tel-input-search-icon-margin-x | 12px | (Current code uses this – likely a typo) | | --tel-item-padding-x | 12px | Horizontal padding for each country row | | --tel-input-body-item-border | 1px solid #eee | Divider between country rows | | --tel-input-body-item-bg | #fff | Country row background | | --tel-input-body-item-color | #333 | Country row text color | | --tel-input-transition-func | ease | Shared transition timing function | | --tel-input-transition-delay | 0s | Shared transition delay | | --tel-input-transition-prop | background-color, color | Shared transitioned properties | | --tel-input-body-item-hover-bg | #eee | Hover background for country rows | | --tel-input-body-item-hover-color | #333 | Hover text color for country rows | | --tel-input-body-item-hover-cursor | pointer | Cursor on hover for country rows | | --tel-input-body-item-selected-bg | #ddd | Selected row background | | --tel-input-body-item-selected-color | #333 | Selected row text color |

You can also disable built-in sizing with disableSizing and style from scratch.

🛣️ Roadmap

• Dropdown with complete slot coverage ✅
• Multiple flag strategies ✅
• Global vs national formatting toggle ✅
• Search UX polish (clear icon, keyboard nav) ⏳
• Fully documented events & accessibility pass ⏳
• Tests 🤯

Contributions welcome — see below 🙏.

🧶 Accessibility

• Keyboard navigation in dropdown (planned)
• ARIA attributes on toggle and list (planned)
• Focus management on open/close (partial; improvements planned)

If accessibility is critical in your project, review current behavior and consider contributing improvements — happy to collaborate.

🤝 Contributing

Contributions are very welcome! You can help by fixing bugs, improving docs, or adding features.

1. Fork the repo and create a new branch
2. npm i to install dependencies
3. npm watch:build to build the project JIT
4. npm link in directory folder
5. npm link vue-tel-num-input in your project directory
6. Commit your changes and push your branch 😍
7. Create Pull-Request
8. Thank you

For UI changes please include screenshots or gifs so it’s easy to review 🥹

👉 Bug reports and feature requests should be submitted as GitHub Issues.

🚧 Project Status

This component is currently in beta. The API and behavior may still change before a stable release.

If you encounter any bugs, unexpected behavior, or have feature requests: 👉 please open an issue on GitHub

Your feedback will help improve and stabilize the component for production use.

Notes & Caveats

• CDN flags require a CORS-safe provider; otherwise use emoji or sprite.
• autoDetectCountry is best-effort; always set defaultCountryCode as fallback.
• When formatterEnabled is true, manual cursor jumps can occur with some masks—test your locales and adjust strategy if needed.

License

MIT © 2025 Mark Minerov