Table of Contents

• Installation
• Usage
• Masking Types
  • Static Masking Type
  • Optional Masking Type
  • Dynamic Masking Type
  • Alias Masking Type
  • Alternator Masking Type
  • Preprocessing Masking Type

Features

• 🎯 Simple API
• 💎 Works like a charm with Next.js
• ✨ Compatible with React Hook Form
• 🏁 Compatible with React Final Form

Install

npm i use-mask-input

Quickstart

import React from 'react'
import { withMask } from 'use-mask-input';

const App = () => {
  return (
    <input type="text" ref={withMask('9999-9999')} />
  )
}

Usage with React Hook Forms

import React from 'react';
import { useForm } from 'react-hook-form';
import { useHookFormMask } from 'use-mask-input';

function App() {
  const { register, handleSubmit } = useForm();
  const registerWithMask = useHookFormMask(register);

  ...

  return (
    <form onSubmit={onSubmit}>
      <input
        {...registerWithMask("phone", ['99 9999-9999', '99999-9999'], {
          required: true
        })}
        type="text"
      />
      <button type="submit">Submit</button>
    </form>
  );
}

Usage with React Final Form

Just use withMask normaly.

import React from 'react';
import { Form, Field } from 'react-final-form';
import { withMask } from 'use-mask-input';

function App() {
  ...
  return (
    <Form
      onSubmit={onSubmit}
      render={({ handleSubmit }) => (
        <form onSubmit={handleSubmit}>
          <Field
            name="phone"
            render={({ input, meta }) => (
              <input ref={withMask('9999-9999')} {...input} />
            )}
          />
          <button type="submit">Submit</button>
        </form>
      )}
    />
  );
}

Masking types

The mask params can be

Static Masking Type

These are the very basics of masking. The mask is defined and will not change during the input.

<input
  {...registerWithMask("phone", '99 9999-9999')}
  type="text"
/>

Optional Masking Type

It is possible to define some parts in the mask as optional. This is done by using [ ]. By example:

<input
  {...registerWithMask("phone", '99 [9]9999-9999')}
  type="text"
/>

This mask will allow input like (99) 99999-9999 or (99) 9999-9999.

Dynamic Masking Type

Dynamic masks can change during input. To define a dynamic part use { }.

{n} => n repeats {n|j} => n repeats, with j jitmasking {n,m} => from n to m repeats {n,m|j} => from n to m repeats, with j jitmasking

Also {+} and {} is allowed. + start from 1 and start from 0.

By example:

//static mask with dynamic syntax
<input
  {...registerWithMask("phone", "aa-9{4}")}
  type="text"
/>

// dynamic mask ~ the 9 def can be occur 1 to 4 times
<input
  {...registerWithMask("phone", "aa-9{4}")}
  type="text"
/>

// dynamic mask ~ email
<input
  {...registerWithMask("phone", "*{1,20}[.*{1,20}][.*{1,20}][.*{1,20}]@*{1,20}[.*{2,6}][.*{1,2}]")}
  type="text"
/>

Alias Masking Type

A Lot of common default "aliases" presets, you can use like that:

<input                         // the alias
  {...registerWithMask("date", "datetime", {
    inputFormat: "yyyy-mm-dd",
  })}
  type="text"
/>

You can use together with options like inputFormat, prefix, suffix, etc. Checkout API docs

The avaliable ones is:

• datetime
• email
• ip
• datetime
• cpf
• email
• numeric
• currency
• decimal
• integer
• percentage
• url
• ip
• mac
• ssn

Alternator Masking Type

The alternator syntax is like an OR statement. The mask can be one of the 3 choices specified in the alternator.

To define an alternator use the |. ex: "a|9" => a or 9 "(aaa)|(999)" => aaa or 999 "(aaa|999|9AA)" => aaa or 999 or 9AA "aaaa|9999" => aaa a or 9 999

<input
  {...registerWithMask("phone", "9999-9999|99999-9999")}
  type="text"
/>

// or just passing an array
<input
  {...registerWithMask("phone", ["9999-9999", "99999-9999"])}
  type="text"
/>

Preprocessing Masking Type

You can define the mask as a function that can allow you to preprocess the resulting mask. Example sorting for multiple masks or retrieving mask definitions dynamically through ajax. The preprocessing fn should return a valid mask definition.

<input
  {...registerWithMask("phone", function () {
    /* do stuff */ return ["[1-]AAA-999", "[1-]999-AAA"];
  })}
  type="text"
