Skip to main content

FormModel

The FormModel class manages a collection of fields, their validation, and the overall form state.

You typically don't instantiate FormModel directly — use createModel() instead.

Properties​

fields​

fields: { [P in keyof K]: Field<K[P], K> }

Object containing all field instances, keyed by field name.

form.fields.email.value;   // access a field
form.fields.email.error;   // get validation error

valid​

get valid(): boolean

true if all fields are valid and no validation is in progress. Returns false while any async validator is running.

dirty​

get dirty(): boolean

true if any field's current value differs from its initial (committed) value.

interacted​

get interacted(): boolean

true if the user has set a value on any field.

validating​

get validating(): boolean

true if any field is currently running an async validator, or if a model-level validation is in progress.

validatedAtLeastOnce​

get validatedAtLeastOnce(): boolean

true if all fields have been validated at least once.

dataIsReady​

get dataIsReady(): boolean

Convenience property. true when interacted && requiredAreFilled && valid.

requiredAreFilled​

get requiredAreFilled(): boolean

true if all required fields have a value (doesn't run validators, just checks .hasValue).

requiredFields​

get requiredFields(): (keyof K)[]

Array of field keys that are currently marked as required (excludes disabled fields).

serializedData​

get serializedData(): K

Returns a plain JavaScript object with current field values. String values are trimmed automatically.

const data = form.serializedData;
// { name: 'John', email: 'john@example.com' }

summary​

get summary(): string[]

Array of all current error messages across all fields.

await form.validate();
console.log(form.summary);
// ['Email is required', 'Password must be at least 8 characters']

Methods​

validate()​

validate(): Promise<void>

Validates all fields with force: true, running all validators regardless of interaction or blur state.

await form.validate();
if (form.valid) {
  // submit
}

commit()​

commit(): void

Sets each field's current value as its new initial value, resetting dirty to false.

restoreInitialValues(opts?)​

restoreInitialValues(opts?: {
  resetInteractedFlag?: boolean;  // default: true
  commit?: boolean;                // default: true
}): void

Resets all fields to their last committed initial values.

updateFrom(obj, opts?)​

updateFrom(
  obj: Partial<K>,
  opts?: {
    resetInteractedFlag?: boolean;  // default: true
    commit?: boolean;
    throwIfMissingField?: boolean;
  },
): void

Sets values for multiple fields at once. Useful for loading data from an API.

form.updateFrom({
  name: 'Jane',
  email: 'jane@example.com',
});

updateField(name, value, opts?)​

updateField(
  name: keyof K,
  value?: K[keyof K],
  opts?: {
    resetInteractedFlag?: boolean;
    commit?: boolean;
    throwIfMissingField?: boolean;
  },
): void

Update a single field's value with options.

addFields(descriptors)​

addFields(descriptors: Partial<Descriptors<K>>): void

Dynamically add new fields to the form at runtime.

form.addFields({
  phone: { value: '', required: 'Phone is required' },
});

disableFields(fieldKeys)​

disableFields(fieldKeys: (keyof K)[]): void

Disables the specified fields. Disabled fields skip validation and are not considered required.

enableFields(fieldKeys)​

enableFields(fieldKeys: (keyof K)[]): void

Re-enables previously disabled fields.

resetInteractedFlag()​

resetInteractedFlag(): void

Resets the interacted flag on all fields.

resetValidatedOnce()​

resetValidatedOnce(): void

Resets the validatedAtLeastOnce flag on all fields.

setValidating(validating)​

setValidating(validating: boolean): void

Manually set the model-level validating state.