Validation
Errors come back as keys, not messages. Add your own rules and use them with a resolver.
Error keys
Empty values are not validated; requiring a value is the job of rules.required or your schema. The error arrives as a key in errors.field.message, so translations stay with you.
| Key | When |
|---|---|
<name>.incomplete | The pattern is not full (phone, card, tckn…) |
<name>.invalid | A checksum failed (Luhn, TCKN, VKN, a date that doesn't exist) |
iban.country | The IBAN does not start with two A–Z letters (2.4+) |
iban.length | Not the length of its country: 26 characters for TR, 22 for DE (2.4+) |
iban.checksum | The mod-97 check failed (2.4+) |
<name>.min, <name>.max | Number, currency or date limit; a past month on expiry |
date.minAge | Age limit |
date.beforeFrom | Before the linked start date |
<name> is the preset name; mask for a custom pattern, or the name you gave definePreset.
From 2.4 the iban preset names the reason with its own keys. iban.invalid stays as the fallback: it comes for a character an IBAN cannot have (a letter outside A–Z) and for your own validate that returns false. If your messages map only has iban.invalid, add the three new keys or fall back to it for any other iban.* key. { preset: "iban", country: "TR" } fixes the country and the length, so of the new keys it only returns iban.checksum. A country code the registry does not list is not rejected; it is checked with 15–34 characters and mod-97.
const messages: Record<string, string> = {
"iban.incomplete": "The IBAN is incomplete",
"iban.country": "An IBAN starts with a country code",
"iban.length": "The IBAN is not the right length for its country",
"iban.checksum": "The IBAN is wrong, check its digits",
"iban.invalid": "Invalid IBAN",
}
const text = (key: string) => messages[key] ?? (key.startsWith("iban.") ? messages["iban.invalid"] : key)Form value: -
Display: -
Custom validation
validate runs after the built-in checks. On a preset, both apply.
useViraMask(form, {
// true: valid · false: "<name>.invalid" · a string: your own key
tckn: { preset: "tckn", validate: (value) => value !== "11111111110" || "tckn.blocked" },
// React Hook Form rules work too
phone: { preset: "phone", country: "TR", rules: { required: "required", validate: { mobile: (v) => v.startsWith("5") || "phone.mobile" } } },
})Zod, Valibot and resolvers
React Hook Form skips register validation when a resolver is set. Wrap the resolver with maskResolver to get schema and mask errors together. Without it, you get a console warning in development.
import { zodResolver } from "@hookform/resolvers/zod"
import { maskResolver, useViraMask } from "@virastack/mask"
const masks = { tckn: "tckn", phone: { preset: "phone", country: "TR" } } as const
const schema = z.object({ tckn: z.string().min(1, "required"), phone: z.string() })
const form = useForm({ resolver: maskResolver(masks, zodResolver(schema)) })
// or pass a Standard Schema directly (no @hookform/resolvers needed)
const form2 = useForm({ resolver: maskResolver(masks, schema) })
const { tckn, phone } = useViraMask(form, masks)To use the same schema on the server, see the server page.