Vue 2 Input Mask Plugin

Common errors

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

  cause Attempting to use `di-vue-mask` (a Vue 2 plugin) in a Vue 3 application. Vue 3's plugin registration API (`app.use()`) is different from Vue 2's (`Vue.use()`), and the internal directives are incompatible.
  fix For Vue 3 projects, use a Vue 3 compatible masking library like `maska`, `vue-imask`, or `vue-3-mask-updated`. This package is exclusively for Vue 2 applications.

• Error: Failed to resolve directive: mask

  cause The `di-vue-mask` plugin has not been correctly registered with Vue, or it's being used in a Vue 3 environment where its directives are not recognized.
  fix Ensure `import VueMask from 'di-vue-mask'; Vue.use(VueMask);` is called before your Vue instance is created. Verify that your project is indeed running Vue 2.

Warnings

• breaking This package is strictly compatible only with Vue 2. It will not work with Vue 3 or later versions due to significant API changes in Vue's core. Consider `maska`, `vue-imask`, `vue-3-mask-updated`, or `ertu-forms` for Vue 3 compatible solutions.
  Fix: For new projects, use a Vue 3 compatible masking library. For existing Vue 2 projects, ensure you remain on Vue 2.
• gotcha When using `di-vue-mask` on custom Vue components that do not inherently support `v-model`, you must use the `v-mask-model` directive instead of `v-model` to ensure proper masking and data binding.
  Fix: Replace `v-model` with `v-mask-model` for custom components that lack `v-model` support: `<my-input v-mask-model="maskValue" v-mask="'0000-0000'"></my-input>`.
• gotcha The mask definitions rely on specific characters (`0`, `9`, `#`, `A`, `S`, `U`, `L`, `$`). Misinterpreting these characters can lead to masks not behaving as expected. For example, `0` is any number (required), `9` is any number (optional), and `A` is any alphanumeric character.
  Fix: Carefully consult the documentation for the special mask characters and their exact meanings to construct correct mask patterns.
• gotcha This package is built upon the `String-Mask` library. While generally stable, any underlying issues or limitations in `String-Mask` could potentially manifest in `di-vue-mask`.
  Fix: If encountering unexpected masking behavior, consider reviewing the `String-Mask` documentation or issues for deeper insight.

Install

• npm install di-vue-mask npm
• yarn add di-vue-mask yarn
• pnpm add di-vue-mask pnpm

Imports

• VueMask
  wrong:

  const VueMask = require('di-vue-mask')

  correct:

  import VueMask from 'di-vue-mask'

  This is the default export of the plugin. It must be imported to register the masking directives globally via Vue.use().
• Vue.use(VueMask)
  wrong:

  new Vue({ components: { VueMask } })

  correct:

  Vue.use(VueMask)

  The library operates as a Vue plugin, registering all its masking directives (like v-mask, v-mask-date, etc.) globally for use in templates. These directives are not imported as separate JavaScript symbols but become available after plugin registration.

Quickstart

Demonstrates how to install and register `di-vue-mask` as a Vue 2 plugin and apply a Brazilian phone number mask to an input field using `v-mask-phone.br`.

import Vue from 'vue';
import VueMask from 'di-vue-mask';

// Register the plugin globally
Vue.use(VueMask);

new Vue({
  el: '#app',
  data: {
    phoneNumber: ''
  },
  template: `
    <div id="app">
      <label for="phoneInput">Enter Phone Number (BR):</label>
      <input type="text" id="phoneInput" v-model="phoneNumber" v-mask-phone.br>
      <p>Raw value: {{ phoneNumber }}</p>
      <p>Try entering digits like '11987654321' to see the mask in action.</p>
    </div>
  `
});