API Reference

useRapidForm()

The single hook exported by rapid-form. Call it inside any React component to get form state and the validation attachment function.

import { useRapidForm } from 'rapid-form'

const { refValidation, values, errors, numberOfRequiredFields } = useRapidForm()

Return values

Name	Type	Description
refValidation	(ref: HTMLFormElement | null, config?: Config) => void	Attaches validation logic to a form element. Pass it as the form’s ref callback.
values	Record<string, Value>	Live map of every tracked field, keyed by the field’s name attribute.
errors	Record<string, FieldError>	Map of validation errors for each field, keyed by the field’s name attribute. Only fields that have been interacted with appear here.
numberOfRequiredFields	number	Count of distinct field names that carry the required attribute in the attached form. A radio group counts once, however many members it has. Required elements without a name are not counted, since rapid-form never tracks them.

List-valued fields

Value['value'] is string | string[]. A <select multiple> or <input type="file" multiple> reports every selection as a string[] — empty selection is []. Every other field type reports a string.

values.langs?.value   // ['ts', 'go']  — <select multiple>
values.email?.value   // 'a@b.com'     — everything else

Narrow with Array.isArray or typeof before using a value as a string. Migrating from v4? See Migration v4 → v5.

---

refValidation(ref, config?)

Attaches Rapid Form’s validation listeners to a form element. Typically called inside a React ref callback on the <form> element.

<form
  ref={(ref) => {
    refValidation(ref, config)
  }}
>
  {/* fields */}
</form>

Parameters

Parameter	Type	Required	Description
ref	HTMLFormElement | null	Yes	The native form element. React passes null when the component unmounts — the function handles this safely.
config	Config	No	Optional configuration object. See Config below.

Reserved field names

Fields named __proto__, constructor, or prototype are silently ignored by rapid-form for security reasons. Validation listeners are never attached to these fields and their values will not appear in errors or values.

---

Config

The optional second argument to refValidation. All properties are optional.

type Config = {
  eventType?: 'input' | 'blur' | 'change'
  resetOnSubmit?: boolean
  validations?: Record<string, ValidationEntry>
  resolver?: SchemaResolver
  trackUnvalidatedFields?: boolean
}

Properties

Property	Type	Default	Description
eventType	'input' | 'blur' | 'change'	'input'	The DOM event that triggers validation for all fields. Can be overridden per field inside validations.
resetOnSubmit	boolean	true	When true, form field values are cleared and the values / errors state is reset after the form’s submit event fires.
validations	Record<string, ValidationEntry>	—	Per-field validation overrides. The record key must match the field’s name attribute. Ignored when resolver is set.
resolver	SchemaResolver	—	Schema resolver function. When provided it replaces per-field validations. See Schema Validation for built-in Zod and Yup adapters.
trackUnvalidatedFields	boolean	false	When true, every named field appears in values even if it is neither required nor listed in validations. Such fields carry no validation constraint. No effect when resolver is set — resolver mode already tracks every named field.

Note

eventType: 'input' fires on every keystroke, giving real-time feedback. Use 'blur' if you prefer to validate only when the user leaves a field.

Reading optional fields

By default an optional field never reaches values, because rapid-form only attaches listeners to fields it validates. Set trackUnvalidatedFields: true when you need to read optional values — it avoids declaring a placeholder validations entry that imposes a constraint you don’t want.

<form ref={(ref) => refValidation(ref, { trackUnvalidatedFields: true })}>
  <input name="email" type="email" required />
  <input name="company" type="text" />
</form>

values.company now updates as the user types, while numberOfRequiredFields stays 1 — tracking and requiredness are independent.

---

ValidationEntry

A per-field configuration object supplied as a value inside Config.validations.

type ValidationEntry = {
  validation: (props: {
    value: string | string[]
    formElements: HTMLFormControlsCollection
  }) => boolean
  eventType?: 'input' | 'blur' | 'change'
  message?: string
}

Properties

