Skip to content

Projects

the-mask-input

A 3.9kB input masking library for React. Drop-in <Input /> with built-in masks for CPF, CNPJ, phone, date, currency, and more.

GitHub ↗npm ↗

Live playground

mask="cpf"
import { Input } from "@g4rcez/components/input";

<Input name="cpf" mask="cpf" title="CPF" placeholder="000.000.000-00" />

mask="cnpj"
import { Input } from "@g4rcez/components/input";

<Input name="cnpj" mask="cnpj" title="CNPJ" placeholder="00.000.000/0000-00" />

mask="cellphone"
import { Input } from "@g4rcez/components/input";

<Input name="phone" mask="cellphone" title="Phone" placeholder="(00) 90000-0000" />

mask="date"
import { Input } from "@g4rcez/components/input";

<Input name="date" mask="date" title="Date" placeholder="dd/MM/yyyy" />

mask="currency" locale="pt-BR" currency="BRL"
import { Input } from "@g4rcez/components/input";

<Input
  name="price"
  mask="currency"
  locale="pt-BR"
  currency="BRL"
  title="Price"
  placeholder="R$ 0,00"
/>

mask="creditCard"
import { Input } from "@g4rcez/components/input";

<Input name="card" mask="creditCard" title="Credit card" placeholder="0000 0000 0000 0000" />

mask="uuid"
import { Input } from "@g4rcez/components/input";

<Input name="uuid" mask="uuid" title="UUID" placeholder="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" />

mask={fn} — auto-detects CPF / CNPJ
import { Input } from "@g4rcez/components/input";

const docMask = (value: string) =>
  value.replace(/\D/g, "").length <= 11 ? "cpf" : "cnpj";

<Input name="doc" mask={docMask} title="CPF or CNPJ" placeholder="000.000.000-00" />

Installation

pnpm add the-mask-input
import { Input } from "@g4rcez/components/input";

export default function App() {
  return (
    <form>
      <Input name="cpf" mask="cpf" title="CPF" placeholder="000.000.000-00" />
    </form>
  );
}

@g4rcez/components wraps the-mask-input — all named masks and custom mask features are available through it.

Built-in masks

  • cpf — 000.000.000-00
  • cnpj — 00.000.000/0000-00
  • cpfCnpj — CPF or CNPJ (auto-detects by length)
  • cep — 000000-000
  • cellphone — (00) 90000-0000
  • telephone — (00) 0000-0000
  • cellTelephone — cellphone or telephone (auto-detects)
  • int — integers only
  • color — #000 or #000000
  • creditCard — 0000 0000 0000 0000
  • date — dd/MM/yyyy
  • isoDate — yyyy/MM/dd
  • time — 00:00
  • uuid — UUID format

Custom masks

Token-based

Pass a string where each character is a token. Useful for fixed-length formats that match a single character class per position.

// Tokens: d = digit, H = hex, X = alphanumeric, x = alpha, A = uppercase, a = lowercase
import { Input } from "@g4rcez/components/input";

<Input name="doc" mask="ddd.ddd.ddd-dd" title="Custom document" placeholder="000.000.000-00" />

The same token string works for any fixed-length format. Try it live — edit the mask below and the input updates instantly. The US Social Security Number is a good starting point:

How to use tokens?
  • d = digit
  • H = hexadecimal
  • X = alphanumeric
  • x = alphabetic
  • A = uppercase
  • a = lowercase

import { Input } from "@g4rcez/components/input";

<Input
  name="custom"
  mask="ddd-dd-dddd"
  title="Custom"
  placeholder="000-00-0000"
/>

Regex array

Pass an array where each element is either a literal string (fixed character) or a RegExp (validated position). Useful for formats with mixed literals and character classes.

// Brazilian license plate: ABC-1234
import { Input } from "@g4rcez/components/input";

<Input
  name="plate"
  title="License plate"
  mask={[/[A-Z]/, /[A-Z]/, /[A-Z]/, "-", /\d/, /\d/, /\d/, /\d/]}
  placeholder="ABC-1234"
/>

Function-based

Pass a function that receives the current value and returns a mask. Useful when the mask pattern depends on what the user has typed so far.

// Validates hours 00–23 by switching the pattern when the first digit is "2"
import { Input } from "@g4rcez/components/input";

const hourMask = (value: string) => {
  const startsWithTwo = ["2", /[0-3]/, ":", /[0-5]/, /\d/];
  const defaultHour  = [/[01]/, /\d/, ":", /[0-5]/, /\d/];
  return value.startsWith("2") ? startsWithTwo : defaultHour;
};

<Input name="hour" title="Hour" mask={hourMask} placeholder="00:00" />