createForm

This method creates a new form instance representing the form in your application.

Options

type FormOptions<
  TForm extends Record<string, unknown>,
  TMeta extends Record<string, unknown> = Record<string, unknown>
> = {
  initial: TForm
  validators?: Validators<TForm, TMeta>
  asyncValidators?: AsyncValidators<TForm, TMeta>
  comparators?: Comparators<TForm>
  onSubmitForm?: OnSubmitForm<TForm, TMeta>
  meta?: TMeta
  config?: FormConfig
}

initial

Required property representing the initial object model for your form. This initial values can also be updated during the lifetime of the form instance and is used to determine form modifications.

validators

Object representing validators that run synchronously. Each field validator is a synchronous function that returns an Error instance if validation fails, or undefined if validation is successfull.

asyncValidators

Object representing validators that run asynchronously. Each field async validator is a Promise that either resolves with an Error instance if validation fails, or undefined if validation is successfull.

comparators

Custom comparator functions for each form field. To determine modifications, each fields value must be compared to its previous value.

By default, field equality is determined with strictly equal operator (===) for primitives, and deep equality for objects, so use this property only if needed.

onSubmitForm

type OnSubmitForm<TForm, TMeta> = (
  form: TForm,
  meta: TMeta,
  modifiedFields: Partial<TForm>
) => Promise<unknown> | void

Function that contains your "submit" logic. Gets called with latest form values, any metadefined and a special modifications object that will contain only the form fields which differ from the latest initial values.

Works in conjuction with submit method returned from createForm and gets called only if all validations pass.

Returning a promise from this function makes returned isSubmitting value true until promise resolves.

config

Configuration options for the current form.

Overrides global config if set.

Read more about the configuration options here.

meta

Optional object that holds additional info which is forwarded to callback functions you provided - like onSubmitForm and validator functions.

Primarily used to resolve a stale closure problem if your callback functions depend on some surrounding state.

Most likely not needed in libraries like Solid.js.

Returns

type FormResult<TForm> = {
  values: TForm
  validations: ValidationResults<TForm>
  modifications: ModificationResults<TForm>
  update: <Key extends keyof TForm>(key: Key, value: TForm[Key]) => void
  runValidation: <Key extends keyof TForm>(key: Key) => void
  submit: () => void
  clear: () => void
  isValid: boolean
  isValidating: boolean
  isSubmitting: boolean
  isModified: boolean
}

values

Object holding the latest values for your form.

validations

Object that contains ValidationState for each form key.

export type ValidationState = {
  validating: boolean,
  error: ValidationResult,
  checked: boolean,
}

modifications

Object that contains modification state for each form key.

type ModificationResults<TForm> = Record<
  keyof TForm,
  { isModified: boolean }
>

update

Used to update form field values. Function takes a key which represents your specific form field, and the new value as arguments.

runValidation

Manually run validation for given field. Validation results are cached and not repeated until the value changes.

submit

Method that starts the validation process.

By default, starts sequential validation of your form fields, and stops if some validation fails.

Can be configured to run all validations in parallel.

Calls onSubmitForm internally if all validations pass.

clear

Resets form to the initial values.

isValid

true if there are no pending or ongoing validations, and all form values are checked and validated.

isValidating

true if there are ongoing validations.

isSubmitting

If your onSubmitForm function returns a Promise, the value will be true until Promise resolves.

isModified

If any of your form fields differs from its value defined in the initial object, this flag will be set to true.