react-imask

library7.6.1jsnpmunverified

react-imask is a React-specific plugin for the robust imask.js library, providing components and hooks to easily integrate input masking into React applications. The current stable version is 7.6.1, with minor releases occurring every few weeks, indicating active development. It differentiates itself by offering dedicated React components like IMaskInput, a Higher-Order Component IMaskMixin for extending existing inputs, and the useIMask hook for functional components. It emphasizes onAccept as the primary event handler for masked value changes, explicitly warning against the common React pattern of using onChange for this purpose. The core imask.js library underpins its powerful masking capabilities, including Number, Pattern, Enum, and Dynamic masks, alongside features like autofix, repeat blocks, and improved IME support.

web-framework

npm install react-imask

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-IMASK

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

IMaskInput

✓ import { IMaskInput } from 'react-imask';

✗ const IMaskInput = require('react-imask').IMaskInput;

IMaskInput is a named export. While a CJS build exists, ESM imports are standard for React.

IMaskMixin

✓ import { IMaskMixin } from 'react-imask';

✗ import IMaskMixin from 'react-imask/IMaskMixin';

IMaskMixin is a named export for extending existing React components as a Higher-Order Component.

useIMask

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

✗ const useIMask = require('react-imask').useIMask;

useIMask is a named export for integrating masking functionality into functional components via a React Hook.

This quickstart demonstrates the basic usage of the IMaskInput component, showing how to apply a Number mask, access internal refs, and correctly handle changes using the onAccept prop instead of onChange.

import { useRef } from 'react'; import { IMaskInput } from 'react-imask'; function MyMaskedInput() { // use ref to get access to internal "masked = ref.current.maskRef" const ref = useRef(null); const inputRef = useRef(null); return ( <IMaskInput mask={Number} radix="." value="12345" unmask={true} // true|false|'typed' ref={ref} inputRef={inputRef} // access to nested input // DO NOT USE onChange TO HANDLE CHANGES! USE onAccept INSTEAD onAccept={ // depending on prop above first argument is // `value` if `unmask=false`, // `unmaskedValue` if `unmask=true`, // `typedValue` if `unmask='typed'` (value, mask) => { console.log('Accepted value:', value); // Example: You might update a state variable here // setStateValue(value); } } // You can also pass input props directly placeholder='Enter number here' min={0} max={99999} /> ); } export default MyMaskedInput;

Debug

Known issues

gotchaDo NOT use the standard React `onChange` event handler for masked input value changes. It will not behave as expected due to how `IMaskInput` manages its internal state and mask logic. Always use the `onAccept` prop instead.

fix

Replace `onChange={(e) => ...}` with `onAccept={(value, mask) => ...}`. The `value` argument to `onAccept` depends on the `unmask` prop (e.g., `unmaskedValue` if `unmask={true}`).

affects: >=0.14.0

gotchaWhen using `IMaskMixin` with `styled-components`, be aware of the prop used to pass the internal input ref. For `styled-components` V4 and older, use `innerRef`. For newer versions (V5+), use `ref`.

fix

Check your `styled-components` version. If `V4`, pass `innerRef={inputRef}` to your styled component within the `IMaskMixin`. If `V5+`, use `ref={inputRef}`.

affects: >=0.14.0

breakingAs of v7.6.0, the `onAccept` callback is now only called on initialization if the value actually changes. Previously, it might have been called even if the initial value didn't result in a change, potentially marking validators as dirty unnecessarily.

fix

Review any logic that relied on `onAccept` firing unconditionally on component mount or initialization, especially related to form validation state. Adjust logic to explicitly check for initial value changes if needed, or rely on subsequent `onAccept` calls for user interaction.

affects: >=7.6.0

gotchaThe package moved to `type: "module"` for most packages (except Angular) in v7.1.1 and adjusted `exports` in `package.json` in v7.1.2. While a CJS build was re-added in v7.2.0, this can still cause module resolution issues in older Node.js environments or with certain bundler configurations that struggle with conditional exports or mixed ESM/CJS environments.

fix

Ensure your project uses a modern Node.js version (LTS recommended) and a bundler (e.g., Webpack 5, Rollup, Vite) that fully supports package `exports` and mixed module types. If encountering module resolution errors, explicitly configure your bundler to resolve `react-imask` as ESM or CJS if necessary.

affects: >=7.1.1

Errors

Common errors & fixes

Cannot read properties of undefined (reading 'maskRef')

Attempting to access `maskRef` on an uninitialized or incorrectly used React ref with `IMaskInput` or `useIMask` before the component has mounted or the mask instance is available.

fix

Ensure the ref is properly assigned to the `IMaskInput` component or returned by `useIMask`, and that you access `ref.current?.maskRef` only after the component has rendered and `ref.current` is not null.

Warning: A component is changing an uncontrolled input of type text to be controlled.

You are providing a `value` prop to `IMaskInput` without an `onAccept` handler, or switching between `value` and `defaultValue` props during the component's lifecycle. React treats inputs with `value` as controlled and `defaultValue` as uncontrolled.

fix

If using the `value` prop, always provide an `onAccept` handler to keep the component controlled. If you intend for the input to manage its own state after initial render, use the `defaultValue` prop instead of `value`.

TypeError: Cannot set properties of null (setting 'value')

You are trying to directly manipulate the `value` property of the underlying HTML input element (e.g., `inputRef.current.value = '...'`) before `IMaskInput` has fully initialized the mask or after it has unmounted.

fix

For `useIMask`, use the `setValue` function returned by the hook. For `IMaskInput`, update the `value` prop passed to the component directly, allowing React to manage updates correctly through the mask.

Upgrade

Version history

7.6.1latest on npm

Audit

Dependencies

reactrequiredPeer dependency for all React-based components and hooks.

Agent activity

4 hits · last 30 days

node

Resources

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

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

homepagehttps://imask.js.org/ ↗