MaskedField

MaskedField is a client component that formats input as the user types, for amounts, phone numbers, dates and similar values. It renders react-number-format's NumericFormat or PatternFormat with Reactberry's Field (as="input") as the input. Masks come from a named preset or from react-number-format props.

Import#

import { MaskedField, maskPresets } from "@reactberry/system/blocks";
import type { MaskedFieldProps, MaskPresetType } from "@reactberry/system/blocks";

Usage#

import { useState } from "react";
import { MaskedField } from "@reactberry/system/blocks";
import { Box, Text } from "@reactberry/system/elements";

export default function BudgetInput() {
  const [amount, setAmount] = useState<number | undefined>();

  return (
    <Box display="flex" flexDirection="column" gap="xs">
      <Text as="label" htmlFor="budget" fontWeight={600}>
        Budget
      </Text>
      <MaskedField
        id="budget"
        preset="currency"
        variant="default"
        value={amount}
        onValueChange={(values) => setAmount(values.floatValue)}
        placeholder="$0.00"
      />
    </Box>
  );
}

Examples#

Presets#

Pass preset to apply a ready-made mask. Pattern presets such as phone, date and creditCard use PatternFormat; percentage uses NumericFormat and only allows values from 0 to 100.

Custom formats#

Props are merged after the preset, so they override its options. Use maskType="pattern" with format for a mask that has no preset.

API#

MaskedField#

All other NumericFormatProps or PatternFormatProps from react-number-format (except customInput and getInputRef) are accepted, including value, onValueChange, onChange, format, mask, prefix, suffix, decimalScale, and isAllowed. They are merged after the preset, so they override preset options. Props that react-number-format does not use are passed through to Field.

maskPresets#

An object of preset configurations. MaskPresetType is keyof typeof maskPresets.

Numeric presets (NumericFormat):

• currency — prefix $, thousand separator ,, decimal separator ., 2 fixed decimals, no negatives.
• percentage — suffix %, up to 2 decimals, no negatives, values limited to 0–100.
• decimal — up to 4 decimals, negatives allowed, thousand separator ,.
• integer — no decimals, no negatives, thousand separator ,.
• year — no decimals, no negatives, values limited to 1900–2100.

Pattern presets (PatternFormat, mask character _, allowEmptyFormatting: false):

• phone — (###) ###-####
• date — ##/##/####, placeholder MM/DD/YYYY
• zip — #####
• zipPlus4 — #####-####
• ssn — ###-##-####
• ein — ##-#######
• creditCard — #### #### #### ####
• time12 — ##:## ##, placeholder HH:MM AM
• time24 — ##:##, placeholder HH:MM

Accessibility#

• MaskedField renders a native input with no label. Pass an id and pair it with a label (htmlFor), or pass aria-label.

Notes#

• Any type prop is removed before rendering (it is stripped together with the preset's internal type key), so the input always uses Field's default type="text".
• MaskedField does not forward refs, and getInputRef is omitted from its props.
• Pattern presets only restrict input to digits; date, time12, and time24 do not validate ranges, and time12 accepts digits only in the AM/PM slot.
• maskType="pattern" without a preset requires a format prop.
• formatWithPreset exists in the module source but is not exported from @reactberry/system/blocks.
• The preset placeholder values (date, time12, time24) are passed to the input and can be overridden.