Registry / web-framework / use-mask-input

use-mask-input

library3.9.0jsnpmunverified

use-mask-input is a React hook library providing flexible input masking capabilities for various form libraries and plain HTML inputs. It currently stands at version 3.9.0 and receives active development, with minor releases adding features like new mask aliases and integrations, and patch releases for optimizations and bug fixes. Key differentiators include out-of-the-box support for popular form libraries such as React Hook Form, TanStack Form, and Ant Design, as well as a rich set of built-in mask aliases for common patterns like Brazilian banking information, CPF, CNPJ, currency, email, and date/time. The library focuses on providing a performant and developer-friendly API through custom hooks and higher-order functions, ensuring seamless integration into modern React applications. It primarily targets client-side usage within a React context.

web-framework

npm install use-mask-input

github ↗package ↗

INSTALL

IMPORT

SIG · USE-MASK-INPUT

use-mask-input

web-frameworkjavascriptv3.9.0

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.

useMaskInput

✓ import { useMaskInput } from 'use-mask-input';

✗ import useMaskInput from 'use-mask-input';

This is the primary named export for basic input masking.

useHookFormMask

✓ import { useHookFormMask } from 'use-mask-input';

✗ import { useMaskInput } from 'use-mask-input/hook-form';

Specifically for integrating with React Hook Form's `register` function. Do not confuse with the base `useMaskInput`.

useTanStackFormMask

✓ import { useTanStackFormMask } from 'use-mask-input';

✗ import { TanStackFormInputProps } from 'use-mask-input';

Hook for integrating with TanStack Form. Types like `TanStackFormInputProps` are also exported but not the primary runtime import.

useMaskInputAntd

✓ import { useMaskInputAntd } from 'use-mask-input/antd';

✗ import { useMaskInputAntd } from 'use-mask-input';

Ant Design specific hooks are exported from a sub-path to minimize bundle size for those not using Ant Design.

This quickstart demonstrates how to integrate `use-mask-input` with React Hook Form to apply phone and email masks to input fields. It shows the `useHookFormMask` hook in action, enabling masked input with form validation and submission.

import React from 'react'; import { useForm } from 'react-hook-form'; import { useHookFormMask } from 'use-mask-input'; function ContactForm() { const { register, handleSubmit } = useForm({ defaultValues: { phone: '', email: '' } }); const registerWithMask = useHookFormMask(register); const onSubmit = (data) => { console.log('Form Submitted:', data); // In a real app, you'd send this data to a backend or handle it. alert(`Submitted Phone: ${data.phone}, Email: ${data.email}`); }; return ( <form onSubmit={handleSubmit(onSubmit)} className="space-y-4 p-4 border rounded-lg"> <div className="flex flex-col"> <label htmlFor="phone" className="mb-1 font-medium">Phone Number</label> <input id="phone" type="text" className="border rounded-md p-2" placeholder="(00) 00000-0000" {...registerWithMask('phone', '(99) 99999-9999')} /> </div> <div className="flex flex-col"> <label htmlFor="email" className="mb-1 font-medium">Email Address</label> <input id="email" type="text" className="border rounded-md p-2" placeholder="example@domain.com" {...registerWithMask('email', 'email')} /> </div> <button type="submit" className="bg-blue-500 hover:bg-blue-600 text-white font-bold py-2 px-4 rounded" > Submit </button> </form> ); } // Example usage in a root component (e.g., App.js) // function App() { // return ( // <div className="container mx-auto mt-10"> // <h1 className="text-3xl font-bold mb-5">Input Mask Demo</h1> // <ContactForm /> // </div> // ); // } // export default App;

Debug

Known issues

breakingOlder versions of `use-mask-input` might not fully support ESM environments or modern React features. Ensure you are on a recent major version (like v3.x) for optimal compatibility.

fix

Upgrade to `use-mask-input@^3.0.0` or later. Check the official documentation for specific migration guides if upgrading from a very old version.

affects: <3.0.0

gotchaWhen using `withMask` or `withHookFormMask` HOCs, it is crucial to wrap the component with `React.memo` to prevent unnecessary re-renders and ensure optimal performance, as specified in the API documentation.

fix

Ensure components wrapped with `withMask` or `withHookFormMask` are also wrapped with `React.memo`, e.g., `const MyMaskedInput = React.memo(withMask(MyInput));`

affects: >=3.0.0

gotchaFor Ant Design integration, specific hooks like `useMaskInputAntd` and `useHookFormMaskAntd` must be imported from the `use-mask-input/antd` sub-path. Importing them directly from 'use-mask-input' will result in undefined symbols or incorrect behavior.

fix

Change your import statements from `import { useMaskInputAntd } from 'use-mask-input';` to `import { useMaskInputAntd } from 'use-mask-input/antd';`.

affects: >=3.7.0

gotchaWhen integrating with TanStack Form, ensure you pass the field's `name`, `value`, `onBlur`, and `onChange` handlers correctly to the `maskField` function to maintain proper form state and masking behavior.

fix

Refer to the TanStack Form usage example in the documentation, specifically how `inputProps` are destructured and passed to the input element: `const inputProps = maskField(mask, { name: field.name, value: field.state.value, onBlur: field.handleBlur, onChange: (event) => field.handleChange(event.target.value) });`

affects: >=3.9.0

Errors

Common errors & fixes

Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

Attempting to call `useMaskInput` or other hooks outside of a React functional component or custom hook.

fix

Ensure all `use-mask-input` hooks are called within the top-level of a React functional component or within another custom hook.

TypeError: Cannot read properties of undefined (reading 'useRef')

Using an outdated version of React (older than 17) which does not meet the peer dependency requirements.

fix

Upgrade your React and React DOM packages to version 17 or higher: `npm install react@^17 react-dom@^17`.

Module not found: Error: Can't resolve 'use-mask-input/antd'

A bundler (like Webpack or Vite) cannot find the specific entry point for Ant Design integrations. This usually happens if the package is not correctly installed or the bundler configuration is not picking up sub-path exports, or there's a typo.

fix

Verify that `use-mask-input` is correctly installed. Check your import paths. If the issue persists, ensure your bundler supports sub-path exports from `package.json` or explicitly configure it.

Upgrade

Version history

3.9.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency for React applications. Minimum version is 17.

react-domrequiredPeer dependency for rendering React components. Minimum version is 17.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/eduardoborges/use-mask-input ↗

packagehttps://www.npmjs.com/package/use-mask-input ↗