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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Inputmask
✓ import Inputmask from 'inputmask';
✗ const Inputmask = require('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
✓ import 'jquery';
import 'inputmask/dist/inputmask';
import 'inputmask/dist/jquery.inputmask';
✗ import { Inputmask } from '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
✓ import type { InputmaskOptions } from 'inputmask';
✗ import { 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.
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">
Debug
Known issues
breakingVersion 5.0 introduced stricter typings and some changes to internal behaviors, including how overwrite mode works. Code written for v4 may require adjustments.fixReview the official changelog and migration guide for specific API changes. Adjust custom masks and options, especially for 'overwrite' behavior.
affects: >=5.0.0
gotchaWhen 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.fixAlways load jQuery first, then `inputmask.js`, then any extensions (e.g., `inputmask.date.extensions.js`), and finally `jquery.inputmask.js`.
affects: >=3.x
gotchaOptional 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.fixRefactor mask definitions to move optional segments to the end of the pattern, e.g., `(999) 999-999[9]` instead of `(999) [999] 999-9999`.
affects: >=3.x
breakingEarly 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.fixEnsure 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.
affects: 5.0.0-beta.x (specifically >=beta.131)
Errors
Common errors & fixes
TypeError: $(...).inputmask is not a function
The jQuery plugin for Inputmask (`jquery.inputmask.js`) was not loaded, or jQuery itself was not available before the plugin tried to attach.
fixVerify 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
The main Inputmask library script (`inputmask.js`) was not loaded or imported correctly in a vanilla JavaScript setup.
fixFor 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
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.
fixEnsure 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
The JavaScript code to apply the mask is executing before the target input element exists in the DOM, or the selector used is incorrect.
fixWrap 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.
Audit
Dependencies
jqueryoptionalRequired only if using the jQuery plugin version of Inputmask. The core library works independently.