Vue Tel Input

9.8.0 · active · verified Sun Apr 19

Vue Tel Input is a Vue.js component that provides an international telephone input field, integrating country code selection, formatting, and validation. It leverages `libphonenumber-js` for robust and accurate parsing, formatting, and validation of phone numbers according to international standards. The current stable version is `9.8.0`, with regular minor and patch releases addressing bugs, improving features like TypeScript support, accessibility, and updating underlying dependencies. Key differentiators include its dedicated Vue 3 support (with a separate legacy branch for Vue 2), flexible installation options (global plugin, local component, or lazy loading for performance), and comprehensive customization capabilities for styling and behavior. It offers a standardized solution for handling diverse international phone number inputs in web applications.

Common errors

```
Cannot find module 'libphonenumber-js' or its corresponding type declarations.
```
cause The `libphonenumber-js` package, a peer dependency, is not installed in your project.

fix `npm install libphonenumber-js`
```
Property 'VueTelInput' does not exist on type 'typeof import("vue-tel-input")'.
```
cause Attempting to use `app.use({ VueTelInput })` or a named import when `app.use()` expects the default export for global registration.

fix Use the default import for global registration: `import VueTelInput from 'vue-tel-input'; app.use(VueTelInput);`
```
Module not found: Error: Can't resolve 'vue-tel-input/dist/vue-tel-input.css'
```
cause An incorrect or deprecated path is being used to import the component's CSS styles.

fix Update your CSS import statement to: `import 'vue-tel-input/vue-tel-input.css';`
```
TypeError: Cannot read properties of undefined (reading 'install') when using `app.use(window['vue-tel-input'])` in browser.
```
cause The `vue-tel-input` script loaded via CDN did not automatically install or `window['vue-tel-input']` is not the correct reference to the plugin's install function.

fix Ensure Vue is loaded before `vue-tel-input` for automatic installation. If installing manually, verify the global variable name and that the plugin object has an `install` method.

Warnings

breaking Starting from `v9.3.0`, `libphonenumber-js` and `vue` were moved to peer dependencies. They must now be explicitly installed in your project.
Fix: Run `npm install libphonenumber-js vue` in your project directory.
gotcha TypeScript declaration files were historically incorrect or missing in versions prior to `v9.8.0`, leading to potential type errors or incomplete IntelliSense.
Fix: Update to `vue-tel-input@9.8.0` or higher to ensure correct and complete TypeScript exports. If using an older version, you might need to add `skipLibCheck: true` to your `tsconfig.json` as a temporary workaround, though this is not recommended.
gotcha The CSS import path was fixed in `v9.2.0`. Older versions might have used a different or incorrect path, leading to styles not being applied.
Fix: Ensure you are using `import 'vue-tel-input/vue-tel-input.css';` for styles. Avoid deprecated or incorrect paths like `vue-tel-input/dist/vue-tel-input.css`.
gotcha When implementing component lazy loading, it's crucial to load both the JavaScript component and its CSS asynchronously and correctly, typically using `Promise.all` with bundlers like Webpack/Rollup. Importing CSS via Vue SFC `<style>` tags in lazy-loaded components can cause the CSS to be bundled with the main vendor chunk instead of being lazy-loaded.
Fix: Follow the lazy loading example in the official documentation, ensuring both `import('vue-tel-input')` and `import('vue-tel-input/vue-tel-input.css')` are part of the asynchronous loading process, and avoid `<style>` tags for component CSS in such scenarios.

Install

npm install vue-tel-input npm
yarn add vue-tel-input yarn
pnpm add vue-tel-input pnpm

Imports

VueTelInput (global)
wrong:
```
import { VueTelInput } from 'vue-tel-input'; app.use(VueTelInput);
```
correct:
```
import VueTelInput from 'vue-tel-input';
app.use(VueTelInput);
```
When using `app.use()` for global plugin registration, the default export of the package is expected. Incorrectly using a named import for this purpose will lead to errors.
VueTelInput (component)
wrong:
```
import VueTelInput from 'vue-tel-input';
```
correct:
```
import { VueTelInput } from 'vue-tel-input';
```
For direct component usage, especially within `<script setup>` or the `components` option, `VueTelInput` is exported as a named export. Attempting to use the default export in this context may not work as expected or is deprecated.
CSS Styles
wrong:
```
import 'vue-tel-input/dist/vue-tel-input.css';
```
correct:
```
import 'vue-tel-input/vue-tel-input.css';
```
The correct path for importing the component's essential styles. Older versions or misconfigurations might lead to attempts to import from the `dist` directory, which is incorrect for recent versions and module bundlers.

Quickstart

Demonstrates basic usage of `vue-tel-input` as a local component within a Vue 3 setup script, binding its value to a reactive reference and importing the necessary styles.

<template>
  <vue-tel-input v-model="phone" mode="international"></vue-tel-input>
</template>

<script lang="ts">
  import { ref, defineComponent } from 'vue';
  import { VueTelInput } from 'vue-tel-input';
  import 'vue-tel-input/vue-tel-input.css';

  export default defineComponent({
    components: {
      VueTelInput,
    },
    setup() {
      const phone = ref<string | null>(null);
      return {
        phone,
      };
    },
  });
</script>

view raw JSON →