vue-imask

library7.6.1jsnpmunverified

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.

web-framework

npm install vue-imask

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE-IMASK

vue-imask

web-frameworkjavascriptv7.6.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

IMaskComponent

✓ import { IMaskComponent } from 'vue-imask';

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

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

IMaskDirective

✓ import { IMaskDirective } from 'vue-imask';

✗ import IMaskDirective from 'vue-imask/directive';

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

useIMask

✓ import { useIMask } from 'vue-imask';

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

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

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>

Debug

Known issues

breakingThe 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.

affects: >=3.0.0

gotchaFor 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.

affects: <3.0.0

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.

affects: >=7.1.1

gotchaSince 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.

affects: >=7.1.2

gotchaThe `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`.

affects: >=2.x

Errors

Common errors & fixes

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

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'

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'.

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.

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 ... />`.

Upgrade

Version history

7.6.1latest on npm

Audit

Dependencies

vuerequiredRuntime peer dependency for all Vue applications.

@vue/composition-apioptionalRequired for Vue 2 applications to enable the Composition API features (composables, setup script, etc.).

@nuxtjs/composition-apioptionalRequired for Vue 2 Nuxt.js projects to enable the Composition API.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/uNmAnNeR/imaskjs.git#master ↗

packagehttps://www.npmjs.com/package/vue-imask ↗

homepagehttps://imask.js.org ↗