Reference

Validation patterns

The regex catalog of @samline/formatter: validation patterns for Mexican, US, European and web fields, each paired with an error message, plus check-digit validators.

The regex export is a readonly TypeScript object of validation patterns. Static entries pair a RegExp with an errorMessage; parametric-only helpers return that pair when called. Patterns check the shape of a value; the check-digit validators (isValidCurp, isValidIban, isValidCard…) also verify its check digit. Both tree-shake: an application that imports only format bundles neither.

import { regex } from '@samline/formatter'

if (!regex.email.pattern.test(input.value)) {
  input.setCustomValidity(regex.email.errorMessage)
}

Compatibility

The shape of the API has not changed: every entry still exposes .pattern and .errorMessage, every key from earlier releases still exists, and new keys and builders were only added. phone, creditCard, url, uuid, date, numeral and postalCode are also callable, with the static .pattern still attached:

regex.phone.pattern.test('5512345678') // static form
regex.phone({ length: 7 }).pattern.test('555-1234') // callable form

What a pattern accepts changed in 3.2.0, because the catalog was audited:

  • Stricter: phone and creditCard reject letters between digits; email rejects doubled, leading or trailing dots and characters outside the local-part set; rfc and curp check the date (and CURP the sex, state and consonants); cp rejects 00xxx; ipv4 rejects leading zeros; date rejects days that do not exist; semver rejects leading zeros in numeric pre-release parts; mention is limited to 30 characters; onlyLetters and onlyAlphanumeric reject blank and multi-line values.
  • Wider: creditCard accepts 12–19 digits; onlyLetters accepts letters in every script (Güemes, François); ipv6 accepts ::1 and other compressed forms; uuid accepts versions 1–8; hexColor accepts alpha (#RGBA, #RRGGBBAA); time24 accepts seconds; hashtag accepts accents; mention accepts leading digits and inner dots; semver accepts +build.

If your form depended on the old behavior, keep it with regex.custom(). The changelog lists every fix.

Usage modes

1. Static (object form)

Static entries expose .pattern and .errorMessage. The callable phone, creditCard, url, uuid, date, numeral and postalCode entries keep those properties too:

regex.phone.pattern.test('5512345678') // true
regex.url.errorMessage // 'Please enter a valid URL.'

2. Parametric (callable form)

Several entries are also functions that accept options to tune the pattern. They return the same { pattern, errorMessage } shape.

// Variable digit count
regex.digits(10).pattern.test('1234567890') // true
regex.digits(7).pattern.test('1234567') // true
regex.digits({ min: 3, max: 10 }).pattern.test('12345') // true

// Custom phone length
regex.phone({ length: 7 }).pattern.test('1234567') // true

// Credit card with custom range
regex.creditCard({ min: 13, max: 19 }).pattern.test('4111111111111') // true

// URL with protocol restriction
regex.url({ protocol: 'https' }).pattern.test('https://example.com') // true
regex.url({ protocol: 'https' }).pattern.test('ftp://example.com') // false

// Password with custom rules
regex.password({ min: 12, special: true }).pattern.test('MyP@ssw0rd!!') // true

3. Custom regex

When none of the built-in patterns fit your use case, define your own with regex.custom(). It accepts either positional or object form:

import { regex } from '@samline/formatter'

// Positional — pattern + error message
const code = regex.custom(/^[A-Z]{5}$/, 'Must be exactly 5 uppercase letters')
code.pattern.test('HELLO') // true
code.errorMessage // 'Must be exactly 5 uppercase letters'

// Object form
const zip = regex.custom({
  pattern: /^\d{4,6}$/,
  errorMessage: 'Must be 4–6 digits.',
})

// Default error message if omitted
const r = regex.custom(/^[a-z]+$/)
r.errorMessage // 'Invalid value.'

Pattern reference

Phone & Mexico

Key Signature Description Error message
phone phone() / phone({ length }) / phone.pattern Phone numbers (default: 10 digits). Spaces, hyphens, dots, parentheses and + may separate the digits. Please enter a valid 10-digit phone number.
rfc rfc.pattern Mexican RFC: 3 or 4 letters, a real YYMMDD date and a 3-character homoclave Please enter a valid RFC.
curp curp.pattern Mexican CURP: date, sex (H, M, X), state code (NE abroad), inner consonants and check digit Please enter a valid CURP.
cp cp.pattern Mexican postal code (01000–99999) Please enter a valid 5-digit postal code.
clabe clabe.pattern Mexican interbank account number (18 digits) Please enter a valid 18-digit CLABE.
ine ine.pattern Mexican voter ID key (clave de elector, INE): 6 letters, birth YYMMDD, state 01–32, sex and 3 digits Please enter a valid voter ID key (clave de elector).
ineCic ineCic.pattern CIC on the back of INE credentials from model D on (9 digits) Please enter a valid 9-digit CIC.
ineOcr ineOcr.pattern OCR on the back of older INE/IFE credentials (13 digits) Please enter a valid 13-digit OCR.
passportMx passportMx.pattern Mexican passport (a letter and 8 digits, G12345678) Please enter a valid passport number (e.g., G12345678).
nss nss.pattern Mexican social security number (IMSS, 11 digits) Please enter a valid 11-digit NSS.

United States

Key Signature Description Error message
ssn ssn.pattern Social Security number (123-45-6789); no 000, 666 or 9xx area, 00 group or 0000 serial, one separator style Please enter a valid SSN (e.g., 123-45-6789).
itin itin.pattern Individual Taxpayer Identification Number (912-70-1234): starts with 9, group 50–65, 70–88, 90–92 or 94–99 Please enter a valid ITIN (e.g., 912-70-1234).
passportUs passportUs.pattern US passport book (9 digits) or next-generation book or card (a letter and 8 digits) Please enter a valid US passport number.
ein ein.pattern Employer Identification Number (12-3456789) with an IRS-assigned prefix Please enter a valid EIN (e.g., 12-3456789).
routingNumber routingNumber.pattern ABA routing number (9 digits, Federal Reserve prefix); pair it with isValidRoutingNumber Please enter a valid 9-digit routing number.

US ZIP codes are postalCode (below); US phone numbers are phone (10 digits).

The US has no national ID card: the everyday equivalent of the Mexican INE is the state driver’s license or state ID, and each of the 50 states numbers it differently (for example A1234567 in California, 123 456 789 in New York, A123-456-78-901-0 in Florida). There is no built-in rule for it; write the states you serve with regex.custom():

const licenseCa = regex.custom(/^[A-Z]\d{7}$/i, 'Please enter a valid California license number.')

Europe & banking

Key Signature Description Error message
iban iban.pattern IBAN shape, with or without groups of 4; pair it with isValidIban for length and checksum Please enter a valid IBAN.
bic bic.pattern BIC / SWIFT code (8 or 11 characters) Please enter a valid BIC/SWIFT code.
vatEu vatEu.pattern EU VAT number with its country prefix, no spaces (DE123456789, NL123456789B01; Greece is EL, Northern Ireland XI) Please enter a valid EU VAT number (e.g., DE123456789).
dniEs dniEs.pattern Spanish DNI (12345678Z) or NIE (X1234567L); pair it with isValidDniEs Please enter a valid DNI or NIE.

Postal codes

Key Signature Description Error message
postalCode postalCode.pattern / postalCode({ country }) Static: US ZIP or ZIP+4. Called: the country’s format Please enter a valid postal code (e.g., 90210 or 90210-1234). / Please enter a valid postal code (GB).

country is an ISO code: US, MX, CA, GB, IE, DE, FR, ES, IT, PT, NL, BE, AT, CH, PL, SE, BR, AR, CO, CL, PE, JP, IN or AU (letters are case-insensitive, so sw1a 1aa passes for GB). Any other code throws a RangeError; write that country’s rule with regex.custom():

regex.postalCode({ country: 'CA' }).pattern.test('K1A 0B1') // true
const nz = regex.custom(/^\d{4}$/, 'Please enter a valid postcode.')

Numbers & Cards

Key Signature Description Error message
numeral numeral.pattern / numeral(options) Static: optional -, plain or comma-grouped digits, optional decimals (1,234.56, -42). Called: what the 'numeral' mask writes with the same options Please enter a valid number.
onlyNumbers onlyNumbers.pattern Digits only Please enter only numbers.
digits digits(n) / digits({ length }) / digits({ min, max }) Variable digit count Please enter N digits.
creditCard creditCard() / creditCard({ min, max }) / creditCard.pattern Card numbers (default: 12–19 digits, every ISO/IEC 7812 length), single spaces or hyphens allowed Please enter a valid card number (12-19 digits).
expirationDate expirationDate.pattern MM/YY or MM/YYYY Please enter a valid expiration date (MM/YY or MM/YYYY).
cardCvc cardCvc.pattern 3- or 4-digit CVC Please enter a valid CVC (3-4 digits).
latitude latitude.pattern -90 to 90, optional decimals Please enter a valid latitude (-90 to 90).
longitude longitude.pattern -180 to 180, optional decimals Please enter a valid longitude (-180 to 180).

numeral(options) reads delimiter, numeralDecimalMark, numeralThousandsGroupStyle, numeralDecimalScale, numeralPositiveOnly, prefix, tailPrefix and signBeforePrefix, so you can pass the options object of the field:

const options = { delimiter: '.', numeralDecimalMark: ',', prefix: '$ ' }
const { formatted } = format('1234,5', 'numeral', options) // '$ 1.234,5'
regex.numeral(options).pattern.test(formatted) // true

Text

Key Signature Description Error message
onlyLetters onlyLetters.pattern Letters in any script (Güemes, François) and spaces; at least one letter Please enter only letters.
onlyAlphanumeric onlyAlphanumeric.pattern Letters in any script, digits and spaces Please enter only letters and numbers.
personName personName.pattern Words joined by single spaces, apostrophes, hyphens or periods (O'Connor, Ma. Fernanda) Please enter a valid name.
slug slug.pattern URL slug (lowercase, hyphens) Please enter a valid slug (lowercase, hyphens, no spaces).
username username.pattern 3–20 chars, letters, numbers, _ or - Please enter a valid username (3-20 chars, letters, numbers, _ or -).

Dates & Times

Key Signature Description Error message
date date.pattern / date(options) Static: real calendar date YYYY-MM-DD (no 2026-02-31; 29 February only in leap years). Called: the 'date' mask order and delimiter Please enter a valid date (YYYY-MM-DD).
time time(options) The 'time' mask: timePattern, timeFormat and delimiter (default HH:MM:SS, 24-hour) Please enter a valid 24-hour time (HH:MM:SS).
time24 time24.pattern 24-hour time HH:MM with optional :SS Please enter a valid 24-hour time (HH:MM).
time12 time12.pattern 12-hour time with AM/PM (9:30 pm, 09:30:15 AM, 9:30 p. m.) Please enter a valid 12-hour time (e.g., 9:30 PM).
isoDateTime isoDateTime.pattern ISO 8601 / RFC 3339 date-time (2026-11-13T09:30, …:15.250Z, …-06:00) Please enter a valid date and time (YYYY-MM-DDTHH:MM).

regex.date (static) tests the ISO raw value. To test the visible formatted value, call it with the field’s options:

const options = { datePattern: ['d', 'm', 'Y'] }
regex.date(options).pattern.test('29/02/2028') // true
regex.date(options).pattern.test('31/04/2026') // false — April has 30 days

Web & Network

Key Signature Description Error message
email email.pattern Email address: dot-atom local part, real domain labels, 64/254 length limits Please enter a valid email address.
url url() / url({ protocol }) / url.pattern http, https or ftp URL with a domain, localhost or IP host Please enter a valid URL.
domain domain.pattern Host name without protocol (example.com, sub.dominio.mx) Please enter a valid domain (e.g., example.com).
ipv4 ipv4.pattern IPv4 addresses (no leading zeros) Please enter a valid IPv4 address.
ipv6 ipv6.pattern IPv6 in full, compressed (::1, 2001:db8::1) or IPv4-embedded form Please enter a valid IPv6 address.
macAddress macAddress.pattern MAC address with one separator (: or -) throughout, or Cisco form 001b.4411.3ab7 Please enter a valid MAC address (e.g., 00:1B:44:11:3A:B7).
hexColor hexColor.pattern Hex color codes (#RGB, #RGBA, #RRGGBB, #RRGGBBAA) Please enter a valid hex color code (e.g., #FFF or #FFFFFF).

Social

Key Signature Description Error message
hashtag hashtag.pattern Hashtags in any script (#méxico); not digits only Please enter a valid hashtag (e.g., #example).
mention mention.pattern Mentions up to 30 characters: letters, digits, _, inner dots Please enter a valid mention (e.g., @username).

Security

Key Signature Description Error message
password password() / password({ min, max, uppercase, lowercase, numbers, special }) Password strength (default: 8+ chars, mixed case, digits) Password must be N–M characters with at least one …
uuid uuid.pattern / uuid({ version }) RFC 9562 UUID, versions 1–8; version pins one Please enter a valid UUID.

Encoding & Versions

Key Signature Description Error message
base64 base64.pattern Padded Base64, not empty Please enter a valid Base64 encoded string.
base64url base64url.pattern URL-safe Base64 (JWT segments), padding optional, not empty Please enter a valid Base64URL encoded string.
semver semver.pattern Semantic Versioning 2.0.0 (1.2.3, 1.2.3-rc.1, 1.2.3+build.5) Please enter a valid semantic version (e.g., 1.2.3).

Utilities

Key Signature Description
custom custom(pattern, errorMessage?) / custom({ pattern, errorMessage }) User-defined regex. Returns { pattern, errorMessage }.

Check-digit validators

A pattern checks the shape of a value; a check digit also catches most typos (a wrong or swapped digit). These functions are named exports of @samline/formatter (and window.Formatter.checks in the browser build). Each one takes the value as typed — spaces and hyphens are ignored, letters are upper-cased — and returns a boolean; non-strings return false.

Function Checks
isLuhn(value) Luhn (mod 10) checksum, 2 or more digits
isValidCard(value) Card number: 12–19 digits and Luhn
isValidClabe(value) Mexican CLABE: 18 digits and the Banco de México 3-7-1 check digit
isValidNss(value) Mexican NSS (IMSS): 11 digits, Luhn check digit
isValidCurp(value) Mexican CURP: regex.curp and the RENAPO check digit
isValidRfc(value) Mexican RFC: regex.rfc and the SAT mod-11 check digit; accepts the generic XAXX010101000 and XEXX010101000
isValidIban(value) IBAN in any registered country: that country’s length and the ISO 13616 mod-97 checksum
isValidRoutingNumber(value) US ABA routing number: Federal Reserve prefix and the 3-7-1 checksum
isValidDniEs(value) Spanish DNI or NIE and its control letter

With @samline/forms, use the pattern for the message while typing and the check digit in validate:

import { isValidCurp, regex } from '@samline/formatter'

const schema = {
  curp: {
    required: true,
    pattern: { value: regex.curp.pattern, message: regex.curp.errorMessage },
    validate: ({ value }) => isValidCurp(value) || 'The CURP check digit does not match.',
  },
}

A valid check digit proves the value is well formed, not that it exists or belongs to the person: confirm it with the issuer (SAT, RENAPO, the bank) when that matters. The CURP algorithm itself cannot see a typo in the 9th character (the tens of the birth day) or a change of exactly 5 in some digits.

Type-safe access

import { regex, type RegexKey } from '@samline/formatter'

function validate(key: RegexKey, value: string): string | null {
  return regex[key].pattern.test(value) ? null : regex[key].errorMessage
}

validate('email', 'foo@bar.com') // null  (valid)
validate('email', 'not-an-email') // 'Please enter a valid email address.'

RegexKey covers entries that always expose a static .pattern and .errorMessage, including the static sides of phone, creditCard, and url. It excludes the parametric-only helpers digits, time, password, and custom.

Notes

  • These patterns check shape, not existence: a CURP, RFC, CLABE, IBAN or card number can match and still have a wrong check digit, and an email can match and still bounce. Pair them with the check-digit validators, and always validate again on the server.
  • Patterns that need Unicode letters (email, url, domain, onlyLetters, onlyAlphanumeric, personName, hashtag, password) use the u flag.
  • The rfc pattern targets the Mexican format (XAXX000000XXX). Replace it if you target a different jurisdiction, or use regex.custom() with your own pattern.
  • Parametric functions return a fresh { pattern, errorMessage } object on every call, so they are safe to use inline without sharing state.
  • The password builder treats each flag as a requirement, not an allow-list: any non-whitespace character is accepted, so Passw0rd! passes the default policy. uppercase and lowercase count capitals and small letters in any script (Ñ, É), and special: true requires at least one character that is not a letter, number or space (~, €, \…). All flags default to true except special, which defaults to false. Disabling every flag leaves a length-only policy.
  • Parametric builders (digits, phone, creditCard, password, numeral, postalCode for an unknown country) throw a RangeError for negative or fractional counts and for min > max; uuid throws for a version outside 1–8, and date / time for an unknown pattern unit.