use-mask-input

Input masks for React and Vue 3, built on the Inputmask engine.

On React it works with plain inputs, React Hook Form, TanStack Form, shadcn/ui and Ant Design. On Vue it ships a directive and a composable, and needs no adapter for vee-validate.

npm install use-mask-input

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

function PhoneInput() {
  const ref = useMaskInput({ mask: '(99) 99999-9999' });
  return <input ref={ref} />;
}

Or in Vue:

<script setup>
import { vMaskInput } from 'use-mask-input/vue';
</script>

<template>
  <input v-mask-input="'(99) 99999-9999'" />
</template>

With React Hook Form

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

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

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input {...registerWithMask('phone', '(99) 99999-9999')} />
      <input {...registerWithMask('email', 'email')} />
      <button type="submit">Submit</button>
    </form>
  );
}

With TanStack Form

import { useForm } from '@tanstack/react-form';
import { useTanStackFormMask } from 'use-mask-input';

function MyForm() {
  const maskField = useTanStackFormMask();
  const form = useForm({
    defaultValues: { phone: '' },
    onSubmit: async ({ value }) => console.log(value),
  });

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        event.stopPropagation();
        void form.handleSubmit();
      }}
    >
      <form.Field name="phone">
        {(field) => {
          const inputProps = maskField(
            '(99) 99999-9999',
            {
              name: field.name,
              value: field.state.value,
              onBlur: field.handleBlur,
              onChange: (event) => field.handleChange(event.target.value),
            },
          );

          return <input {...inputProps} placeholder="(00) 00000-0000" />;
        }}
      </form.Field>
    </form>
  );
}

See the full TanStack Form Integration guide.

With Ant Design

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

function EmailInput() {
  const ref = useMaskInputAntd({ mask: 'email' });
  return <Input ref={ref} />;
}

See the full Ant Design Integration guide.

With shadcn/ui

shadcn/ui's Input exposes an HTMLInputElement ref directly, so the base hooks work without any adapter:

import { useMaskInput } from 'use-mask-input';
import { Input } from '@/components/ui/input';

function CepField() {
  const ref = useMaskInput({ mask: '99999-999' });
  return <Input ref={ref} placeholder="00000-000" />;
}

See the full shadcn/ui Integration guide.

With Vue 3

Import from the use-mask-input/vue subpath. In <script setup> the directive needs no registration, because Vue resolves a vMaskInput binding to v-mask-input on its own:

<script setup>
import { vMaskInput } from 'use-mask-input/vue';
import { ref } from 'vue';

const cpf = ref('');
</script>

<template>
  <input v-model="cpf" v-mask-input="{ mask: 'cpf', options: { autoUnmask: true } }" />
  <!-- displays 123.456.789-01, and cpf holds 12345678901 -->
</template>

v-model works without an adapter, and so does vee-validate. See the full Vue 3 guide.

APIs

React

API	When to use
useMaskInput	Default choice. Returns a ref callback.
useHookFormMask	Wraps React Hook Form's register.
useTanStackFormMask	Wraps TanStack Form input props with mask support.
withMask	Non-hook ref callback. Requires React.memo.
withHookFormMask	Non-hook mask for registered fields. Requires React.memo.
withTanStackFormMask	Non-hook mask for TanStack input props. Requires React.memo.
useMaskInputAntd	useMaskInput for Ant Design.
useHookFormMaskAntd	useHookFormMask for Ant Design.

Vue

API	When to use
vMaskInput	Default choice. A directive, usable as v-mask-input.
useMaskInput (Vue)	Composable, for imperative reads and unmaskedValue().

Both

API	When to use
formatWithMask	Format a stored value without a mounted element.
unformatWithMask	Strip a mask from a formatted value.

Full signatures and parameters in the API Reference.

Mask Types

• Static Mask: fixed patterns like 999-999
• Dynamic Mask: variable-length patterns
• Optional Mask: masks with optional parts
• Alias Mask: built-in presets (email, currency, datetime, ...)
• Alternator Mask: multiple patterns
• Preprocessing Mask: dynamic masks with functions