IMask.js

Common errors

• IMask is not defined

  cause The IMask library script was not loaded or initialized before attempting to use it, or it's not correctly imported in an ESM context.
  fix Ensure `IMask` is imported as `import IMask from 'imask';` at the top of your module or that the `<script src="https://unpkg.com/imask"></script>` tag is placed before any script attempting to use `IMask` in a global context.

• TypeError: IMask.InputMask is not a constructor

  cause This error can occur in specific build environments (e.g., production bundles) where the `InputMask` component might not be correctly exposed or tree-shaken, or when trying to instantiate it directly in a way not intended by the library.
  fix Always initialize IMask using the main factory function: `const mask = IMask(element, options);` Do not try to directly construct `IMask.InputMask` or similar internal components. Ensure your bundler is configured correctly if tree-shaking is aggressively removing parts of `imask`.

• Value not updating or mask not applying on component mount (React/Vue)

  cause Framework-specific plugins might have nuances. For React hooks (`useIMask`), issues can arise if the `value` prop is not handled correctly, or if `onAccept` is not called as expected. Old versions might not apply the mask on initial value set.
  fix For React/Vue plugins, ensure you are on the latest minor version. In `v7.6.0`, `onAccept` is now only called on init if the value changes, which might affect validation logic. Always refer to the specific plugin documentation for correct lifecycle and prop handling. Ensure `ref` is passed correctly in React hooks if needed.

• Copy/paste doesn't work as expected with complex masks (e.g., numbers with separators)

  cause IMask's internal handling of pasted input might not correctly interpret non-mask characters or resolve complex formatting variations during paste operations. This is especially noticeable with localized number formats.
  fix Test copy/paste functionality thoroughly with your specific mask configuration. For number masks, ensure `thousandsSeparator` and `radix` options are correctly set to match expected input formats. Consider implementing a custom `prepare` callback to normalize pasted values if default behavior is insufficient.

Warnings

• breaking Starting from `v7.1.2`, the explicit `esm` part in import paths for specific mask modules can be skipped. This means `import 'imask/esm/masked/number'` should now be `import 'imask/masked/number';`. While the old path might still work due to compatibility, updating is recommended.
  Fix: Update import paths from `import 'imask/esm/masked/some-mask'` to `import 'imask/masked/some-mask';`.
• breaking In `v7.1.1`, the `type: "module"` was set for all packages except Angular. This change primarily affects CommonJS environments or older build setups, potentially leading to module resolution issues if not configured correctly for ESM. `v7.2.0` later added a `cjs` build, mitigating some of these issues but requiring awareness.
  Fix: Ensure your build system correctly handles ESM modules. For CJS environments, explicit `require('imask/cjs/some-path')` might be necessary, though `import IMask from 'imask'` should generally resolve correctly if `package.json` `exports` map correctly.
• gotcha When applying `IMask` to an input element, always use `type="text"`. Other input types (e.g., `type="number"`, `type="tel"`) are not officially supported and may lead to unexpected behavior or conflicts with native browser input handling.
  Fix: Ensure all HTML input elements intended for `IMask.js` have `type="text"`.
• gotcha For optimal tree-shaking and reduced bundle size, individual mask types (e.g., `Number`, `Date`) should be imported via their specific paths (e.g., `import 'imask/masked/number'`) rather than attempting to destructure them from the main `imask` import. The latter will pull in the entire library.
  Fix: Use side-effect imports for specific masked types: `import IMask from 'imask'; import 'imask/masked/number';`.
• gotcha IMask operates by creating an internal 'masked input' layer. Directly manipulating the original HTML input element's properties (like `disabled` state or classes) dynamically via JavaScript or a framework's data binding might not reflect on the visible masked input. Events should also be attached to the `IMask` instance callbacks.
  Fix: Interact with the `IMask` instance (e.g., `mask.updateOptions()`, `mask.value = '...'`) to control the masked input. Use `onAccept` or `onComplete` callbacks for events. If modifying the underlying DOM element directly, ensure changes are synchronized or considered in the context of `IMask`'s internal handling.
• gotcha Intermediate validation states for complex masks like `Date` or `RegExp` can be tricky. A mask like `/^123$/` will only validate the complete string '123' and prevent any input until it matches perfectly. Always consider intermediate values for masks, otherwise, input might not be possible.
  Fix: When using `RegExp` or `Function` masks, design them to validate intermediate states gracefully. For complex cases, `Pattern` or `Function` masks are often more suitable, or implement custom `validate` callbacks that handle partial inputs.

Install

• npm install imask npm
• yarn add imask yarn
• pnpm add imask pnpm

Imports

• IMask
  wrong:

  const IMask = require('imask');

  correct:

  import IMask from 'imask';

  While CJS is supported since v7.2.0, ESM `import` is the recommended modern approach. The `require` syntax might lead to issues with tree-shaking or module resolution in some bundlers.
• Masked options (e.g., Number, Date)
  wrong:

  import { Number } from 'imask'; // Number, Date, etc., are not directly exported for tree-shaking
  import IMask, { Number } from 'imask';

  correct:

  import IMask from 'imask';
  import 'imask/masked/number'; // for number mask
  // or specific masks like import 'imask/masked/date';
  const element = document.getElementById('my-input');
  const mask = IMask(element, { mask: Number });

  For optimal tree-shaking and to reduce bundle size, specific mask types (like `Number`, `Date`, `PatternMasked`) should be imported for their side-effects via path imports (e.g., `imask/masked/number`). This populates the `IMask` factory with the necessary mask definitions.
• IMask.Masked options (e.g., IMask.MaskedPattern)
  wrong:

  import { MaskedPattern } from 'imask';
  import { MaskedPattern } from 'imask/masked/pattern';

  correct:

  import IMask from 'imask';
  const patternMasked = IMask.MaskedPattern({ mask: '+{7}(000)000-00-00' });

  Constructors for specific masked classes (e.g., `MaskedPattern`, `MaskedNumber`) are typically accessed as properties of the main `IMask` object after their respective modules have been imported (which usually happens implicitly with the main `imask` import, or explicitly for tree-shaking).

Quickstart

This quickstart demonstrates setting up two common masks: a phone number using a pattern mask and a currency input using a number mask. It highlights basic initialization, options like `lazy` and `placeholderChar`, and how to access `value` and `unmaskedValue`.

import IMask from 'imask';

document.addEventListener('DOMContentLoaded', () => {
  const phoneInput = document.getElementById('phone-input');
  if (phoneInput) {
    const phoneMask = IMask(phoneInput, {
      mask: '+{7}(000)000-00-00',
      lazy: false, // show placeholder from start
      placeholderChar: '_'
    });
    
    // Example of accessing values
    phoneInput.addEventListener('blur', () => {
      console.log('Masked Value:', phoneMask.value);
      console.log('Unmasked Value:', phoneMask.unmaskedValue);
    });
  }

  const currencyInput = document.getElementById('currency-input');
  if (currencyInput) {
    const currencyMask = IMask(currencyInput, {
      mask: Number,
      thousandsSeparator: ' ',
      scale: 2, // digits after point
      signed: false, // disallow negative
      padFractionalZeros: true, // if true, then pads zeros at end to the length of scale
      normalizeZeros: true, // appends or removes zeros at the end of the fractional part of a number
      mapToRadix: ['.', ','], // to change radix point for `.` or `,` from keyboard
      radix: '.', // fractional delimiter
      autofix: true // automatically fix incomplete input
    });
  }
});

// To make this runnable in a browser, you'd need HTML like:
// <input type="text" id="phone-input" placeholder="+7(___)___-__-__">
// <input type="text" id="currency-input" placeholder="0.00">