use-mask-input

https://use-mask-input.eduardoborges.dev
Admin
use-mask-input is a lightweight library that provides input masks for React and Vue 3 applications...
Tokens:47,039
Snippets:419
Trust Score:4.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install use-mask-input and antd

Source: https://use-mask-input.eduardoborges.dev/antd

Install both use-mask-input and antd packages via npm.

```bash
npm install use-mask-input antd  
```

--------------------------------

### Install use-mask-input via npm

Source: https://use-mask-input.eduardoborges.dev/auth.md

Install the use-mask-input library from npm. No authentication is required for this public documentation site; authentication for your own applications is your responsibility.

```bash
npm install use-mask-input
```

--------------------------------

### Install use-mask-input and @tanstack/react-form

Source: https://use-mask-input.eduardoborges.dev/tanstack-form

Install the required packages for integrating use-mask-input with TanStack Form.

```bash
npm install use-mask-input @tanstack/react-form  
```

--------------------------------

### Run the example app

Source: https://use-mask-input.eduardoborges.dev/vue

Command to run the example app in the repository, which is a Vite + Vue 3 + vee-validate app covering all mask features.

```bash
pnpm dev:vue
```

--------------------------------

### formatWithMask usage example

Source: https://use-mask-input.eduardoborges.dev/api-reference

Example of using formatWithMask to format a raw value. Imports the function from 'use-mask-input' and demonstrates formatting a CPF and a custom mask.

```typescript
import { formatWithMask } from 'use-mask-input';  
  
formatWithMask('12345678900', 'cpf'); // '123.456.789-00'  
formatWithMask('999999', '999-999'); // '999-999'  
```

--------------------------------

### useMaskInput phone input example

Source: https://use-mask-input.eduardoborges.dev/api-reference

Example of using useMaskInput to mask a phone input. Attach the returned ref callback to an input element; the placeholder shows the unmasked format.

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

function PhoneInput() {  
  const maskRef = useMaskInput({  
    mask: '(99) 99999-9999',  
  });  

  return <input ref={maskRef} placeholder="(00) 00000-0000" />;  
}  
```

--------------------------------

### Vue vMaskInput directive: script setup and global registration

Source: https://use-mask-input.eduardoborges.dev/llms.txt

Use the vMaskInput directive in Vue. In <script setup>, importing the variable named vMaskInput is enough; Vue resolves any vFoo binding to v-foo, so no registration or plugin is needed. Outside <script setup>, register it globally with createApp(App).directive('mask-input', vMaskInput).

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

<template>
  <input v-mask-input="'cpf'" />
</template>
```

```ts
import { createApp } from 'vue';
import { vMaskInput } from 'use-mask-input/vue';

createApp(App).directive('mask-input', vMaskInput);
```

--------------------------------

### useMaskInput usage example

Source: https://use-mask-input.eduardoborges.dev/llms-full.txt

Example of using the useMaskInput hook to apply a phone mask to an input. The returned ref callback is attached via the ref prop, and the hook manages ref stability internally.

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

function PhoneInput() {
  const maskRef = useMaskInput({
    mask: '(99) 99999-9999',
  });

  return <input ref={maskRef} placeholder="(00) 00000-0000" />;
}
```

--------------------------------

### React useMaskInput basic example

Source: https://use-mask-input.eduardoborges.dev/intro

Basic React usage of the useMaskInput hook to apply a phone mask to an input.

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

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

--------------------------------

### unformatWithMask usage example

Source: https://use-mask-input.eduardoborges.dev/api-reference

Example of using unformatWithMask to remove a mask from a formatted value. Imports the function from 'use-mask-input' and demonstrates unformatting a CPF.

```typescript
import { unformatWithMask } from 'use-mask-input';  
  
unformatWithMask('123.456.789-00', 'cpf'); // '12345678900'  
```

--------------------------------

### Basic datetime mask example

Source: https://use-mask-input.eduardoborges.dev/llms-full.txt

Shows how to use the datetime alias with a custom input format. The ref is attached to an input element, and placeholder is set to illustrate expected input format.

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

function DateInput() {
  const dateMask = useMaskInput({
    mask: 'datetime',
    options: {
      inputFormat: 'dd/mm/yyyy',
    },
  });

  return (
    <input
      type="text"
      ref={dateMask}
      placeholder="DD/MM/YYYY"
    />
  );
}
```

