Skip to main content

API

info

The description of some of the functions is taken from the Final Form documentation

Form​

createForm​

Form creation function.

Takes the same config as createForm from Final Form with the differences

  • you can't pass debug option
  • you need to pass subscribeOn

Returns:

  • api
  • $
const { api, $ } = createForm<{ firstName: string }>({
  onSubmit: async (f) => {
    await sleep(1000);

    return f.firstName === 'Incorrect' ? { firstName: 'Submit Error' } : undefined;
  },
  subscribeOn: ['values', 'errors', 'submitting', 'submitSucceeded', 'submitFailed', 'submitErrors'],
  // like config from Final Form with omited 'debug' | 'initialValues' | 'validate'
});

pauseValidation​

If called, validation will be paused until resumeValidation() is called.

() => void

registerField​

Registers a new field. Returns a field = $ (field state) and api for thid field.

Example
const form = createForm<{ name: string }>({ onSubmit: () => {}, subscribe: ['active'] });

const field = form.api.registerField({
  name: 'firstName',
  subscribeOn: ['value'],
  initialValue: 'defaultValue', // Optional. or Store with a value
  validate: (x) => (x === 'Steve' ? 'Error' : undefined), // Optional.
  // config?: like config from Final Form with omited 'initialValue' | 'getValidator'
});

setSubmitFn​

Not presented in Final Form.

Allows you to dynamically set submit function. Uses effect.use under the hood.

(_: (values: FormValues) => Promise<SubmissionErrors | void>) => void

revalidateFx​

Not presented in Final Form.

Triggers form revalidation. Can be useful when the form validation function depends on dynamic parameters (e.g. store value)

const setError = createEvent<string>();
const $error = createStore<string>('');

sample({ clock: setError, target: $error });
sample({ clock: setError, target: api.reValidateFx });

const validationFx = attach(() => {
  effect: ({ fields, error }) => {
    if (fields.firstName.length <= 2) {
      return { firstName: error }
    }
  },
  source: $error,
  mapParams: (fields, error) => ({ fields, error })
})

setError('Incorrect value');

reset​

Resets the values back to the initial values the form was initialized with. Or empties all the values if the form was not initialized. If you provide initialValues they will be used as the new initial values.

(initialValues: ?InitialFormValues) => Promise<void>;

restart​

Resets all form and field state. Same as calling reset(initialValues) on the form and resetState() for each field. Form should be just as it was when it was first created.

(initialValues: ?InitialFormValues) => Promise<void>;

resumeValidation​

Resumes validation paused by pauseValidation(). If validation was blocked while it was paused, validation will be run.

() => Promise<void>;

submitFx​

Submits the form if there are currently no validation errors. It may return undefined or a Promise depending on the nature of the onSubmit configuration value given to the form when it was created.

() => Promise<Object | undefined | void>;

form.$​

It is a Store that stores the form state. The keys are taken from subscribeOn + isValidationOnPause

Example
const form = createForm({
  onSubmit: () => {},
  initialValues: { firstName: '' },
  subscribeOn: ['active', 'errors'],
});

form.$.getState(); // { active: null, errors: {}, isValidationPaused: false }

Field​

blurFx​

Blurs (marks inactive) the given field.

() => Promise<void>;

changeFx​

Changes the value of the given field.

<F extends keyof FormValues>(value?: FormValues[F]) => Promise<void>;

focusFx​

Focuses (marks active) the given field.

() => Promise<void>;

resetState​

Resets all of a field's flags (e.g. touched, visited, etc.) to their initial state.

(name: string) => Promise<void>;

setValidationFn​

Not presented in Final Form.

Allows you to dynamically set validation function. Uses effect.use under the hood.

(_: (params: FormValues) => Promise<SubmissionErrors | void>) => void