String

Use x.string() for text values. Supports format validators like .email(), .url(), and length constraints.

x.string().label("Company Name").min(2).max(100)

columnNameAliases

Use alternate CSV headers for the same field.

.columnNameAliases(aliases: string[])

• aliases lists the alternate column names, e.g., ["Email", "Email Address"].

label

Sets the user-facing label shown in the widget.

.label(text: string)

• text sets the label text.

description

Sets help text shown below the field.

.description(text: string)

• text sets the description text.

example

Sets the placeholder example value.

.example(text: string)

• text sets the example value.

optional

Makes the field optional.

.optional()

default

Available after .optional().

.default(defaultValue: unknown | (() => unknown | Promise<unknown>))

• defaultValue can be a static value or a function used when the field is empty, e.g., "Unknown" or () => new Date().toISOString().

email

Validates email format.

.email(options?: { message?: string })

• message overrides the validation error text, e.g., "Enter a valid email address".

url

Validates URLs.

.url(options?: { allowedProtocols?: ("http" | "https" | "ftp" | "sftp" | "file" | "mailto" | "tel")[]; allowedDomains?: string[]; allowSubdomains?: boolean; allowPaths?: boolean; allowQueryParams?: boolean; message?: string })

• allowedProtocols restricts accepted protocols, e.g., ["https"] or ["https", "mailto"].
• allowedDomains restricts accepted domains, e.g., ["example.com"].
• allowSubdomains controls whether subdomains are accepted.
• allowPaths controls whether paths are accepted.
• allowQueryParams controls whether query strings are accepted.
• message overrides the validation error text, e.g., "Only company URLs are allowed".

uuid

Validates UUIDs.

.uuid(options?: { version?: "v1" | "v4" | "v5" | "all"; message?: string })

• version restricts the accepted UUID version, e.g., "v4" or "all".
• message overrides the validation error text, e.g., "Use a valid UUID".

ip

Validates IP addresses.

.ip(options?: { version?: "v4" | "v6" | "all"; message?: string })

• version restricts the accepted IP version, e.g., "v4", "v6", or "all".
• message overrides the validation error text, e.g., "Enter a valid IP address".

phone

Validates phone numbers.

.phone(options?: { allowedCountries?: string[]; format?: "international" | "national" | "both"; output?: "e164" | "formatted" | "digits"; message?: string })

• allowedCountries restricts input to ISO 3166-1 alpha-2 country codes, e.g., ["US"] or ["US", "CA"].
• format controls the expected input format, e.g., "international", "national", or "both".
• output controls the normalized output format, e.g., "e164", "formatted", or "digits".
• message overrides the validation error text, e.g., "Enter a valid US phone number".

country

Validates country names or codes.

.country(options?: { output?: "name" | "2-letter" | "3-letter"; message?: string })

• output controls the parsed country format, e.g., "name", "2-letter", or "3-letter".
• message overrides the validation error text, e.g., "Enter a valid country".

alphabetical

Restricts values to letters only.

.alphabetical(options?: { message?: string })

• message overrides the validation error text, e.g., "Use letters only".

alphanumerical

Restricts values to letters and numbers only.

.alphanumerical(options?: { message?: string })

• message overrides the validation error text, e.g., "Use letters and numbers only".

numerical

Restricts values to numeric characters only.

.numerical(options?: { message?: string })

• message overrides the validation error text, e.g., "Use numeric characters only".

regex

Matches a regular expression.

.regex(pattern: RegExp, options?: { message?: string })

• pattern is the regular expression to match, e.g., /^[A-Z]{3}-\d{4}$/.
• message overrides the validation error text, e.g., "Use format ABC-1234".

iban

Validates IBAN values.

.iban(options?: { allowedCountries?: string[]; message?: string })

• allowedCountries restricts input to ISO 3166-1 alpha-2 country codes, e.g., ["DE"] or ["DE", "FR"].
• message overrides the validation error text, e.g., "Enter a valid EU IBAN".

bic

Validates BIC/SWIFT codes.

.bic(options?: { message?: string })

• message overrides the validation error text, e.g., "Enter a valid BIC/SWIFT code".

gtin

Validates GTIN values.

.gtin(options?: { message?: string })

• message overrides the validation error text, e.g., "Enter a valid GTIN".

currencyCode

Validates ISO 4217 currency codes.

.currencyCode(options?: { allowedCurrencies?: string[]; message?: string })

• allowedCurrencies restricts input to specific currency codes, e.g., ["USD"] or ["USD", "EUR"].
• message overrides the validation error text, e.g., "Use a supported currency code".

min

Sets the minimum length.

.min(minLength: number, options?: { message?: string })

• minLength sets the minimum length.
• message overrides the validation error text, e.g., "Must be at least 8 characters".

max

Sets the maximum length.

.max(maxLength: number, options?: { message?: string })

• maxLength sets the maximum length.
• message overrides the validation error text, e.g., "Must be 255 characters or fewer".

length

Sets the required exact length.

.length(exactLength: number, options?: { message?: string })

• exactLength sets the required exact length.
• message overrides the validation error text, e.g., "Must be exactly 2 characters".

includes

Requires a substring.

.includes(substring: string, options?: { message?: string })

• substring sets the required substring.
• message overrides the validation error text, e.g., "Must include @".

startsWith

Requires a prefix.

.startsWith(prefix: string, options?: { message?: string })

• prefix sets the required prefix.
• message overrides the validation error text, e.g., "Must start with INV-".

endsWith

Requires a suffix.

.endsWith(suffix: string, options?: { message?: string })

• suffix sets the required suffix.
• message overrides the validation error text, e.g., "Must end with .com".