Property	Type	Required	Description
validation	(props: { value: string | string[]; formElements: HTMLFormControlsCollection }) => boolean	Yes	Custom validation function. Return true when the value is valid, false when it is invalid. Receives the current field value and the full formElements collection so you can cross-reference other fields. value is a string[] for list-valued fields — narrow with Array.isArray or typeof before using it as a string.
eventType	'input' | 'blur' | 'change'	No	Overrides the top-level eventType for this specific field only.
message	string	No	Error message stored in errors[name].message when this field’s validation returns false.

Example — require a field to be longer than 10 characters, validated on blur:

refValidation(ref, {
  validations: {
    username: {
      eventType: 'blur',
      validation: ({ value }) => value.length > 10,
      message: 'Username must be more than 10 characters',
    },
  },
})

Example — cross-field validation (password confirmation):

refValidation(ref, {
  validations: {
    confirmPassword: {
      validation: ({ value, formElements }) => {
        const password = formElements.namedItem('password') as HTMLInputElement
        return value === password?.value
      },
      message: 'Passwords do not match',
    },
  },
})

---

Error object shape (FieldError)

Each entry in the errors map conforms to the FieldError type.

type FieldError = {
  name: string
  value: string | string[]
  isInvalid: boolean
  errorType?: 'invalidFormat'
  message?: string
}

Properties

Property	Type	Description
name	string	The name attribute of the form field.
value	string | string[]	The current value of the field at the time the error was recorded. A string[] for list-valued fields.
isInvalid	boolean	true when the field fails validation, false when it passes. Use this as the primary flag for disabling submit buttons or showing error UI.
errorType	'invalidFormat' | undefined	Set to 'invalidFormat' for built-in format checks (e.g. email format, password length). undefined for custom validation errors.
message	string | undefined	Human-readable error message. Populated from the message property of a ValidationEntry, or a built-in default message for format errors.

Typical usage:

const { errors } = useRapidForm()
const isFormValid = Object.values(errors).every((e) => !e.isInvalid)

// Render an inline error
{errors.email?.isInvalid && (
  <span role="alert">{errors.email.message}</span>
)}

// Disable the submit button until all fields are valid
<button type="submit" disabled={!isFormValid}>
  Submit
</button>

---

SchemaResolver

A function type that receives all current form values and returns a map of error messages. Both sync and async resolvers are supported.

import type { SchemaResolver } from 'rapid-form'

type SchemaResolver = (
  values: Record<string, string | string[]>
) =>
  | Record<string, string | undefined>
  | Promise<Record<string, string | undefined>>

Return undefined (or omit the key) for fields that pass validation. Return a string message for fields that fail.

Built-in adapters are available for Zod and Yup — see the Schema Validation guide.

---

Exported TypeScript types

All types are re-exported from the package root and can be imported directly.

import type { Config, Value, FieldError, NumberOfRequiredFields, SchemaResolver } from 'rapid-form'

Type	Definition	Description
Config	{ eventType?: EventType; resetOnSubmit?: boolean; validations?: Record<string, ValidationEntry>; resolver?: SchemaResolver; trackUnvalidatedFields?: boolean }	The optional config parameter accepted by refValidation.
Value	{ name: string; value: string | string[] }	Shape of each entry in the values map returned by useRapidForm. Checkbox fields report their checked state as 'true' / 'false', ignoring any value attribute. A radio group is one entry keyed by its shared name, holding the selected member’s value ('' when nothing is selected). List-valued fields — <select multiple> and <input type="file" multiple> — hold a string[].
FieldError	{ name: string; value: string | string[]; isInvalid: boolean; errorType?: 'invalidFormat'; message?: string }	Shape of each entry in the errors map returned by useRapidForm.
NumberOfRequiredFields	number	Alias for the numberOfRequiredFields return value.
SchemaResolver	(values: Record<string, string | string[]>) => Record<string, string | undefined> | Promise<...>	Schema resolver function type. Use with the built-in adapters or write your own.