--------------------------------

### Dynamic Mask examples: useMaskInput with repetition syntax

Source: https://use-mask-input.eduardoborges.dev/llms.txt

Uses curly-brace repetition syntax for variable-length inputs. JIT masking only shows mask characters as the user types.

```TSX
// Exactly 4 digits after letters
useMaskInput({ mask: 'aa-9{4}' })

// 1 to 10 digits
useMaskInput({ mask: '9{1,10}' })

// 2 letters followed by 4–8 digits
useMaskInput({ mask: 'A{2}-9{4,8}' })

// Email (manual dynamic pattern)
useMaskInput({ mask: '*{1,20}[.*{1,20}][.*{1,20}][.*{1,20}]@*{1,20}[.*{2,6}][.*{1,2}]' })
```

```TSX
useMaskInput({
  mask: '9{4|1}',
  options: { jitMasking: true },
})
```

--------------------------------

### Email Input with useMaskInputAntd

Source: https://use-mask-input.eduardoborges.dev/antd

Use this snippet to create an email input with a mask. The mask 'email' applies email formatting. The placeholder shows an example email address.

```jsx
import { Input } from 'antd';  

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

  

function EmailInput() {  
  const maskRef = useMaskInputAntd({ mask: 'email' });  
  return <Input ref={maskRef} placeholder="name@example.com" />;  
}  

```

--------------------------------

### Watching form values with Form.useWatch

Source: https://use-mask-input.eduardoborges.dev/antd

Use Form.useWatch to observe masked values in real time. This example watches all form values and displays the email value.

```tsx
import { Form, Input, Typography } from 'antd';  
import { useMaskInputAntd } from 'use-mask-input/antd';  
  
function WatchExample() {  
  const [form] = Form.useForm();  
  const values = Form.useWatch([], form);  
  
  const maskRef = useMaskInputAntd({ mask: 'email' });  
  
  return (  
    <Form form={form} layout="vertical">  
      <Form.Item name="email" label="Email">  
        <Input ref={maskRef} />  
      </Form.Item>  
      <Typography.Text code>  
        Current value: {values?.email}  
      </Typography.Text>  
    </Form>  
  );  
}  
```

--------------------------------

### Use vMaskInput directive in script setup

Source: https://use-mask-input.eduardoborges.dev/vue

Use the vMaskInput directive in a Vue 3 single-file component. Importing the directive in <script setup> is sufficient; Vue resolves the v-mask-input binding automatically without registration or a plugin.

```html
<script setup>

import { vMaskInput } from 'use-mask-input/vue';  

</script>  

<template>  
  <input v-mask-input="'cpf'" />  
</template>
```

--------------------------------

### withMask phone input example

Source: https://use-mask-input.eduardoborges.dev/api-reference

Example of using `withMask` with a phone mask pattern. The component is wrapped with `React.memo` to keep the ref callback identity stable across parent re-renders, preventing flickering and cursor loss. The mask pattern `'(99) 99999-9999'` is applied to the input.

```jsx
import { memo } from 'react';  
import { withMask } from 'use-mask-input';  

const PhoneInput = memo(() => {  
  return (  
    <input  
      ref={withMask('(99) 99999-9999')}  
      placeholder="(00) 00000-0000"  
    />  
  );  
});  

```

--------------------------------

### Optional Mask examples: useMaskInput with optional sections

Source: https://use-mask-input.eduardoborges.dev/llms.txt

Sections in square brackets are optional. Examples include phone numbers with optional digits and credit card groups.

```TSX
// Phone with optional 9th digit (mobile vs landline)
useMaskInput({ mask: '(99) [9]9999-9999' })

// Phone with optional area code
useMaskInput({ mask: '[99] 9999-9999' })

// International phone: optional country code + optional area code
useMaskInput({ mask: '[+99] [9]9999-9999' })

// Credit card with optional groups
useMaskInput({ mask: '9999[ 9999][ 9999][ 9999]' })
```

--------------------------------

### useTanStackFormMask usage example

Source: https://use-mask-input.eduardoborges.dev/llms-full.txt

Example of using useTanStackFormMask with TanStack Form. It wraps field state and handlers into masked input props, preserving all original handlers and values.

```tsx
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.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>
  );
}
```

--------------------------------

### Override alias options (prefix 'US$ ' for 'brl-currency')

Source: https://use-mask-input.eduardoborges.dev/vue