/>

API

withMask(mask, options?)

Attach a mask to an input via a ref:

const attach = withMask('999-9999', { clearIncomplete: true });
<input ref={attach} />;

• mask: string | string[] | (opts: Options) => string \| string[]
• options: Options (see below)

useHookFormMask(registerFn)

Integrate masking with React-Hook-Form’s register:

const maskedRegister = useHookFormMask(register);
<input {...maskedRegister('phone', '999-9999', { showMaskOnFocus: true })} />;

Options

| Option | Description | Type | Default | |----------------------------|------------------------------------------------------------------------------------------------------|------------------------------|----------------------------------------------------| | mask | Static mask, array of masks, or function returning mask(s) | string \| string[] \| fn | — | | regex | Treat the mask as a regular expression | string | — | | placeholder | Character shown for empty slots | string | "_" | | optionalmarker | Delimiters for optional sections | { start: string; end: string } | { start: "[", end: "]" } | | quantifiermarker | Delimiters for repetition ranges | { start: string; end: string } | { start: "{", end: "}" } | | groupmarker | Delimiters for grouping | { start: string; end: string } | { start: "(", end: ")" } | | alternatormarker | Character separating alternator options | string | "|" | | escapeChar | Character to escape mask meta-symbols | string | "\\" | | definitions | Custom symbol→validator mappings | Record<string,Definition> | — | | alias | Built-in preset (“datetime”, “currency”, etc.) | string | — | | inputFormat | Format string for datetime alias | string | — | | outputFormat | Format of unmasked datetime value | string | — | | displayFormat | Visual format when losing focus (datetime alias) | string | — | | clearMaskOnLostFocus | Trim placeholders on blur | boolean | true | | showMaskOnFocus | Show full mask when focused | boolean | true | | showMaskOnHover | Show mask when hovering | boolean | true | | clearIncomplete | Clear input if not fully filled on blur | boolean | false | | removeMaskOnSubmit | Strip mask chars on form submit | boolean | false | | autoUnmask | Always return unmasked value | boolean | false | | jitMasking | Just-in-time masking (only show entered chars) | boolean | false | | nullable | Return "" if no input | boolean | true | | noValuePatching | Disable .value patching hacks | boolean | false | | insertMode | Insert vs overwrite | boolean | true | | insertModeVisual | Highlight caret in overwrite mode | boolean | true | | positionCaretOnClick | Caret placement on click: "none", "lvp", "radixFocus", "select", "ignore" | string | "lvp" | | positionCaretOnTab | Move caret to last valid position on Tab | boolean | true | | tabThrough | Tab between mask sections | boolean | false | | skipOptionalPartCharacter| Character to skip optional blocks | string | " " | | numericInput | Keep caret at end for numeric | boolean | false | | rightAlign | Right-align numeric | boolean | true | | radixPoint | Decimal separator | string | "" | | groupSeparator | Thousands separator | string | "" | | digits | Fractional digits count or range | number \| string | "*" | | digitsOptional | Allow skipping fractional digits | boolean | true | | enforceDigitsOnBlur | Force show fractional digits on blur | boolean | false | | allowMinus | Permit minus sign | boolean | true | | negationSymbol | Symbols for negative (e.g. { front: "-", back: "" }) | object | { front: "-", back: "" } | | prefix | Static text prepended | string | "" | | suffix | Static text appended | string | "" | | SetMaxOnOverflow | Clamp value at max if exceeded | boolean | false | | min | Minimum allowed (numeric/datetime) | string \| number | — | | max | Maximum allowed (numeric/datetime) | string \| number | — | | step | Ctrl+↑/↓ increment step (numeric) | number | 1 | | repeat | Repeat mask N times or "*" for infinite | number \| string | 0 | | greedy | Greedy vs non-greedy repeat | boolean | false | | keepStatic | Delay switching in alternator/multi-mask scenarios | boolean \| null | (multi-mask: true) | | importDataAttributes | Read HTML data-inputmask-* attrs | boolean | true | | supportsInputType | Allow masking on specified inputmode types | string[] | ["text","tel","url","password","search"] | | ignorables | Key codes to ignore | number[] | — | | prefillYear | Pre-fill century in datetime alias | boolean | true | | casing | Force letter casing: "upper", "lower", "title" | string | — | | inputmode | Hint for on-screen keyboards (HTML inputmode) | string | "verbatim" |