{"id":12596,"library":"vue-tel-input","title":"Vue Tel Input","description":"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.","status":"active","version":"9.8.0","language":"javascript","source_language":"en","source_url":"https://github.com/iamstevendao/vue-tel-input","tags":["javascript","vue","telephone","phone","vue-tel-input","phone input","telephone input","input","international phone","typescript"],"install":[{"cmd":"npm install vue-tel-input","lang":"bash","label":"npm"},{"cmd":"yarn add vue-tel-input","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-tel-input","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides international phone number parsing, validation, and formatting logic.","package":"libphonenumber-js","optional":false},{"reason":"Required Vue.js framework for component rendering.","package":"vue","optional":false}],"imports":[{"note":"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.","wrong":"import { VueTelInput } from 'vue-tel-input'; app.use(VueTelInput);","symbol":"VueTelInput (global)","correct":"import VueTelInput from 'vue-tel-input';\napp.use(VueTelInput);"},{"note":"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.","wrong":"import VueTelInput from 'vue-tel-input';","symbol":"VueTelInput (component)","correct":"import { VueTelInput } from 'vue-tel-input';"},{"note":"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.","wrong":"import 'vue-tel-input/dist/vue-tel-input.css';","symbol":"CSS Styles","correct":"import 'vue-tel-input/vue-tel-input.css';"}],"quickstart":{"code":"<template>\n  <vue-tel-input v-model=\"phone\" mode=\"international\"></vue-tel-input>\n</template>\n\n<script lang=\"ts\">\n  import { ref, defineComponent } from 'vue';\n  import { VueTelInput } from 'vue-tel-input';\n  import 'vue-tel-input/vue-tel-input.css';\n\n  export default defineComponent({\n    components: {\n      VueTelInput,\n    },\n    setup() {\n      const phone = ref<string | null>(null);\n      return {\n        phone,\n      };\n    },\n  });\n</script>","lang":"typescript","description":"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."},"warnings":[{"fix":"Run `npm install libphonenumber-js vue` in your project directory.","message":"Starting from `v9.3.0`, `libphonenumber-js` and `vue` were moved to peer dependencies. They must now be explicitly installed in your project.","severity":"breaking","affected_versions":">=9.3.0"},{"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.","message":"TypeScript declaration files were historically incorrect or missing in versions prior to `v9.8.0`, leading to potential type errors or incomplete IntelliSense.","severity":"gotcha","affected_versions":"<9.8.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<9.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=9.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"`npm install libphonenumber-js`","cause":"The `libphonenumber-js` package, a peer dependency, is not installed in your project.","error":"Cannot find module 'libphonenumber-js' or its corresponding type declarations."},{"fix":"Use the default import for global registration: `import VueTelInput from 'vue-tel-input'; app.use(VueTelInput);`","cause":"Attempting to use `app.use({ VueTelInput })` or a named import when `app.use()` expects the default export for global registration.","error":"Property 'VueTelInput' does not exist on type 'typeof import(\"vue-tel-input\")'."},{"fix":"Update your CSS import statement to: `import 'vue-tel-input/vue-tel-input.css';`","cause":"An incorrect or deprecated path is being used to import the component's CSS styles.","error":"Module not found: Error: Can't resolve 'vue-tel-input/dist/vue-tel-input.css'"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'install') when using `app.use(window['vue-tel-input'])` in browser."}],"ecosystem":"npm"}