Aliases carry defaults that your options override individually. This example changes only the prefix while keeping the alias's radix point and group separator.

```html
<input v-mask-input="{ mask: 'brl-currency', options: { prefix: 'US$ ' } }" />  
```

--------------------------------

### Basic usage of alias masks in React and Vue

Source: https://use-mask-input.eduardoborges.dev/tutorial-basics/alias-mask

Use the alias name as the mask. The React example uses useMaskInput with the 'datetime' alias and an inputFormat option. The Vue example uses the v-mask-input directive with the same alias, since both share one engine.

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

function DateInput() {  
  const dateMask = useMaskInput({  
    mask: 'datetime',  
    options: {  
      inputFormat: 'dd/mm/yyyy',  
    },  
  });  

  return (  
    <input  
      type="text"  
      ref={dateMask}  
      placeholder="DD/MM/YYYY"  
    />  
  );  
}  
```

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

<template>  
  <input v-mask-input="'datetime'" />  
</template>  
```

--------------------------------

### Basic Static Mask with useMaskInput

Source: https://use-mask-input.eduardoborges.dev/llms-full.txt

Basic static mask example using the '9999-9999' pattern for a phone number input. The mask is passed to useMaskInput and the returned ref is attached to the input element.

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

function PhoneInput() {
  const phoneMask = useMaskInput({
    mask: '9999-9999',
  });

  return (
    <input
      type="tel"
      ref={phoneMask}
      placeholder="0000-0000"
    />
  );
}
```

--------------------------------

### Preprocessing Mask examples: useMaskInput with function

Source: https://use-mask-input.eduardoborges.dev/llms.txt

Pass a function to compute the mask pattern at evaluation time. Useful for conditional logic, country-specific formats, or patterns fetched from an API.

```TSX
// Country-specific phone
function CountryPhoneInput({ country }: { country: string }) {
  const ref = useMaskInput({
    mask: function () {
      const formats: Record<string, string> = {
        US: '(999) 999-9999',
        BR: '(99) 99999-9999',
        UK: '9999 999 999',
        DE: '9999 9999999',
      };
      return formats[country] || '9999-9999';
    },
  });
  return <input ref={ref} />;
}

// Input type selector
useMaskInput({
  mask: function () {
    if (inputType === 'phone') return ['(99) 9999-9999', '(99) 99999-9999'];
    if (inputType === 'email') return 'email';
    if (inputType === 'postal') return '99999-999';
    return '9999-9999';
  },
})
```

--------------------------------

### Alternator Mask examples: useMaskInput with multiple patterns

Source: https://use-mask-input.eduardoborges.dev/llms.txt

Multiple valid patterns separated by | or as an array. The engine selects the pattern that matches the current input. Array syntax is recommended for more than 2 patterns.

```TSX
// Landline or mobile
useMaskInput({ mask: '(99) 9999-9999|(99) 99999-9999' })

// Array syntax (recommended for more than 2 patterns)
useMaskInput({ mask: ['9999-9999', '99999-9999'] })

// Credit card types
useMaskInput({ mask: ['9999 9999 9999 9999', '9999 999999 99999'] })

// Date separators
useMaskInput({ mask: '99/99/9999|99-99-9999|99.99.9999' })

// Old and Mercosul license plates
useMaskInput({ mask: ['AAA-9999', 'AAA9A99'] })
```

--------------------------------

### Register vMaskInput globally

Source: https://use-mask-input.eduardoborges.dev/vue

Register the vMaskInput directive globally when not using <script setup>. This is needed for components that do not import the directive locally.

```javascript
import { createApp } from 'vue';  

import { vMaskInput } from 'use-mask-input/vue';  

