Component reference
MaskedInput
Guide entry of formatted delivery information.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Delivery contact
MaskedInput is controlled here and writes into the same form state as the regular inputs.
Width adapts to the available space
"use client";
import { useState } from "react";
import {
useForm,
Card,
CardHeader,
CardTitle,
CardDescription,
CardContent,
Form,
Input,
FormError,
MaskedInput,
FormSubmit
} from "@pimolu/react";
interface DeliveryValues {
recipient: string;
phone: string;
postalCode: string;
}
function DeliveryForm() {
const [confirmed, setConfirmed] = useState(false);
const form = useForm<DeliveryValues>({
defaultValues: {
recipient: "",
phone: "",
postalCode: "",
},
validate: (values) => {
const errors: Partial<Record<keyof DeliveryValues, string>> = {};
if(!values.recipient.trim()) {
errors.recipient = "Who should we ask for?";
}
if(values.phone.replace(/\D/g, "").length < 10) {
errors.phone = "Enter the full 10-digit number.";
}
if(values.postalCode.replace(/[^a-z0-9]/gi, "").length < 6) {
errors.postalCode = "Enter a complete postal code.";
}
return errors;
},
onSubmit: async () => {
await new Promise((resolve) => setTimeout(resolve, 600));
setConfirmed(true);
},
});
return (
<Card>
<CardHeader>
<CardTitle>Delivery contact</CardTitle>
<CardDescription>
MaskedInput is controlled here and writes into the same form
state as the regular inputs.
</CardDescription>
</CardHeader>
<CardContent>
<Form form={form} className="grid gap-5 min-w-0">
<Input label="Recipient" required fullWidth {...form.register("recipient")} />
<FormError name="recipient" />
<MaskedInput
label="Phone"
mask="(999) 999-9999"
required
fullWidth
value={form.values.phone}
onValueChange={(value) => form.setValue(
"phone",
value
)}
invalid={Boolean(form.errors.phone)}
aria-describedby={form.errors.phone
? `${form.formId}-phone-error`
: undefined}
helperText="We only call on delivery day."
/>
<FormError name="phone" />
<MaskedInput
label="Postal code"
mask="a9a 9a9"
required
fullWidth
value={form.values.postalCode}
onValueChange={(value) => form.setValue(
"postalCode",
value
)}
invalid={Boolean(form.errors.postalCode)}
aria-describedby={form.errors.postalCode
? `${form.formId}-postalCode-error`
: undefined}
/>
<FormError name="postalCode" />
<FormSubmit>Confirm delivery</FormSubmit>
{
confirmed && (<p role="status">
Delivery contact saved for {form.values.recipient}.
</p>)
}
</Form>
</CardContent>
</Card>
);
}
export function DemoExample() {
return (<DeliveryForm />);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Patterns
The same engine covers phone numbers, dates, postal codes and mixed alphanumeric references.
Sizes
sm, md and lg match the other text controls.
Controlled value and paste
onValueChange receives the formatted string. Pasting a formatted value is normalized and the caret lands after the last accepted character.
Usage
Separate display formatting from the value your backend expects and validate the complete input.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluMaskedInputProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
maskRequired | string | — | Mask pattern. `9` accepts a digit, `a` a letter, `*` a letter or a digit. Every other character is a literal, `\` escapes a token. |
value | string | undefined | — | Controlled **formatted** value. |
defaultValue | string | undefined | — | Initial value, formatted with the mask. |
onValueChange | ((value: string) => void) | undefined | — | Called with the next formatted value. |
label | ReactNode | — | Visible label, associated with the text input. |
helperText | ReactNode | — | Supporting text below the field. |
errorMessage | ReactNode | — | Error text, replacing the helper text. |
invalid | boolean | undefined | false | Invalid state without an error message. |
size | PimoluMaskedInputSize | undefined | "md" | Visual size. Defaults to "md". |
fullWidth | boolean | undefined | false | Stretch to the parent width. |
containerClassName | string | undefined | — | Class applied to the outer field. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
children | ReactNode | — | Standard React/HTML attribute. |
onClick | MouseEventHandler<HTMLInputElement> | undefined | — | Standard React/HTML attribute. |
disabled | boolean | undefined | false | Standard React/HTML attribute. |
name | string | undefined | — | Standard React/HTML attribute. |
required | boolean | undefined | false | Standard React/HTML attribute. |
maskRequiredstringNo default extracted.
Mask pattern. `9` accepts a digit, `a` a letter, `*` a letter or a digit. Every other character is a literal, `\` escapes a token.
valuestring | undefinedNo default extracted.
Controlled **formatted** value.
defaultValuestring | undefinedNo default extracted.
Initial value, formatted with the mask.
onValueChange((value: string) => void) | undefinedNo default extracted.
Called with the next formatted value.
labelReactNodeNo default extracted.
Visible label, associated with the text input.
helperTextReactNodeNo default extracted.
Supporting text below the field.
errorMessageReactNodeNo default extracted.
Error text, replacing the helper text.
invalidboolean | undefinedDefault: false
Invalid state without an error message.
sizePimoluMaskedInputSize | undefinedDefault: "md"
Visual size. Defaults to "md".
fullWidthboolean | undefinedDefault: false
Stretch to the parent width.
containerClassNamestring | undefinedNo default extracted.
Class applied to the outer field.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
childrenReactNodeNo default extracted.
Standard React/HTML attribute.
onClickMouseEventHandler<HTMLInputElement> | undefinedNo default extracted.
Standard React/HTML attribute.
disabledboolean | undefinedDefault: false
Standard React/HTML attribute.
namestring | undefinedNo default extracted.
Standard React/HTML attribute.
requiredboolean | undefinedDefault: false
Standard React/HTML attribute.
Accessibility
- Explain the expected format outside the placeholder and allow paste and correction.