Vue Phone Number Input

Common errors

• [Vue warn]: Failed to resolve component: vue-phone-number-input

  cause Attempting to use the Vue 2 component in a Vue 3 application.
  fix This component is incompatible with Vue 3. Migrate to `MazPhoneNumberInput` from `maz-ui` v3.x.

• TypeError: Cannot read properties of undefined (reading 'install')

  cause Incorrect global component registration or `Vue` is not globally available in a CommonJS or non-browser environment.
  fix Ensure `Vue` is imported and globally available (e.g., `import Vue from 'vue';`) and use `Vue.component('VuePhoneNumberInput', VuePhoneNumberInput);` without `.default` for ESM imports. If using UMD, refer to the documentation for correct `window.VuePhoneNumberInput.default` usage.

• [Vue warn]: Invalid prop: type check failed for prop "modelValue". Expected String, got Object.

  cause `v-model` is bound to an object instead of a string. `vue-phone-number-input` expects a string for the phone number.
  fix Ensure `v-model` is bound to a string variable (e.g., `v-model="userPhoneNumber"`). The component emits a detailed object on the `@update` event, which should be handled separately if you need the full data.

• Error: Could not find country calling code for country 'XX'

  cause An invalid or unsupported ISO 3166-1 alpha-2 country code was provided to a prop like `default-country-code` or implicitly via an initial `v-model` value.
  fix Verify that the country code (e.g., 'US', 'FR', 'DE') is a valid ISO 3166-1 alpha-2 code and is recognized by `libphonenumber-js`. Refer to a list of standard country codes.

Warnings

• breaking This package is explicitly marked as unmaintained by its author. No further updates, bug fixes, or security patches will be released for `vue-phone-number-input` (v1.x).
  Fix: Migrate to `MazPhoneNumberInput` from the `maz-ui` library. Use `maz-ui` v2.x for Vue 2 projects or `maz-ui` v3.x for Vue 3 projects.
• breaking This component is built exclusively for Vue 2. Attempting to use `vue-phone-number-input` directly in a Vue 3 application will lead to component resolution failures and runtime errors.
  Fix: If working with Vue 3, use `MazPhoneNumberInput` from `maz-ui` v3.x which provides a compatible version of the component. Avoid trying to adapt this Vue 2 package to Vue 3.
• gotcha The component relies on `libphonenumber-js` for its core functionality. As this package is unmaintained, it will not receive updates to `libphonenumber-js`. This can result in outdated phone number data, incorrect validation for new country codes or formats, and potential security vulnerabilities if `libphonenumber-js` has critical updates.
  Fix: Regularly monitor `libphonenumber-js` for updates. If using this unmaintained component, you may need to manually update `libphonenumber-js` and verify compatibility, or preferably, migrate to `maz-ui` which actively manages its dependencies.
• gotcha The component requires a global CSS import (`import 'vue-phone-number-input/dist/vue-phone-number-input.css';`). This can lead to styling conflicts with other UI libraries or custom project styles due to its global nature and potentially generic class names.
  Fix: Use CSS preprocessors with scoping features (e.g., Sass, Less) to override conflicting styles, or increase CSS specificity in your custom stylesheets. Consider encapsulating the component within a shadow DOM if deeper isolation is required, though this adds complexity.

Install

• npm install vue-phone-number-input npm
• yarn add vue-phone-number-input yarn
• pnpm add vue-phone-number-input pnpm

Imports

• VuePhoneNumberInput
  wrong:

  const VuePhoneNumberInput = require('vue-phone-number-input');

  correct:

  import VuePhoneNumberInput from 'vue-phone-number-input';

  Primarily designed for ES Modules in modern Vue 2 setups. CommonJS require syntax is generally incorrect.
• CSS Styles
  wrong:

  import 'vue-phone-number-input/src/scss/vue-phone-number-input.scss';

  correct:

  import 'vue-phone-number-input/dist/vue-phone-number-input.css';

  Always import the pre-compiled CSS from `dist` for production. Directly importing SCSS requires a specific build pipeline.
• Global Component Registration
  wrong:

  Vue.component('vue-phone-number-input', VuePhoneNumberInput.default);

  correct:

  Vue.component('VuePhoneNumberInput', VuePhoneNumberInput);

  When using ESM imports like `import VuePhoneNumberInput from '...'`, `VuePhoneNumberInput` directly references the component definition. `.default` is typically for UMD builds.

Quickstart

Demonstrates global registration and basic usage of the `VuePhoneNumberInput` component within a Vue 2 application, including v-model binding, setting a default country, preferred countries, and handling the `update` event to access parsed phone number details.

import Vue from 'vue'; // Ensure Vue 2 is installed
import VuePhoneNumberInput from 'vue-phone-number-input';
import 'vue-phone-number-input/dist/vue-phone-number-input.css';

// Register the component globally (common in Vue 2 applications)
Vue.component('VuePhoneNumberInput', VuePhoneNumberInput);

// Example Vue 2 component where it would be used
const App = Vue.extend({
  name: 'PhoneNumberDemo',
  data() {
    return {
      userPhoneNumber: '+12025550100' as string, // Initial phone number value
      defaultCountry: 'US' as string,
      phoneDetails: null as Record<string, any> | null, // To store the output object
    };
  },
  methods: {
    onUpdate(payload: Record<string, any>) {
      console.log('Phone number data:', payload);
      this.phoneDetails = payload;
    },
  },
  template: `
    <div id="app-container">
      <h2>Phone Number Entry (Vue 2)</h2>
      <p>Current V-Model: <code>{{ userPhoneNumber }}</code></p>
      <VuePhoneNumberInput
        v-model="userPhoneNumber"
        :default-country-code="defaultCountry"
        :no-use-browser-locale="true"
        :preferred-countries="['US', 'CA', 'MX', 'DE']"
        @update="onUpdate"
        :translations="{ countrySelectorLabel: 'Select Country', phoneNumberLabel: 'Enter Phone' }"
      />
      <div v-if="phoneDetails">
        <h3>Parsed Phone Details:</h3>
        <pre>{{ JSON.stringify(phoneDetails, null, 2) }}</pre>
      </div>
      <p style="margin-top: 20px;"><em>Note: This component is unmaintained and for Vue 2 only.</em></p>
    </div>
  `,
});

// Mount the app (in a typical Vue 2 setup)
// new Vue({
//   el: '#app',
//   render: h => h(App)
// });