createApp(App).directive('mask-input', vMaskInput);
```

--------------------------------

### Optional section mask pattern

Source: https://use-mask-input.eduardoborges.dev/llms.txt

Example mask with an optional bracketed prefix, allowing input with or without the prefix.

```mask-pattern
[+99] 9999-9999
```

--------------------------------

### IP alias example

Source: https://use-mask-input.eduardoborges.dev/llms-full.txt

Uses the 'ip' alias to mask IPv4 addresses.

```tsx
function IpAddressInput() {
  const ipMask = useMaskInput({
    mask: 'ip',
  });

  return (
    <input
      type="text"
      ref={ipMask}
      placeholder="192.168.0.1"
    />
  );
}
```

--------------------------------

### Vue v-mask-input with v-model and autoUnmask

Source: https://use-mask-input.eduardoborges.dev/intro

Vue 3 example using v-mask-input with v-model and autoUnmask option. The comment shows the displayed value and the unmasked value stored in the ref.

```vue
<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>  
```

--------------------------------

### Currency alias example

Source: https://use-mask-input.eduardoborges.dev/llms-full.txt

Shows the currency alias with Brazilian Real configuration: prefix R$ , group separator dot, decimal comma, 2 digits.

```tsx
function CurrencyInput() {
  const currencyMask = useMaskInput({
    mask: 'currency',
    options: {
      prefix: 'R$ ',
      groupSeparator: '.',
      radixPoint: ',',
      digits: 2,
    },
  });

  return (
    <input
      type="text"
      ref={currencyMask}
      placeholder="R$ 0,00"
    />
  );
}
```

--------------------------------

### Pass mask as prop with VueMaskBinding type

Source: https://use-mask-input.eduardoborges.dev/vue

VueMaskBinding is useful when passing a mask down as a prop. The example defines a prop typed as VueMaskBinding and uses it in the template.

```html
<script setup lang="ts">  

import { vMaskInput } from 'use-mask-input/vue';  

import type { VueMaskBinding } from 'use-mask-input/vue';  

  

defineProps<{ mask: VueMaskBinding }>();  

</script>  

  

<template>  

  <input v-mask-input="mask" />  

</template>  
```

--------------------------------

### useTanStackFormMask usage with TanStack Form

Source: https://use-mask-input.eduardoborges.dev/llms.txt

React component example showing how to use useTanStackFormMask with TanStack Form's useForm and Field components. It demonstrates masking a phone input with a pattern and a currency input with the 'currency' alias and custom options.

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

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

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        e.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.Field name="amount">
        {(field) => {
          const inputProps = maskField(
            'currency',
            {
              name: field.name,
              value: field.state.value,
              onBlur: field.handleBlur,
              onChange: (event) => field.handleChange(event.target.value),
            },
            { prefix: '$ ', groupSeparator: ',', digits: 2, rightAlign: false },
          );
          return <input {...inputProps} placeholder="$ 0.00" />;
        }}
      </form.Field>
    </form>
  );
}
```

--------------------------------

### Credit Card Input with useMaskInputAntd

Source: https://use-mask-input.eduardoborges.dev/antd

Use this snippet to create a credit card input with a mask. The mask '9999 9999 9999 9999' formats the input as a 16-digit credit card number. The placeholder shows an example value.

```jsx
import { Input } from 'antd';  

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

  

function CreditCardInput() {  
  const maskRef = useMaskInputAntd({  
    mask: '9999 9999 9999 9999',  
  });  
  return <Input ref={maskRef} placeholder="0000 0000 0000 0000" />;  
}  

```

--------------------------------

### useTanStackFormMask with custom currency options

Source: https://use-mask-input.eduardoborges.dev/tanstack-form

Using useTanStackFormMask with custom mask options. The example applies a currency mask with prefix '$ ', group separator ',', 2 digits, and rightAlign disabled.

```tsx
const inputProps = maskField(  
  'currency',  
  {  
    name: field.name,  
    value: field.state.value,  
    onBlur: field.handleBlur,  
    onChange: (event) => field.handleChange(event.target.value),  
  },  
  {  
    prefix: '$ ',  
    groupSeparator: ',',  
    digits: 2,  
    rightAlign: false,  
  },  
);  


```

--------------------------------

### Phone Number Input with useMaskInputAntd

Source: https://use-mask-input.eduardoborges.dev/antd

Use this snippet to create a phone number input with a mask. The mask '(999) 999-9999' formats the input as a US phone number. The placeholder shows an example value.

```jsx
import { Input } from 'antd';  

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

  

function PhoneInput() {  
  const maskRef = useMaskInputAntd({ mask: '(999) 999-9999' });  
  return <Input ref={maskRef} placeholder="(555) 123-4567" />;  
}  

```

--------------------------------

### withMask currency input with options

Source: https://use-mask-input.eduardoborges.dev/api-reference

Example of using `withMask` with the `'currency'` alias and custom options. The options set a `R$ ` prefix, comma radix point, dot group separator, two digits, and right alignment disabled. The component is wrapped with `React.memo` to maintain ref callback stability.

