{"id":12502,"library":"vue-imask","title":"Vue IMask Plugin","description":"vue-imask is the official Vue.js plugin for IMask.js, a robust and versatile JavaScript input mask library. It provides native Vue 2 and Vue 3 support through a component (`<imask-input>`), a directive (`v-imask`), and a composable (`useIMask`) for granular control over input formatting. The package is currently at version 7.6.1 and receives frequent updates, typically on a monthly basis, incorporating new mask features and bug fixes from the core IMask.js library, along with Vue-specific enhancements. Its key differentiators include comprehensive mask types (pattern, number, date, enum, dynamic, etc.), excellent IME support, and a flexible API that allows for both declarative (component/directive) and programmatic (composable) masking, making it suitable for a wide range of input formatting requirements in Vue applications. It ships with full TypeScript type definitions, ensuring type safety and improved developer experience.","status":"active","version":"7.6.1","language":"javascript","source_language":"en","source_url":"https://github.com/uNmAnNeR/imaskjs#master","tags":["javascript","vue","imask","input","mask","typescript"],"install":[{"cmd":"npm install vue-imask","lang":"bash","label":"npm"},{"cmd":"yarn add vue-imask","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-imask","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime peer dependency for all Vue applications.","package":"vue","optional":false},{"reason":"Required for Vue 2 applications to enable the Composition API features (composables, setup script, etc.).","package":"@vue/composition-api","optional":true},{"reason":"Required for Vue 2 Nuxt.js projects to enable the Composition API.","package":"@nuxtjs/composition-api","optional":true}],"imports":[{"note":"Used for the `<imask-input>` component. CommonJS `require` is generally discouraged since `vue-imask` is ESM-first since v7.1.1.","wrong":"const IMaskComponent = require('vue-imask');","symbol":"IMaskComponent","correct":"import { IMaskComponent } from 'vue-imask';"},{"note":"Used to register the `v-imask` directive. Ensure named import syntax is used.","wrong":"import IMaskDirective from 'vue-imask/directive';","symbol":"IMaskDirective","correct":"import { IMaskDirective } from 'vue-imask';"},{"note":"Vue 3 Composition API hook. The `/dist/vue-imask.esm.js` path is unnecessary and deprecated since v7.1.2.","wrong":"import { useIMask } from 'vue-imask/dist/vue-imask.esm.js';","symbol":"useIMask","correct":"import { useIMask } from 'vue-imask';"}],"quickstart":{"code":"<template>\n  <imask-input\n    v-model:typed=\"numberModel\"\n    :mask=\"Number\"\n    radix=\".\"\n    @accept:masked=\"onAcceptMasked\"\n    @accept:unmasked=\"onAcceptUnmasked\"\n    placeholder='Enter number here'\n  />\n</template>\n\n<script lang=\"ts\">\n  import { defineComponent, ref } from 'vue';\n  import { IMaskComponent } from 'vue-imask';\n  // Also useful: Number, Pattern, Date, Enum masks from imask core\n  import { NumberMask } from 'imask'; \n\n  export default defineComponent({\n    components: {\n      'imask-input': IMaskComponent\n    },\n    setup() {\n      const numberModel = ref<number | string>('');\n\n      const onAcceptMasked = (value: string) => {\n        console.log('Masked value:', value);\n      };\n\n      const onAcceptUnmasked = (unmaskedValue: string) => {\n        console.log('Unmasked value:', unmaskedValue);\n      };\n\n      return {\n        numberModel,\n        Number: NumberMask, // Or simply 'Number' if importing from 'imask' core\n        onAcceptMasked,\n        onAcceptUnmasked,\n      };\n    }\n  });\n</script>","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=7.1.1"},{"fix":"Update import paths to remove the redundant `/esm/` segment where applicable for cleaner and potentially more robust imports.","message":"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.","severity":"gotcha","affected_versions":">=7.1.2"},{"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`.","message":"The `v-imask` directive might not consistently update `v-model` bindings in all scenarios, especially when complex mask configurations or dynamic changes are involved.","severity":"gotcha","affected_versions":">=2.x"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install vue-imask` or `yarn add vue-imask` to install the package.","cause":"The `vue-imask` package is not installed or incorrectly added to `package.json`.","error":"Failed to resolve import \"vue-imask\" from \"src/App.vue\". Is the file system or an NPM dependency missing?"},{"fix":"Install the necessary plugin: `npm install --save-dev @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.","error":"Error: Cannot find module '@vue/composition-api'"},{"fix":"Access the mask reference via `e.detail` as `const maskRef = (e as CustomEvent).detail; this.value = maskRef.value;`.","cause":"When using the `v-imask` directive's `@accept` or `@complete` events, the event detail object is accessed incorrectly in TypeScript.","error":"Property 'value' does not exist on type 'Event'."},{"fix":"Ensure `components: { 'imask-input': IMaskComponent }` is present in your component's options, and use it in the template as `<imask-input ... />`.","cause":"When using `IMaskComponent` in a Vue 2 single-file component, it needs to be properly registered in the `components` option.","error":"Component is missing template or render function."}],"ecosystem":"npm"}