API
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.
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
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