```jsx
import { memo } from 'react';  
import { withMask } from 'use-mask-input';  

const CurrencyInput = memo(() => {  
  return (  
    <input  
      ref={withMask('currency', {  
        prefix: 'R$ ',  
        radixPoint: ',',  
        groupSeparator: '.',  
        digits: 2,  
        rightAlign: false,  
      })}  
    />  
  );  
});  

```

--------------------------------

### Static Mask examples: useMaskInput with fixed patterns

Source: https://use-mask-input.eduardoborges.dev/llms.txt

Fixed patterns that don't change during input. Each position is either a pattern character (9, a, A, *, #) or a literal. A forces uppercase letters; a accepts any case. Literal characters are always shown at the corresponding position.

```TSX
// Phone
useMaskInput({ mask: '(99) 99999-9999' })

// Date
useMaskInput({ mask: '99/99/9999' })

// Credit card
useMaskInput({ mask: '9999 9999 9999 9999' })

// Brazilian ZIP code
useMaskInput({ mask: '99999-999' })

// License plate (old Brazilian format: letters + digits)
useMaskInput({ mask: 'AAA-9999' })

// Custom ID
useMaskInput({ mask: 'ID: 999-AAA' })
```

--------------------------------

### useMaskInput composable usage

Source: https://use-mask-input.eduardoborges.dev/vue

Use this composable to get a ref callback and a function for the raw unmasked value. Bind maskRef to an input via :ref and call unmaskedValue() in event handlers. The example logs '12345678901' on submit.

```Vue
<script setup>  

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

  

const { maskRef, unmaskedValue } = useMaskInput('cpf');  

  

function submit() {  

  console.log(unmaskedValue()); // '12345678901'  

}  

</script>  

  

<template>  

  <input :ref="maskRef" />  

  <button @click="submit">Submit</button>  

</template>  
```

--------------------------------

### Payment card number pattern example

Source: https://use-mask-input.eduardoborges.dev/llms-full.txt

Example of using a custom mask pattern for card numbers (9999 9999 9999 9999).

```tsx
function CardNumberInput() {
  const cardMask = useMaskInput({
    mask: '9999 9999 9999 9999',
  });

  return (
    <input
      type="text"
      ref={cardMask}
      placeholder="0000 0000 0000 0000"
    />
  );
}
```

--------------------------------

### Global registration with Options API

Source: https://use-mask-input.eduardoborges.dev/api-reference

For the Options API or global registration, use createApp and the directive method.

```javascript
import { createApp } from 'vue';  

import { vMaskInput } from 'use-mask-input/vue';  

  

createApp(App).directive('mask-input', vMaskInput);  
```

--------------------------------

### JIT Masking with useMaskInput

Source: https://use-mask-input.eduardoborges.dev/llms-full.txt

Uses JIT (Just-In-Time) masking with the {4|1} syntax and the jitMasking option enabled. Shows the mask only as the user types.

```tsx
function JitMaskInput() {
  const mask = useMaskInput({
    mask: '9{4|1}',
    options: {
      jitMasking: true,
    },
  });

  return (
    <input
      type="text"
      ref={mask}
      placeholder="0"
    />
  );
}
```

--------------------------------

### Validate discovery endpoints with curl

Source: https://use-mask-input.eduardoborges.dev/discoverability

Run these curl commands to verify the Link headers, robots.txt, and API catalog. The first command checks the homepage Link headers, the second fetches robots.txt, and the third requests the API catalog with the required Accept header.

```bash
curl -sI https://use-mask-input.eduardoborges.dev/ | grep -i '^link:'  

curl -s https://use-mask-input.eduardoborges.dev/robots.txt | head  

curl -sH 'Accept: application/linkset+json' https://use-mask-input.eduardoborges.dev/.well-known/api-catalog  
```

--------------------------------

### withTanStackFormMask usage example

Source: https://use-mask-input.eduardoborges.dev/api-reference

Example usage of withTanStackFormMask inside a memoized React component. It applies a phone mask to the input props and spreads the result onto an <input> element.

```jsx
import { memo } from 'react';  

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

  

const InputField = memo(function InputField({  

  inputProps,  

}: {  

  inputProps: {  

    name: string;  

    value: string;  

    onBlur: () => void;  

    onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;  

  };  

}) {  

  const maskedProps = withTanStackFormMask(inputProps, '(99) 99999-9999');  

  return <input {...maskedProps} />;  

});  
```

