Masked Input React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Masked Input is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import MaskedInput from @/components/ui/masked-input.

import { useState } from "react"
import { MaskedInput, type MaskedInputDetails } from "@/components/ui/masked-input"

export function CardForm() {
  const [card, setCard] = useState("")
  const [details, setDetails] = useState<MaskedInputDetails | null>(null)
  const [touched, setTouched] = useState(false)

  return (
    <form className="flex flex-col gap-4">
      <MaskedInput
        preset="card-number"
        name="card"
        label="Card number"
        placeholder="1234 5678 9012 3456"
        value={card}
        onValueChange={(raw, info) => {
          setCard(raw)
          setDetails(info)
        }}
        onBlur={() => setTouched(true)}
        error={touched && details?.valid === false ? "The card number is not valid." : undefined}
        required
      />
      <div className="grid grid-cols-2 gap-3">
        <MaskedInput preset="card-expiry" name="expiry" label="Expiry" placeholder="MM/YY" showMask="focus" maskPlaceholder="MM/YY" />
        <MaskedInput preset="card-cvc" name="cvc" label="CVC" placeholder="123" enterKeyHint="done" />
      </div>
      <MaskedInput
        label="License plate (Romania)"
        mask={(raw) => (/^B\d/i.test(raw) ? "A 999 AAA" : "AA 99 AAA")}
        placeholder="CJ 12 ABC"
        autoCapitalize="characters"
      />
    </form>
  )
}

Props

• presetdefault "none"
  "none" | "card-number" | "card-expiry" | "card-cvc" | "iban" | "cnp" | "postal-code"

  A ready mask with its validator, inputMode and autoComplete. card-number: 16 digits in groups of 4 (up to 19, Amex 4-6-5), Luhn, brand chip. card-expiry: 99/99, smart month, not in the past. card-cvc: 3 digits. iban: country length, uppercase, mod 97. cnp: 13 digits, checksum, birth date, county 01-52. postal-code: 6 digits. The playground shows the card form while none has no mask.

• maskdefault ""
  string | ((raw: string) => string)

  The pattern: 9 a digit, a a letter, A a letter shown uppercase, * a letter or digit, \ escapes; anything else is a literal ("AA 99 AAA"). A function picks the pattern from the raw value typed so far (Amex cards, Bucharest plates). Overrides the preset's mask; the preset's validator stays.

• showMaskdefault "never"
  "never" | "focus" | "always"

  The rest of the mask after the caret as a faint ghost (text-muted-foreground/60), aligned with the typed text. focus shows it while the field is focused; always keeps it visible and replaces the placeholder. A resting floating label hides it.

• maskPlaceholderdefault ""
  string

  The ghost text for the whole mask, character by character ("mm/dd/yyyy" for 99/99/9999). Empty shows placeholderChar in each token.

• placeholderChardefault "_"
  string

  The ghost character for each token when there is no maskPlaceholder.

