Maska: Input Mask

3.2.0 · active · verified Sun Apr 19

Maska is a lightweight, zero-dependency JavaScript library for creating input masks, supporting Vanilla JS, Vue (2 and 3), Alpine.js, and Svelte. The current stable version is 3.2.0, with ongoing maintenance and minor releases following a significant v3.0.0 rewrite. Key differentiators include its minimal footprint (~3 Kb gzipped), comprehensive framework integrations, and advanced masking features such as custom tokens with modifiers and transform functions, hooks, and a dedicated number mask mode for simplified currency and numerical formatting. It also supports dynamic, reversed, and eager masks, providing robust solutions for various input validation scenarios.

Common errors

```
TypeError: Maska is not a constructor
```
cause Attempting to instantiate `Maska` when it hasn't been correctly imported or is undefined in the current scope. Often occurs with incorrect CommonJS `require` usage in an ESM-only environment.

fix Ensure you are using `import { Maska } from 'maska';` in an ES Module context and that the script type is `module` in HTML `<script type="module">`.
```
[Vue warn]: Failed to resolve directive: maska
```
cause The `v-maska` directive for Vue has not been properly imported or registered, or the incorrect import path (`maska` instead of `maska/vue`) was used.

fix Import the directive specifically from `maska/vue` and register it correctly in your Vue application. For Vue 3, this might involve `app.directive('maska', vMaska)` or in a component's `directives` option.
```
Uncaught SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use `import` syntax in a script that is not treated as an ES Module.

fix Add `type="module"` to your script tag: `<script type="module" src="./main.js"></script>`. Alternatively, use a bundler like Webpack or Rollup to transpile your code for older environments.

Warnings

breaking Maska v3 introduced significant breaking changes, including a simplified directive format for framework integrations and specific import paths for Vue (e.g., `maska/vue`). Direct usage of the main `maska` package for Vue directives is no longer supported.
Fix: Review the official Maska v3 documentation for updated integration instructions, especially for Vue, Alpine.js, and Svelte. Ensure you import framework-specific modules (e.g., `import { vMaska } from 'maska/vue';`).
gotcha Maska v3 is designed for modern JavaScript environments and primarily uses ES Modules (ESM). Attempting to use `require()` for imports will result in errors.
Fix: Always use `import` statements for Maska, e.g., `import { Maska } from 'maska'`. If using CommonJS, consider transpilation or a bundler that handles ESM imports.
gotcha When defining custom tokens, ensure the `pattern` property uses a valid regular expression. Incorrect patterns or forgetting to escape special characters in the mask string can lead to unexpected masking behavior or input validation issues.
Fix: Carefully define `tokens` with correct regular expressions. For instance, `tokens: { '#': { pattern: /\d/ } }` for digits. Test edge cases with your masks.
gotcha For number masks or inputs requiring reversed masking (e.g., currency inputs where you type from right to left), remember to set the `reversed: true` option to ensure correct behavior and formatting.
Fix: Include `reversed: true` in your Maska options for applicable inputs: `new Maska(input, { mask: '...', reversed: true })`.

Install

npm install maska npm
yarn add maska yarn
pnpm add maska pnpm

Imports

Maska
wrong:
```
const Maska = require('maska')
```
correct:
```
import { Maska } from 'maska'
```
For Vanilla JS and general utility. ESM-only import for modern applications. The CommonJS `require` syntax is not supported in Maska v3.

v-maska directive (Vue)

wrong:

import { Maska } from 'maska'; // Then trying to use it directly as a Vue directive without 'maska/vue'

correct:

import { vMaska } from 'maska/vue';

// In Vue component setup:
directives: { maska: vMaska }

Since Maska v3, the Vue directive is imported specifically from 'maska/vue'. Ensure correct registration for Vue 2 or Vue 3 setup.

MaskaDetail
```
import { type MaskaDetail } from 'maska'
```
TypeScript type import for detailed mask information, such as `masked`, `unmasked`, `completed` status.

Quickstart

Demonstrates basic Maska usage for Vanilla JavaScript, applying a phone number mask and a reversed currency mask to input fields. It shows how to initialize Maska, define masks and tokens, and access masked/unmasked values and completion status.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Maska Quickstart</title>
</head>
<body>
  <label for="phone-input">Phone Number (US):</label>
  <input type="text" id="phone-input" placeholder="+1 (___) ___-____" />

  <label for="currency-input">Currency ($):</label>
  <input type="text" id="currency-input" placeholder="$__.__" />

  <script type="module">
    import { Maska } from 'maska';

    document.addEventListener('DOMContentLoaded', () => {
      // Example 1: Phone number mask
      const phoneInput = document.getElementById('phone-input');
      const phoneMask = new Maska(phoneInput, {
        mask: '+1 (###) ###-####',
        tokens: {
          '#': { pattern: /\d/ }
        }
      });

      phoneInput.addEventListener('input', () => {
        console.log('Phone - Unmasked:', phoneMask.unmasked, 'Completed:', phoneMask.completed);
      });

      // Example 2: Currency mask
      const currencyInput = document.getElementById('currency-input');
      const currencyMask = new Maska(currencyInput, {
        mask: '$###,###,###.##', // Example for up to millions, two decimal places
        reversed: true,
        tokens: {
          '#': { pattern: /\d/, multiple: true }
        }
      });

      currencyInput.addEventListener('input', () => {
        console.log('Currency - Masked:', currencyMask.masked, 'Unmasked:', currencyMask.unmasked);
      });
    });
  </script>
</body>
</html>

view raw JSON →