--------------------------------

### URL Input with useMaskInput

Source: https://use-mask-input.eduardoborges.dev/tutorial-basics/alias-mask

Applies the 'url' mask with no additional options. The input is type="url" with placeholder "https://example.com".

```jsx
function UrlInput() {  

  const urlMask = useMaskInput({  

    mask: 'url',  

  });  

  

  return (  

    <input  

      type="url"  

      ref={urlMask}  

      placeholder="https://example.com"  

    />  

  );  

}  
```

--------------------------------

### Brazilian bank account alias placeholder example with (000) 12345678-9

Source: https://use-mask-input.eduardoborges.dev/llms-full.txt

Example of using the br-bank-account alias with a customized placeholder '(000) 12345678-9' to illustrate a format like Caixa Econômica.

```tsx
function BankAccountInput() {
  const bankAccountMask = useMaskInput({
    mask: 'br-bank-account',
  });

  return (
    <input
      type="text"
      ref={bankAccountMask}
      placeholder="(000) 12345678-9"
    />
  );
}
```

--------------------------------

### useHookFormMaskAntd usage example

Source: https://use-mask-input.eduardoborges.dev/api-reference

Example usage of useHookFormMaskAntd in a React Hook Form form with an Ant Design Input. It registers a masked phone field and submits the form data to console.log.

```jsx
import { Input } from 'antd';  

import { useForm } from 'react-hook-form';  

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

  

function MyForm() {  

  const { register, handleSubmit } = useForm();  

  const registerWithMask = useHookFormMaskAntd(register);  

  

  return (  

    <form onSubmit={handleSubmit(console.log)}>  

      <Input  

        {...registerWithMask('phone', '(99) 99999-9999')}  

        placeholder="(00) 00000-0000"  

      />  

      <button type="submit">Submit</button>  

    </form>  

  );  

}  
```

--------------------------------

### useHookFormMask with React Hook Form example

Source: https://use-mask-input.eduardoborges.dev/api-reference

Example of using useHookFormMask with React Hook Form. It wraps the register function to apply a mask to a phone field while leaving other fields unmasked.

```jsx
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')}  
        placeholder="(00) 00000-0000"  
      />  

      {/* Fields without masks still use the regular register */}  
      <input {...register('email')} placeholder="email@example.com" />  

      <button type="submit">Submit</button>  
    </form>  
  );  
}  
```

--------------------------------

### Options

Source: https://use-mask-input.eduardoborges.dev/api-reference

Configuration options for Inputmask, including placeholder, unmasking, prefixes, suffixes, and numeric formatting.

```APIDOC
## Options

### Description
Configuration options for Inputmask, including placeholder, unmasking, prefixes, suffixes, and numeric formatting.

### Options Table
| Option | Type | Description |
| --- | --- | --- |
| `placeholder` | `string` | Placeholder character for unfilled positions (default `_`). |
| `autoUnmask` | `boolean` | If `true`, `value` returns unmasked data. |
| `prefix` | `string` | Text prepended to the input. |
| `suffix` | `string` | Text appended to the input. |
| `radixPoint` | `string` | Decimal separator character. |
| `groupSeparator` | `string` | Thousands separator character. |
| `digits` | `number` | Number of decimal digits. |
| `rightAlign` | `boolean` | Align input text to the right. |
| `inputFormat` | `string` | Date input format (for `datetime` alias). |
| `outputFormat` | `string` | Date output format (for `datetime` alias). |
| `min` | `number` | Minimum allowed value (numeric aliases). |
| `max` | `number` | Maximum allowed value (numeric aliases). |
```

--------------------------------

### JIT Masking with useMaskInput (React)

Source: https://use-mask-input.eduardoborges.dev/tutorial-basics/dynamic-mask

Uses the mask '9{4|1}' with jitMasking option to show the mask only as the user types.

```jsx
function JitMaskInput() {  
  const mask = useMaskInput({  
    mask: '9{4|1}',  
    options: {  
      jitMasking: true,  
    },  
  });  

  

  return (  
    <input  
      type="text"  
      ref={mask}  
      placeholder="0"  
    />  
  );  
}  

```

--------------------------------

### withHookFormMask phone input example

Source: https://use-mask-input.eduardoborges.dev/api-reference