• showValiditydefault true
  boolean

  A trailing CircleCheck (success) or CircleAlert (danger) that pops in once the value is complete, with a visually hidden Valid / Invalid. Needs a validator (the preset's or validate).

• showBranddefault true
  boolean

  card-number: the leading card icon and the trailing brand chip read from the first digits.

• submitMaskeddefault false
  boolean

  The hidden form input (rendered when name is set) sends the masked text (4111 1111 …) instead of the raw digits. The readout under the demo shows what the form gets.

• labeldefault ""
  ReactNode

  Renders the field anatomy around the box, linked with htmlFor. Leave it empty for a bare field (then pass aria-label).

• descriptiondefault ""
  ReactNode

  Helper text under the box, linked with aria-describedby; a good place for the format ("Format: LL/AA").

• errordefault ""
  ReactNode

  Replaces the description with the animated error and marks the field invalid. Say why the value failed (the demo does).

• requireddefault false
  boolean

  The red mark after the label and the native required attribute.

• invaliddefault false
  boolean

  The invalid look and aria-invalid without a message. A complete value that fails validation sets it by itself after the first blur.

• disableddefault false
  boolean

  Dims the field and blocks input; the hidden form input is disabled too, so nothing is submitted. The demo fills in the test card.

• readOnlydefault false
  boolean

  The value stays visible and selectable but cannot change. The demo fills in the test card.

• placeholderdefault ""
  string

  Hint text while empty. Hidden while an always-visible ghost covers the field.

• defaultValuedefault ""
  string

  The starting raw value while uncontrolled, with or without literals ("4111111111111111").

• namedefault ""
  string

  Renders a hidden input with this name and the raw value (or the masked text with submitMasked), so native forms and FormData get the clean value.

• sizedefault "md"
  "sm" | "md" | "lg"

  Height 32 / 40 / 48px with 13 / 14 / 15px text (16px on phones so iOS never zooms); md grows to 44px on touch.

• variantdefault "soft"
  "soft" | "outline" | "underline" | "ghost"

  The Input's box look: a filled well, a bordered box, a bottom line or no fill until hover.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner shape, scaled with the size like the button's; full makes a pill. Ignored by underline.

• accentdefault ""
  string

  Any CSS color for the focus ring, the outline border on focus and the caret. Empty uses the ring token.

• floatingLabeldefault false
  boolean

  The label rests inside the box and floats up on focus or when filled; the ghost waits until it has floated.

• clearabledefault false
  boolean

  A clear button while there is a value; Escape clears from the keyboard.

• prefixdefault ""
  ReactNode

  Text before the input in the muted addon look, like "RO" or "+40", or an element rendered as is. A click on it lands in the input.

• clearLabeldefault "Clear"
  string

  The clear button's accessible name and title (with clearable).

• loadingdefault false
  boolean

  A small spinner at the end and aria-busy, e.g. while the server checks an IBAN. The field stays editable.

• loadingLabeldefault "Loading"
  string

  The spinner's visually hidden text.

• selectOnFocusdefault false
  boolean

  Selects the whole value when the field takes focus, by click, tap or Tab, so typing replaces it.

• enterKeyHintdefault "next"
  "enter" | "done" | "go" | "next" | "previous" | "search" | "send"

  The label of the phone keyboard's Enter key. next suits a field in a form; pass done on the last one.

• value
  string

  The raw value, controlled, without literals. A value longer than the mask shows cut but is not changed until the next edit.

• onValueChange
  (raw: string, details: { masked: string; complete: boolean; valid: boolean | null; brand?: CardBrand | null }) => void

  Fires on every edit with the raw value and the details: the masked text, whether every token is filled, the validator's verdict once complete (null before), and the card brand for card-number.

• validate
  (raw: string) => boolean

  Runs once the value is complete; replaces the preset's validator. Without one (and without a preset) valid stays null and no icon shows. The mask engine and the checks are exported too (see Parts), for server code, initial state and read-only displays.

• labels
  Partial<{ valid: string; invalid: string; brands: Partial<Record<CardBrand, string>> }>

  The visually hidden text of the validity icon ("Valid" / "Invalid") and the brand chip names.

• onChange
  (event: ChangeEvent<HTMLInputElement>) => void

  The native change event, untouched. Its target value is the masked text; read the raw value from onValueChange.

• leftIcon
  ReactNode

  A leading icon; card-number shows a card icon by default (with showBrand).

• suffix
  ReactNode

  Text or an element after the brand chip and the validity icon.

• rightIcon
  ReactNode

  A trailing icon after the brand chip and the validity icon; it crossfades with the spinner while loading.

• clearIcon
  ReactNode

  Replaces the clear button's icon (a 16px X by default).

• onClear
  () => void

  Called after the clear button or Escape emptied the field (with clearable). onValueChange fires too, with an empty raw value.

• fieldProps
  Partial<FieldProps>

  Anything else for the Field wrapper: optional and optionalLabel, labelAction, orientation, labelWidth, hideLabel, requiredIndicator.

• ref
  RefObject<HTMLInputElement | null> or (node) => void

  The native input. Every other Input prop and native prop lands on it: inputMode, autoComplete and autoCapitalize (defaults from the preset), onBlur, aria-describedby. With react-hook-form use Controller (value / onValueChange), not register, since the element holds the masked text.

• classNames
  Partial<Record<InputSlot | "ghost" | "brand" | "validity", string>>

  Extra classes for the Input's parts plus the ghost, the brand chip and the validity icon.

Parts

FAQ

More React input components