arkyn

v3.0.1-beta.72

MaskedInput

The MaskedInput component is a specialized version of input that automatically applies formatting masks as the user types. It's ideal for fields that require specific formats, such as CPF, CNPJ, phone number, zip code, credit card number, and others.

tsx

import { MaskedInput } from "@arkyn/components";

Basic usage

Basic usage of an input requires a name, mask and replacement property.

tsx

<MaskedInput
  name="phone"
  mask="(__) _____-____"
  replacement={{ _: /\d/ }} // Only accepts numbers
/>

Mask settings

The mask property defines the mask pattern using special characters to represent positions to be filled. The replacement property defines which characters are accepted in each position.

Simple replacement

Use a simple string to replace all marked positions.

tsx

<MaskedInput
  name="simple-replacement"
  label="Simple replacement"
  mask="___-___-___"
  replacement="_"
  placeholder="000-000-000"
/>

Replacement with regex

Use an object with regex to control exactly which characters are accepted.

tsx

<MaskedInput
  name="regex-replacement"
  label="Numbers only"
  mask="(__) _____-____"
  replacement={{ _: /\d/ }}
  placeholder="(00) 00000-0000"
  leftIcon={Phone}
/>

Showing the mask

Use showMask to display the mask pattern as a visual placeholder.

tsx

<MaskedInput
  name="cpf-show-mask"
  label="CPF (with visible mask)"
  mask="___.___.___-__"
  replacement="_"
  showMask
  leftIcon={User}
/>

Value separation

Use separate to separate the mask characters from the actual input value.

tsx

<MaskedInput
  name="cpf-separate"
  label="CPF (separate value)"
  mask="___.___.___-__"
  replacement="_"
  separate
  leftIcon={User}
/>

Sizes

The available sizes are md and lg, following the same pattern as the Input component.

tsx

<MaskedInput
  name="phone-md"
  mask="(__) _____-____"
  replacement={{ _: /\d/ }}
  placeholder="(00) 00000-0000"
  size="md"
/>
<MaskedInput
  name="phone-lg"
  mask="(__) _____-____"
  replacement={{ _: /\d/ }}
  placeholder="(00) 00000-0000"
  size="lg"
/>

Variants

The available variants are solid, outline, and underline, providing different visual styles.

tsx

<MaskedInput
  name="cpf-solid"
  mask="___.___.___-__"
  replacement="_"
  placeholder="000.000.000-00"
  variant="solid"
/>
<MaskedInput
  name="cpf-outline"
  mask="___.___.___-__"
  replacement="_"
  placeholder="000.000.000-00"
  variant="outline"
/>
<MaskedInput
  name="cpf-underline"
  mask="___.___.___-__"
  replacement="_"
  placeholder="000.000.000-00"
  variant="underline"
/>

Prefix and suffix

Use prefix and suffix to add text or fixed icons at the beginning or end of the input.

With prefix

tsx

<MaskedInput
  mask="____.___,__"
  replacement={{ _: /\d/ }}
  name="money"
  label="My wallet"
  placeholder="100.00"
  prefix="R$"
/>

With suffix

tsx

<MaskedInput
  mask="__/__/____"
  replacement={{ _: /\d/ }}
  name="day"
  label="Your birthday month"
  suffix={Calendar1}
/>

Input states

The component supports different states, such as disabled, read-only, and loading.

Disabled input

The disabled state prevents any user interaction with the field and prevents data from being submitted through a form.

tsx

<MaskedInput
  name="disabled-cpf"
  label="CPF disabled"
  mask="___.___.___-__"
  replacement="_"
  placeholder="000.000.000-00"
  disabled
  leftIcon={User}
/>

Read-only input

The read-only state allows the user to view the field value but cannot edit it. Unlike the disabled state, the value can be selected and copied, and field data can be submitted via a form.

tsx

<MaskedInput
  name="readonly-cpf"
  label="CPF read-only"
  mask="___.___.___-__"
  replacement="_"
  value="123.456.789-00"
  readOnly
  leftIcon={User}
/>

Loading state

The loading state displays a spinner and automatically disables input. The spinner appears on the left by default, or on the right if there is a rightIcon.

tsx

<MaskedInput
  name="loading-cpf"
  label="Validating CPF..."
  mask="___.___.___-__"
  replacement="_"
  placeholder="000.000.000-00"
  isLoading
  leftIcon={User}
/>

Validation and errors

The component integrates with form validation systems and can display error messages. If an error message is provided via the errorMessage property, it will take precedence over messages from the form provider.
Customizable Forms
For forms, it is recommended to use the FormProvider which offers native integration with all form tools.

tsx

<MaskedInput
  name="invalid-cpf"
  label="CPF"
  mask="___.___.___-__"
  replacement="_"
  placeholder="000.000.000-00"
  errorMessage="Invalid CPF"
  leftIcon={User}
  showAsterisk
/>

Properties

name - string (required) Field name for form manipulation
mask - string (required) Mask pattern (e.g., ".._-" for CPF)
replacement - string | Replacement (required) Replacement character or setting for mask positions
separate - boolean Whether to separate mask characters from the input value
showMask - boolean Whether to show the mask placeholder
label - string Label text to display above the input
errorMessage - string Error message to display below the input
isLoading - boolean (default: false) Controls the loading state with a spinner
size - "md" | "lg" (default: "md") Input size
variant - "solid" | "outline" | "underline" (default: "solid") Visual variant of the input
prefix - `string | LucideIcon Text or icon to display at the beginning of the input
suffix - string | LucideIcon Text or icon to display at the end of the input
showAsterisk - boolean Whether to display an asterisk in the label for required fields
leftIcon - LucideIcon Optional icon to display on the left side
rightIcon - LucideIcon Optional icon to display on the right side
Other Properties
All other standard HTML properties of <input> are also supported, except type, which is controlled by the mask.

Notes

  • The type type is not supported because it is controlled by the mask.
  • When isLoading is true, the input is automatically disabled.
  • The component is based on the @react-input/mask library for advanced mask functionality.
On this page