Example of using `withHookFormMask` to apply a phone mask to an already-registered field. The component is wrapped with `React.memo` to keep the ref callback stable. Use this only when you need to apply the mask to a field registered elsewhere; otherwise prefer `useHookFormMask` for built-in memoization.

```jsx
import { memo } from 'react';  
import { useForm } from 'react-hook-form';  
import { withHookFormMask } from 'use-mask-input';  

const MyForm = memo(() => {  
  const { register, handleSubmit } = useForm();  

  return (  
    <form onSubmit={handleSubmit(console.log)}>  
      <input  
        {...withHookFormMask(register('phone'), '(99) 99999-9999')}  
        placeholder="(00) 00000-0000"  
      />  
      <button type="submit">Submit</button>  
    </form>  
  );  
});  

```

--------------------------------

### Datetime alias with input and output formats

Source: https://use-mask-input.eduardoborges.dev/llms-full.txt

Demonstrates using the datetime alias with both inputFormat and outputFormat. The unmasked value is read via ref.unmaskedValue(); the visible input stays masked so e.target.value is not the unmasked output.

```tsx
function DateTimeInput() {
  const dateTimeMask = useMaskInput({
    mask: 'datetime',
    options: {
      inputFormat: 'dd/mm/yyyy HH:MM',
      outputFormat: 'yyyy-mm-dd HH:MM',
    },
  });

  return (
    <input
      type="text"
      ref={dateTimeMask}
      placeholder="DD/MM/YYYY HH:MM"
    />
  );
}
```

--------------------------------

### Basic Preprocessing Mask Syntax (React and Vue)

Source: https://use-mask-input.eduardoborges.dev/tutorial-basics/preprocessing-mask

Shows the basic syntax for a preprocessing mask in React and Vue. In React, pass a function to useMaskInput that returns an array of mask patterns. In Vue, define the mask function inside the binding object and keep it stable across renders to avoid re-applying the mask.

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

function DynamicInput() {  
  const mask = useMaskInput({  
    mask: function() {  
      // Your logic here  
      return ['[1-]AAA-999', '[1-]999-AAA'];  
    },  
  });  

  return (  
    <input  
      type="text"  
      ref={mask}  
      placeholder="AAA-000"  
    />  
  );  
}  

```

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

const binding = {  
  mask: () => ['[1-]AAA-999', '[1-]999-AAA'],  
};  
</script>  

<template>  
  <input v-mask-input="binding" placeholder="AAA-000" />  
</template>  

```

--------------------------------

### Alternator mask with pipe syntax (React and Vue)

Source: https://use-mask-input.eduardoborges.dev/tutorial-basics/alternator-mask

Use the pipe character `|` to separate alternator options in the mask string. The React example uses `useMaskInput` with `mask: '9999-9999|99999-9999'`; the Vue example uses the `v-mask-input` directive with an array of masks. Both accept 8-digit (`1234-5678`) and 9-digit (`12345-6789`) phone numbers.

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

function PhoneInput() {  
  const phoneMask = useMaskInput({  
    mask: '9999-9999|99999-9999',  
  });  

  return (  
    <input  
      type="tel"  
      ref={phoneMask}  
      placeholder="0000-0000"  
    />  
  );  
}  

```

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

<template>  
  <input v-mask-input="['9999-9999', '99999-9999']" />  
</template>  

```

--------------------------------

### Custom placeholder for br-bank-agency mask

Source: https://use-mask-input.eduardoborges.dev/llms-full.txt

Example of the 'br-bank-agency' mask with a customized placeholder '(0000)' to indicate the expected format.

```tsx
function BankAgencyInput() {
  const bankAgencyMask = useMaskInput({
    mask: 'br-bank-agency',
  });

  return (
    <input
      type="text"
      ref={bankAgencyMask}
      placeholder="(0000)"
    />
  );
}
```

--------------------------------

### Percentage Input with useMaskInput

Source: https://use-mask-input.eduardoborges.dev/tutorial-basics/alias-mask

Applies the 'percentage' mask with options for 2 digits and a suffix of ' %'. The input is type="text" with placeholder "0,00 %".

```jsx
function PercentageInput() {  

  const percentageMask = useMaskInput({  

    mask: 'percentage',  

    options: {  

      digits: 2,  

      suffix: ' %',  

    },  

  });  

  

  return (  

    <input  

      type="text"  

      ref={percentageMask}  

      placeholder="0,00 %"  

    />  

  );  

}  
```

