Vue IMask Plugin

Common errors

• Failed to resolve import "vue-imask" from "src/App.vue". Is the file system or an NPM dependency missing?

  cause The `vue-imask` package is not installed or incorrectly added to `package.json`.
  fix Run `npm install vue-imask` or `yarn add vue-imask` to install the package.

• Error: Cannot find module '@vue/composition-api'

  cause You are using `vue-imask` (or its composable/component features) in a Vue 2 project without the `@vue/composition-api` plugin installed.
  fix Install the necessary plugin: `npm install --save-dev @vue/composition-api`.

• Property 'value' does not exist on type 'Event'.

  cause When using the `v-imask` directive's `@accept` or `@complete` events, the event detail object is accessed incorrectly in TypeScript.
  fix Access the mask reference via `e.detail` as `const maskRef = (e as CustomEvent).detail; this.value = maskRef.value;`.

• Component is missing template or render function.

  cause When using `IMaskComponent` in a Vue 2 single-file component, it needs to be properly registered in the `components` option.
  fix Ensure `components: { 'imask-input': IMaskComponent }` is present in your component's options, and use it in the template as `<imask-input ... />`.

Warnings

• breaking The behavior of `v-model` and the `accept` events changed significantly between Vue 2 and Vue 3. In Vue 3, you can use `v-model:value`, `v-model:masked`, `v-model:unmasked`, or `v-model:typed`. The `onAccept` callback in Vue 2 depends on the `unmask` prop, while Vue 3 introduces distinct `onAccept:masked`, `onAccept:unmasked`, and `onAccept:typed` events.
  Fix: For Vue 3, explicitly use `v-model:masked`, `v-model:unmasked`, or `v-model:typed`. Handle specific event values via `onAccept:masked`, `onAccept:unmasked`, etc.
• gotcha For Vue 2 applications, especially when using the composable (`useIMask`) or the component with advanced features, the `@vue/composition-api` plugin is required. For Vue 2 Nuxt.js projects, `@nuxtjs/composition-api` is also needed.
  Fix: Install `npm i -D @vue/composition-api` for Vue 2, and `npm i -D @nuxtjs/composition-api` (plus module configuration) for Nuxt 2. This is not needed for Vue 3.
• gotcha `vue-imask` (and the core `imask` library) adopted `type: "module"` across all packages (except Angular) since v7.1.1, making it ESM-first. While a CJS build was added in v7.2.0, ESM imports are generally preferred and more straightforward.
  Fix: Always use ES module import syntax (`import ... from 'package';`). If you encounter issues in a CommonJS environment, ensure your build setup correctly handles dual-package exports or consider configuring your bundler to resolve the CJS entry point explicitly.
• gotcha Since v7.1.2, the `esm` part in import paths (e.g., `import 'imask/esm/masked/number'`) can be skipped, simplifying imports to `import 'imask/masked/number';` for core IMask.js modules.
  Fix: Update import paths to remove the redundant `/esm/` segment where applicable for cleaner and potentially more robust imports.
• gotcha The `v-imask` directive might not consistently update `v-model` bindings in all scenarios, especially when complex mask configurations or dynamic changes are involved.
  Fix: Instead of relying solely on `v-model` with the directive, use the `@accept` or `@complete` events to explicitly update your data property with `e.detail.value` or `e.detail.unmaskedValue`.

Install

• npm install vue-imask npm
• yarn add vue-imask yarn
• pnpm add vue-imask pnpm

Imports

• IMaskComponent
  wrong:

  const IMaskComponent = require('vue-imask');

  correct:

  import { IMaskComponent } from 'vue-imask';

  Used for the `<imask-input>` component. CommonJS `require` is generally discouraged since `vue-imask` is ESM-first since v7.1.1.
• IMaskDirective
  wrong:

  import IMaskDirective from 'vue-imask/directive';

  correct:

  import { IMaskDirective } from 'vue-imask';

  Used to register the `v-imask` directive. Ensure named import syntax is used.
• useIMask
  wrong:

  import { useIMask } from 'vue-imask/dist/vue-imask.esm.js';

  correct:

  import { useIMask } from 'vue-imask';

  Vue 3 Composition API hook. The `/dist/vue-imask.esm.js` path is unnecessary and deprecated since v7.1.2.

Quickstart

This quickstart demonstrates the usage of the `IMaskComponent` with Vue 3's Composition API, showing `v-model:typed` for bidirectional binding and separate `accept` events for masked and unmasked values.

<template>
  <imask-input
    v-model:typed="numberModel"
    :mask="Number"
    radix="."
    @accept:masked="onAcceptMasked"
    @accept:unmasked="onAcceptUnmasked"
    placeholder='Enter number here'
  />
</template>

<script lang="ts">
  import { defineComponent, ref } from 'vue';
  import { IMaskComponent } from 'vue-imask';
  // Also useful: Number, Pattern, Date, Enum masks from imask core
  import { NumberMask } from 'imask'; 

  export default defineComponent({
    components: {
      'imask-input': IMaskComponent
    },
    setup() {
      const numberModel = ref<number | string>('');

      const onAcceptMasked = (value: string) => {
        console.log('Masked value:', value);
      };

      const onAcceptUnmasked = (unmaskedValue: string) => {
        console.log('Unmasked value:', unmaskedValue);
      };

      return {
        numberModel,
        Number: NumberMask, // Or simply 'Number' if importing from 'imask' core
        onAcceptMasked,
        onAcceptUnmasked,
      };
    }
  });
</script>