{"id":13871,"library":"react-imask","title":"React IMask Plugin","description":"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.","status":"active","version":"7.6.1","language":"javascript","source_language":"en","source_url":"https://github.com/uNmAnNeR/imaskjs#master","tags":["javascript","react","imask","input","mask","typescript"],"install":[{"cmd":"npm install react-imask","lang":"bash","label":"npm"},{"cmd":"yarn add react-imask","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-imask","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for all React-based components and hooks.","package":"react","optional":false}],"imports":[{"note":"IMaskInput is a named export. While a CJS build exists, ESM imports are standard for React.","wrong":"const IMaskInput = require('react-imask').IMaskInput;","symbol":"IMaskInput","correct":"import { IMaskInput } from 'react-imask';"},{"note":"IMaskMixin is a named export for extending existing React components as a Higher-Order Component.","wrong":"import IMaskMixin from 'react-imask/IMaskMixin';","symbol":"IMaskMixin","correct":"import { IMaskMixin } from 'react-imask';"},{"note":"useIMask is a named export for integrating masking functionality into functional components via a React Hook.","wrong":"const useIMask = require('react-imask').useIMask;","symbol":"useIMask","correct":"import { useIMask } from 'react-imask';"}],"quickstart":{"code":"import { useRef } from 'react';\nimport { IMaskInput } from 'react-imask';\n\nfunction MyMaskedInput() {\n  // use ref to get access to internal \"masked = ref.current.maskRef\"\n  const ref = useRef(null);\n  const inputRef = useRef(null);\n\n  return (\n    <IMaskInput\n      mask={Number}\n      radix=\".\"\n      value=\"12345\"\n      unmask={true} // true|false|'typed'\n      ref={ref}\n      inputRef={inputRef}  // access to nested input\n      // DO NOT USE onChange TO HANDLE CHANGES! USE onAccept INSTEAD\n      onAccept={\n        // depending on prop above first argument is\n        // `value` if `unmask=false`,\n        // `unmaskedValue` if `unmask=true`,\n        // `typedValue` if `unmask='typed'`\n        (value, mask) => {\n          console.log('Accepted value:', value);\n          // Example: You might update a state variable here\n          // setStateValue(value);\n        }\n      }\n      // You can also pass input props directly\n      placeholder='Enter number here'\n      min={0}\n      max={99999}\n    />\n  );\n}\n\nexport default MyMaskedInput;\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Replace `onChange={(e) => ...}` with `onAccept={(value, mask) => ...}`. The `value` argument to `onAccept` depends on the `unmask` prop (e.g., `unmaskedValue` if `unmask={true}`).","message":"Do 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.","severity":"gotcha","affected_versions":">=0.14.0"},{"fix":"Check your `styled-components` version. If `V4`, pass `innerRef={inputRef}` to your styled component within the `IMaskMixin`. If `V5+`, use `ref={inputRef}`.","message":"When 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`.","severity":"gotcha","affected_versions":">=0.14.0"},{"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.","message":"As 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.","severity":"breaking","affected_versions":">=7.6.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=7.1.1"}],"env_vars":null,"search_vec":"'7.6.1':35 'activ':44 'alongsid':114 'applic':29 'autofix':117 'block':119 'capabl':106 'chang':84 'common':89 'compon':19,53,60,72 'core':99 'current':31 'dedic':51 'develop':45 'differenti':47 'dynam':112 'easili':23 'emphas':74 'enum':110 'event':79 'everi':40 'exist':64 'explicit':85 'extend':63 'featur':115 'function':71 'handler':80 'higher':58 'higher-ord':57 'hook':21,69 'imask':2,6,126 'imask.js':16,100 'imaskinput':55 'imaskmixin':61 'ime':122 'improv':121 'includ':107 'indic':43 'input':25,65,127 'integr':24 'javascript':124 'librari':17,101 'like':54,116 'mask':26,82,105,113,128 'minor':37 'number':108 'occur':39 'offer':50 'onaccept':75 'onchang':94 'order':59 'pattern':91,109 'plugin':3,12 'power':104 'primari':78 'provid':18 'purpos':97 'react':1,5,10,28,52,90,125 'react-imask':4 'react-specif':9 'releas':38 'repeat':118 'robust':15 'specif':11 'stabl':32 'support':123 'typescript':129 'underpin':102 'use':93 'useimask':68 'valu':83 'version':33 'warn':86 'week':42","created_at":"2026-04-20T01:56:44.580566+00:00","updated_at":"2026-04-20T01:56:44.580566+00:00","problems":[{"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.","cause":"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.","error":"Cannot read properties of undefined (reading 'maskRef')"},{"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`.","cause":"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.","error":"Warning: A component is changing an uncontrolled input of type text to be controlled."},{"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.","cause":"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.","error":"TypeError: Cannot set properties of null (setting 'value')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://imask.js.org/","github":"https://github.com/uNmAnNeR/imaskjs.git#master","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/react-imask","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}