--------------------------------

### useMaskInput with currency alias and options

Source: https://use-mask-input.eduardoborges.dev/llms.txt

Usage of useMaskInput with the 'currency' alias and custom options. Configure prefix, group separator, radix point, digits, and alignment. The placeholder shows the expected currency format.

```tsx
function CurrencyInput() {
  const ref = useMaskInput({
    mask: 'currency',
    options: {
      prefix: 'R$ ',
      groupSeparator: '.',
      radixPoint: ',',
      digits: 2,
      rightAlign: false,
    },
  });
  return <input ref={ref} placeholder="R$ 0,00" />;
}
```

--------------------------------

### Email alias example

Source: https://use-mask-input.eduardoborges.dev/llms-full.txt

Shows using the email alias to mask an email input. The input type is set to email.

```tsx
function EmailInput() {
  const emailMask = useMaskInput({
    mask: 'email',
  });

  return (
    <input
      type="email"
      ref={emailMask}
      placeholder="user@example.com"
    />
  );
}
```

--------------------------------

### useMaskInput with datetime alias and formats

Source: https://use-mask-input.eduardoborges.dev/llms.txt

Usage of useMaskInput with the 'datetime' alias. Specify input and output formats. The placeholder shows the expected input format.

```tsx
function DateInput() {
  const ref = useMaskInput({
    mask: 'datetime',
    options: {
      inputFormat: 'dd/mm/yyyy',
      outputFormat: 'yyyy-mm-dd',
    },
  });
  return <input ref={ref} placeholder="DD/MM/YYYY" />;
}
```

--------------------------------

### Company tax ID pattern example

Source: https://use-mask-input.eduardoborges.dev/llms-full.txt

Custom pattern for Brazilian CNPJ (99.999.999/9999-99) when you need a format not built-in like cnpj alias.

```tsx
function CompanyIdInput() {
  const idMask = useMaskInput({
    mask: '99.999.999/9999-99',
  });

  return (
    <input
      type="text"
      ref={idMask}
      placeholder="00.000.000/0000-00"
    />
  );
}
```

--------------------------------

### withMask

Source: https://use-mask-input.eduardoborges.dev/api-reference

Creates a ref callback that applies an input mask. This is the simplest API when you just need a masked ref and don't use React Hook Form.

```APIDOC
## withMask

### Description
Creates a ref callback that applies an input mask. This is the simplest API when you just need a masked ref and don't use React Hook Form.

### Function Signature
```typescript
function withMask(
  mask: Mask,
  options?: Options
): (input: HTMLElement | null) => void
```

### Parameters
- **mask** (`Mask`) - Required - The mask pattern, alias, or array of patterns.
- **options** (`Options`) - Optional - Inputmask configuration options.

### Returns
A ref callback function to pass to an element's `ref` prop. The returned callback also exposes `unmaskedValue()`.

### Caching Behavior
When called without `options`, the callback is cached by mask key so the same function identity is returned for the same mask. When `options` is provided, a new callback is created each call, so `memo` is needed.

### Example
```jsx
import { memo } from 'react';
import { withMask } from 'use-mask-input';

const PhoneInput = memo(() => {
  return (
    <input
      ref={withMask('(99) 99999-9999')}
      placeholder="(00) 00000-0000"
    />
  );
});
```

### Example with Options
```jsx
import { memo } from 'react';
import { withMask } from 'use-mask-input';

const CurrencyInput = memo(() => {
  return (
    <input
      ref={withMask('currency', {
        prefix: 'R$ ',
        radixPoint: ',',
        groupSeparator: '.',
        digits: 2,
        rightAlign: false,
      })}
    />
  );
});
```
```

--------------------------------

### Basic Preprocessing Mask Syntax

Source: https://use-mask-input.eduardoborges.dev/llms-full.txt

Basic syntax for a preprocessing mask: pass a function to useMaskInput that returns a valid mask definition. The function can return a single mask or an array of masks.

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

function DynamicInput() {
  const mask = useMaskInput({
    mask: function() {
      // Your logic here
      return ['[1-]AAA-999', '[1-]999-AAA'];
    },
  });

  return (
    <input
      type="text"
      ref={mask}
      placeholder="AAA-000"
    />
  );
}
```
Tokens:
Raw