react-maskara

Installation

npm i react-maskara

Requires React 19 or later.

MaskedInput

A ready-to-use, unstyled component that wraps a native <input> and applies masking on every keystroke. Best for standalone inputs where you don't need a form library. Accepts all standard HTML input attributes alongside the mask prop.

import { MaskedInput } from "react-maskara"

export const Form = () => {
  return (
    <form>
      <MaskedInput
        mask="99/99/9999"
        placeholder="dd/mm/yyyy"
        id="date"
        name="date"
      />
    </form>
  )
}

Props

Prop	Type	Required	Description
mask	string	Yes	The mask pattern string. See Mask Patterns for syntax.
ref	Ref<HTMLInputElement>	No	Forwarded to the underlying `<input>` element via `useImperativeHandle`.
...props	InputHTMLAttributes	No	All standard HTML input attributes (`id`, `name`, `placeholder`, `type`, `className`, etc.). `maxLength` is set automatically to match the mask length.

withMask

A utility function that injects masking behavior into an existing input element by wrapping its ref callback. Designed for use with form libraries like react-hook-form or Formik, where you spread registration props onto a native <input>. It can also be used with an empty object for standalone inputs when you prefer not to use the MaskedInput component.

import { withMask } from "react-maskara"
import { useForm } from "react-hook-form"

export const Form = () => {
  const { register, handleSubmit } = useForm()

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input
        {...withMask(register("card"), { mask: "9999 9999 9999 9999" })}
        placeholder="XXXX XXXX XXXX XXXX"
        type="tel"
        autoComplete="cc-number"
      />
    </form>
  )
}

Without a form library, pass an empty object as the first argument:

<input
  {...withMask({}, { mask: "(999) 999-9999" })}
  placeholder="(___) ___-____"
  type="tel"
/>

Parameters

Parameter	Type	Description
el	{ ref?: RefCallback<HTMLInputElement> }	The props object to extend. Typically the return value of `register()` from a form library, or `{}` for standalone use. The original `ref` callback, if present, is preserved and called after the mask ref runs.
options.mask	string	The mask pattern string. See Mask Patterns for syntax.

Returns the same object type with the ref replaced by a callback that attaches an input event listener for masking and sets maxLength to the mask length. The listener is cleaned up automatically when the element is unmounted.

Mask Patterns

A mask is a string where certain characters define what the user can type and all other characters are treated as fixed separators that are inserted automatically.

Character	Allowed input
9	Any digit — 0 through 9
a	Any letter — a–z or A–Z
*	Any alphanumeric character — 0–9, a–z, or A–Z

Any character that is not 9, a, or * is a literal separator. It is inserted into the input automatically when the user's cursor reaches that position — no need to type it manually.

Common examples

Format	Mask	Example output
Date	99/99/9999	31/12/2025
Phone (US)	(999) 999-9999	(555) 867-5309
Credit card	9999 9999 9999 9999	4111 1111 1111 1111
SSN (US)	999-99-9999	123-45-6789
ZIP code (US)	99999	90210
Time	99:99	14:30