Inputmask

Common errors

• TypeError: $(...).inputmask is not a function

  cause The jQuery plugin for Inputmask (`jquery.inputmask.js`) was not loaded, or jQuery itself was not available before the plugin tried to attach.
  fix Verify that jQuery is included on the page, followed by `inputmask.js`, then any extension files (e.g., `inputmask.numeric.extensions.js`), and finally `jquery.inputmask.js`.

• Uncaught ReferenceError: Inputmask is not defined

  cause The main Inputmask library script (`inputmask.js`) was not loaded or imported correctly in a vanilla JavaScript setup.
  fix For ESM, ensure `import Inputmask from 'inputmask';` is at the top of your module. For script tags, verify the `inputmask.js` file is correctly linked in your HTML before its usage.

• Uncaught ReferenceError: NULL is not defined

  cause This specific error was reported when upgrading from Inputmask v5 beta to 5.0.8, indicating an issue with how `null` was handled in certain parts of the library.
  fix Ensure you are on Inputmask version 5.0.8 or later, as this issue was addressed in that release. If using an older beta, update to the latest stable v5.0.x.

• Mask not applied to input field / Input field not responding to mask pattern

  cause The JavaScript code to apply the mask is executing before the target input element exists in the DOM, or the selector used is incorrect.
  fix Wrap your masking logic inside a `DOMContentLoaded` event listener or a `$(document).ready()` block for jQuery. Double-check your element ID or class selectors to ensure they match existing HTML elements.

Warnings

• breaking Version 5.0 introduced stricter typings and some changes to internal behaviors, including how overwrite mode works. Code written for v4 may require adjustments.
  Fix: Review the official changelog and migration guide for specific API changes. Adjust custom masks and options, especially for 'overwrite' behavior.
• gotcha When using the jQuery plugin (`jquery.inputmask.js`), ensure that jQuery is loaded and available *before* both the main `inputmask.js` and `jquery.inputmask.js` scripts. Incorrect loading order will prevent the plugin from attaching to jQuery.
  Fix: Always load jQuery first, then `inputmask.js`, then any extensions (e.g., `inputmask.date.extensions.js`), and finally `jquery.inputmask.js`.
• gotcha Optional parts in masks, denoted by square brackets `[]`, should generally be placed at the end of the mask pattern. Placing them in the middle can lead to unexpected or inconsistent masking behavior.
  Fix: Refactor mask definitions to move optional segments to the end of the pattern, e.g., `(999) 999-999[9]` instead of `(999) [999] 999-9999`.
• breaking Early beta versions of Inputmask v5 (e.g., v5 beta 131+) were reported to cause conflicts with other JavaScript libraries and break page functionality when certain date formatting options like `inputformat:'yyyy-mm-dd'` were used. This was likely due to aggressive DOM manipulation or global scope pollution.
  Fix: Ensure you are using a stable release of v5.0.x (like 5.0.9 or later) as these issues were addressed. If still encountering conflicts, simplify or remove complex `inputformat` options for debugging.

Install

• npm install inputmask npm
• yarn add inputmask yarn
• pnpm add inputmask pnpm

Imports

• Inputmask
  wrong:

  const Inputmask = require('inputmask');

  correct:

  import Inputmask from 'inputmask';

  This is the standard ESM import for vanilla JavaScript usage in modern bundler environments. CommonJS `require` is also supported but less common in new projects.
• jQuery Plugin
  wrong:

  import { Inputmask } from 'inputmask/dist/jquery.inputmask';

  correct:

  import 'jquery';
  import 'inputmask/dist/inputmask';
  import 'inputmask/dist/jquery.inputmask';

  When using the jQuery plugin, jQuery must be imported or available globally *before* `inputmask` and `jquery.inputmask`. The jQuery plugin extends `$.fn.inputmask` and does not export a named symbol directly. Extension files like `inputmask.numeric.extensions.js` should be imported similarly if needed.
• Type Definitions
  wrong:

  import { InputmaskOptions } from 'inputmask';

  correct:

  import type { InputmaskOptions } from 'inputmask';

  For TypeScript projects, install `@types/inputmask` for type declarations. Use `import type` to avoid bundling unnecessary runtime code.
• Specific Extensions (ESM)

  import Inputmask from 'inputmask';
  import 'inputmask/lib/extensions/inputmask.numeric.extensions';

  For vanilla JS, extensions are loaded separately. For ESM, import them from `lib/extensions` after the main `inputmask` import. The specific path might vary slightly based on your bundler configuration.

Quickstart

Demonstrates how to apply an input mask to HTML input fields for phone numbers and dates using vanilla JavaScript and the ESM import style.

import Inputmask from 'inputmask';

// Vanilla JavaScript example
document.addEventListener('DOMContentLoaded', () => {
  const phoneInput = document.getElementById('phone-number');
  const dateInput = document.getElementById('date-input');

  if (phoneInput) {
    const phoneMask = new Inputmask('+9 (999) 999-9999');
    phoneMask.mask(phoneInput);
  }

  if (dateInput) {
    // Ensure inputmask.date.extensions is imported for 'datetime' alias
    const dateMask = new Inputmask('datetime', {
      inputFormat: 'dd/mm/yyyy',
      placeholder: 'dd/mm/yyyy'
    });
    dateMask.mask(dateInput);
  }
});

// HTML to go with the above JavaScript:
// <input type="text" id="phone-number" placeholder="+_ (___) ___-____">
// <input type="text" id="date-input" placeholder="dd/mm/yyyy">