Vue 3 International Telephone Input

1.0.4 · active · verified Sun Apr 19

vue3-tel-input is a Vue 3 component designed to provide an international telephone input field. It features an integrated country flag dropdown, automatic formatting, and adherence to international dialing standards. The current stable version is 1.0.4. While a specific release cadence isn't published, the project appears actively maintained with recent updates. A key differentiator is its explicit compatibility with Vue 3's composition API and global application setup, moving beyond older Vue versions. It supports both global plugin installation with default options and local component registration for fine-grained control, and requires a separate CSS import for styling. It allows filtering countries and setting preferred countries, making it flexible for various internationalization needs.

Common errors

```
Failed to resolve component: vue-tel-input
```
cause The component was not properly imported or registered, either globally with `app.use()` or locally in a component's `components` option.

fix For global usage: `import VueTelInput from 'vue3-tel-input'; app.use(VueTelInput);`. For local usage: `import { VueTelInput } from 'vue3-tel-input'; components: { VueTelInput }`.
```
TypeError: Cannot read properties of undefined (reading 'use')
```
cause Attempting to use `app.use()` on a non-Vue 3 application instance or trying to install the plugin using Vue 2's `Vue.use()` syntax.

fix Ensure you are using `createApp` to initialize your Vue 3 application instance. For browser usage, confirm that Vue 3 is globally available before attempting `app.use(VueTelInput)`.
```
[Vue warn]: v-model value must be a ref, received null
```
cause `v-model` is being used with a non-reactive variable, or the variable returned from `setup()` doesn't match the template binding.

fix Ensure the variable bound to `v-model` is a `ref` or `reactive` object from Vue's reactivity system. For example: `const phoneNumber = ref('');` in `<script setup>` or `data() { return { phoneNumber: '' } }` in options API.

Warnings

breaking This package is specifically designed for Vue 3. Using it with Vue 2 applications (e.g., via `Vue.use()` or `Vue.component()` global methods without `createApp`) will result in runtime errors as it leverages Vue 3's APIs.
Fix: Ensure your project is a Vue 3 application. If migrating from Vue 2, use `createApp` for initialization. For Vue 2, use a compatible `vue-tel-input` package.
gotcha The documentation includes examples for `vue-form-generator` which appears to be a Vue 2 library. Attempting to integrate `vue3-tel-input` with `vue-form-generator` directly in a Vue 3 project will likely lead to incompatibility and errors due to differing Vue API versions.
Fix: Avoid using the `vue-form-generator` integration examples if your project is Vue 3. Instead, integrate the component directly into your Vue 3 forms.
gotcha The component's styles are not automatically bundled with the component import. Forgetting to explicitly import the CSS file will result in an unstyled and potentially non-functional input field.
Fix: Always include `import 'vue3-tel-input/dist/vue3-tel-input.css';` in your main entry file or the component where `vue-tel-input` is used.

Install

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

Imports

VueTelInput
wrong:
```
const VueTelInput = require('vue3-tel-input');
```
correct:
```
import VueTelInput from 'vue3-tel-input';
```
Used for global plugin installation via `app.use(VueTelInput, options)` in a Vue 3 application.
VueTelInput
wrong:
```
import VueTelInput from 'vue3-tel-input';
```
correct:
```
import { VueTelInput } from 'vue3-tel-input';
```
Used for local component registration within a Vue component's `components` option. This is a named import.
CSS Styles
wrong:
```
import 'vue3-tel-input/vue3-tel-input.css';
```
correct:
```
import 'vue3-tel-input/dist/vue3-tel-input.css';
```
Essential for proper styling. Must be imported separately from the component itself.

Quickstart

This quickstart demonstrates both global registration and local component usage with `v-model` binding, preferred/only countries, and event handling for validation data.

import { createApp, ref } from 'vue';
import App from './App.vue';
import { VueTelInput } from 'vue3-tel-input';
import 'vue3-tel-input/dist/vue3-tel-input.css';

const app = createApp(App);

app.component('VueTelInput', VueTelInput);
app.mount('#app');

// In your App.vue or any other component:
// <template>
//   <div>
//     <h1>Enter Phone Number</h1>
//     <vue-tel-input
//       v-model="phoneNumber"
//       :preferredCountries="['US', 'CA']"
//       :onlyCountries="['US', 'CA', 'GB', 'DE', 'FR']"
//       :inputOptions="{ placeholder: 'Enter your phone number' }"
//       @update="onUpdate"
//     ></vue-tel-input>
//     <p v-if="phoneNumber">Current Number: {{ phoneNumber }}</p>
//     <p v-if="telInputInfo">Validation Info: {{ telInputInfo }}</p>
//   </div>
// </template>

// <script setup>
// import { ref } from 'vue';
// const phoneNumber = ref('');
// const telInputInfo = ref(null);

// const onUpdate = (payload) => {
//   phoneNumber.value = payload.number;
//   telInputInfo.value = payload;
//   console.log('Tel Input Update:', payload);
// };
// </script>

view raw JSON →