{"id":12637,"library":"vue3-tel-input","title":"Vue 3 International Telephone Input","description":"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.","status":"active","version":"1.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/victorybiz/vue3-tel-input","tags":["javascript","vue","vue3","vue 3","telephone","phone","vue-tel-input","vue3-tel-input","phone input"],"install":[{"cmd":"npm install vue3-tel-input","lang":"bash","label":"npm"},{"cmd":"yarn add vue3-tel-input","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue3-tel-input","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Used for global plugin installation via `app.use(VueTelInput, options)` in a Vue 3 application.","wrong":"const VueTelInput = require('vue3-tel-input');","symbol":"VueTelInput","correct":"import VueTelInput from 'vue3-tel-input';"},{"note":"Used for local component registration within a Vue component's `components` option. This is a named import.","wrong":"import VueTelInput from 'vue3-tel-input';","symbol":"VueTelInput","correct":"import { VueTelInput } from 'vue3-tel-input';"},{"note":"Essential for proper styling. Must be imported separately from the component itself.","wrong":"import 'vue3-tel-input/vue3-tel-input.css';","symbol":"CSS Styles","correct":"import 'vue3-tel-input/dist/vue3-tel-input.css';"}],"quickstart":{"code":"import { createApp, ref } from 'vue';\nimport App from './App.vue';\nimport { VueTelInput } from 'vue3-tel-input';\nimport 'vue3-tel-input/dist/vue3-tel-input.css';\n\nconst app = createApp(App);\n\napp.component('VueTelInput', VueTelInput);\napp.mount('#app');\n\n// In your App.vue or any other component:\n// <template>\n//   <div>\n//     <h1>Enter Phone Number</h1>\n//     <vue-tel-input\n//       v-model=\"phoneNumber\"\n//       :preferredCountries=\"['US', 'CA']\"\n//       :onlyCountries=\"['US', 'CA', 'GB', 'DE', 'FR']\"\n//       :inputOptions=\"{ placeholder: 'Enter your phone number' }\"\n//       @update=\"onUpdate\"\n//     ></vue-tel-input>\n//     <p v-if=\"phoneNumber\">Current Number: {{ phoneNumber }}</p>\n//     <p v-if=\"telInputInfo\">Validation Info: {{ telInputInfo }}</p>\n//   </div>\n// </template>\n\n// <script setup>\n// import { ref } from 'vue';\n// const phoneNumber = ref('');\n// const telInputInfo = ref(null);\n\n// const onUpdate = (payload) => {\n//   phoneNumber.value = payload.number;\n//   telInputInfo.value = payload;\n//   console.log('Tel Input Update:', payload);\n// };\n// </script>","lang":"typescript","description":"This quickstart demonstrates both global registration and local component usage with `v-model` binding, preferred/only countries, and event handling for validation data."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For global usage: `import VueTelInput from 'vue3-tel-input'; app.use(VueTelInput);`. For local usage: `import { VueTelInput } from 'vue3-tel-input'; components: { VueTelInput }`.","cause":"The component was not properly imported or registered, either globally with `app.use()` or locally in a component's `components` option.","error":"Failed to resolve component: vue-tel-input"},{"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)`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'use')"},{"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.","cause":"`v-model` is being used with a non-reactive variable, or the variable returned from `setup()` doesn't match the template binding.","error":"[Vue warn]: v-model value must be a ref, received null"}],"ecosystem":"npm"}