✅ Zero dependencies
✅ Framework agnostic
✅ Opt-in subscriptions - only update on the state you need!
✅ 💥 3.5k gzipped 💥
npm install --save final-formor
yarn add final-form🏁 Final Form works on subscriptions to perform updates based on the Observer pattern. Both form and field subscribers must specify exactly which parts of the form state they want to receive updates about.
import { createForm } from 'final-form'
// Create Form
const form = createForm({
initialValues,
onSubmit, // required
validate
})
// Subscribe to form state updates
const unsubscribe = form.subscribe(
formState => {
// Update UI
},
{ // FormSubscription: the list of values you want to be updated about
dirty: true,
valid: true,
values: true
}
})
// Subscribe to field state updates
const unregisterField = form.registerField(
'username',
fieldState => {
// Update field UI
const { blur, change, focus, ...rest } = fieldState
// In addition to the values you subscribe to, field state also
// includes functions that your inputs need to update their state.
},
{ // FieldSubscription: the list of values you want to be updated about
active: true,
dirty: true,
touched: true,
valid: true,
value: true
}
)
// Submit
form.submit() // only submits if all validation passes- Examples
- Libraries
- API
- Types
ConfigDebugFunction: (state: FormState, fieldStates: { [string]: FieldState }) => voidDecorator: (form: FormApi) => UnsubscribeFieldConfigFieldStateactive?: booleanblur: () => voidchange: (value: any) => voiddata?: Objectdirty?: booleanerror?: anyfocus: () => voidinitial?: anyinvalid?: booleanlength?: numbername: stringpristine?: booleansubmitError?: anysubmitFailed?: booleansubmitSucceeded?: booleantouched?: booleanvalid?: booleanvalue?: anyvisited?: boolean
FieldSubscriber: (state: FieldState) => voidFieldSubscription: { [string]: boolean }FormApibatch: (fn: () => void) => void)blur: (name: string) => voidchange: (name: string, value: ?any) => voidfocus: (name: string) => voidgetRegisteredFields: () => string[]getState: () => FormStateinitialize: (values: Object) => voidmutators: ?{ [string]: Function }submit: () => ?Promise<?Object>subscribe: (subscriber: FormSubscriber, subscription: FormSubscription) => UnsubscriberegisterField: RegisterFieldreset: () => void
FormStateFormSubscriber: (state: FormState) => voidFormSubscription: { [string]: boolean }InternalFieldStateactive: booleanblur: () => voidchange: (value: any) => voiddata: Objectfocus: () => voidisEqual: (a: any, b: any) => booleanname: stringpristine: booleantouched: booleanvalidateFields: ?(string[])validators: { [number]: (value: ?any, allValues: Object) => ?any | Promise<?any> } }valid: booleanvisited: boolean
InternalFormStateMutableStateMutator: (args: any[], state: MutableState, tools: Tools) => anyRegisterField: (name: string, subscriber: FieldSubscriber, subscription: FieldSubscription, config?: FieldConfig) => UnsubscribeToolsUnsubscribe : () => void
Demonstrates how 🏁 Final Form can be used inside a React component to manage form state. It also shows just how much 🏁 React Final Form does for you out of the box.
For more examples using React, see 🏁 React Final Form Examples.
A form state management system for React that uses 🏁 Final Form under the hood.
A form state management system for Vue that uses 🏁 Final Form under the hood.
The following can be imported from final-form.
Creates a form instance. It takes a Config and returns a
FormApi.
An à la carte list of all the possible things you can subscribe to for a field. Useful for subscribing to everything.
An à la carte list of all the possible things you can subscribe to for a form. Useful for subscribing to everything.
A special Symbol key used to return a whole-form error inside error objects
returned from validation or submission.
The current used version of 🏁 Final Form.
The initial values of your form. These will also be used to compare against the
current values to calculate pristine and dirty.
Optional named mutation functions.
onSubmit: (values: Object, form: FormApi, callback: ?(errors: ?Object) => void) => ?Object | Promise<?Object> | void
Function to call when the form is submitted. There are three possible ways to
write an onSubmit function:
- Synchronously: returns
undefinedon success, or anObjectof submission errors on failure - Asynchronously with a callback: returns
undefined, callscallback()with no arguments on success, or with anObjectof submission errors on failure. - Asynchronously with a
Promise: returns aPromise<?Object>that resolves with no value on success or resolves with anObjectof submission errors on failure. The reason it resolves with errors is to leave rejection for when there is a server or communications error.
Submission errors must be in the same shape as the values of the form. You may
return a generic error for the whole form (e.g. 'Login Failed') using the
special FORM_ERROR symbol key.
A whole-record validation function that takes all the values of the form and
returns any validation errors. There are three possible ways to write a
validate function:
- Synchronously: returns
{}orundefinedwhen the values are valid, or anObjectof validation errors when the values are invalid. - Asynchronously with a
Promise: returns aPromise<?Object>that resolves with no value on success or resolves with anObjectof validation errors on failure. The reason it resolves with errors is to leave rejection for when there is a server or communications error.
Validation errors must be in the same shape as the values of the form. You may
return a generic error for the whole form using the special FORM_ERROR symbol
key.
An optional callback for debugging that returns the form state and the states of
all the fields. It's called on every state change. A typical thing to pass in
might be console.log.
If true, validation will happen on blur. If false, validation will happen on
change. Defaults to false.
A function that decorates a
form by subscribing to it and making changes as the form state changes, and
returns an Unsubscribe function to detach itself from
the form. e.g.
🏁 Final Form Calculate.
A function to determine if two values are equal. Defaults to ===.
A field-level validation function to validate a single field value. Returns an
error if the value is not valid, or undefined if the value is valid.
An array of field names to validate when this field changes. If undefined,
every field will be validated when this one changes; if [], only this
field will have its field-level validation function called when it changes; if
other field names are specified, those fields and this one will be validated
when this field changes.
FieldState is an object containing:
Whether or not the field currently has focus.
A function to blur the field (mark it as inactive).
A function to change the value of the field.
A place for arbitrary values to be placed by mutators.
true when the value of the field is !== the initial value, false if the
values are ===.
The current validation error for this field.
A function to focus the field (mark it as active).
The initial value of the field. undefined if it was never initialized.
true if the field has a validation error or a submission error. false
otherwise.
The length of the array if the value is an array. undefined otherwise.
The name of the field.
true if the current value is === to the initial value, false if the values
are !===.
The submission error for this field.
true if a form submission has been tried and failed. false otherwise.
true if the form has been successfully submitted. false otherwise.
true if this field has ever gained and lost focus. false otherwise. Useful
for knowing when to display error messages.
true if this field has no validation or submission errors. false otherwise.
The value of the field.
true if this field has ever gained focus.
FieldSubscription is an object containing the following:
When true the FieldSubscriber will be notified of changes to the active
value in FieldState.
When true the FieldSubscriber will be notified of changes to the data
value in FieldState.
When true the FieldSubscriber will be notified of changes to the dirty
value in FieldState.
When true the FieldSubscriber will be notified of changes to the error
value in FieldState.
When true the FieldSubscriber will be notified of changes to the initial
value in FieldState.
When true the FieldSubscriber will be notified of changes to the invalid
value in FieldState.
When true the FieldSubscriber will be notified of changes to the length
value in FieldState.
When true the FieldSubscriber will be notified of changes to the pristine
value in FieldState.
When true the FieldSubscriber will be notified of changes to the
submitError value in FieldState.
When true the FieldSubscriber will be notified of changes to the
submitFailed value in FieldState.
When true the FieldSubscriber will be notified of changes to the
submitSucceeded value in FieldState.
When true the FieldSubscriber will be notified of changes to the touched
value in FieldState.
When true the FieldSubscriber will be notified of changes to the valid
value in FieldState.
When true the FieldSubscriber will be notified of changes to the value
value in FieldState.
When true the FieldSubscriber will be notified of changes to the visited
value in FieldState.
Allows batch updates by silencing notifications while the fn is running.
Example:
form.batch(() => {
form.change('firstName', 'Erik') // listeners not notified
form.change('lastName', 'Rasmussen') // listeners not notified
}) // NOW all listeners notifiedBlurs (marks inactive) the given field.
Changes the value of the given field.
Focuses (marks active) the given field.
Returns a list of all the currently registered fields.
A way to request the current state of the form without subscribing.
Initializes the form to the values provided. All the values will be set to these
values, and dirty and pristine will be calculated by performing a
shallow-equals between the current values and the values last initialized with.
The form will be pristine after this call.
The state-bound versions of the mutators provided to Config.
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.
Subscribes to changes to the form. The subscriber will only be called when
values specified in subscription change. A form can have many subscribers.
Registers a new field and subscribes to changes to it. The subscriber will
only be called when the values specified in subscription change. More than
one subscriber can subscribe to the same field.
This is also where you may provide an optional field-level validation function
that should return undefined if the value is valid, or an error. It can
optionally return a Promise that resolves (not rejects) to undefined or an
error.
Resets the values back to the initial values the form was initialized with. Or empties all the values if the form was not initialized.
The name of the currently active field. undefined if none are active.
true if the form values are different from the values it was initialized with.
false otherwise. Comparison is done with shallow-equals.
The whole-form error returned by a validation function under the FORM_ERROR
key.
An object containing all the current validation errors. The shape will match the shape of the form's values.
The values the form was initialized with. undefined if the form was never
initialized.
true if any of the fields or the form has a validation or submission error.
false otherwise. Note that a form can be invalid even if the errors do not
belong to any currently registered fields.
true if the form values are the same as the initial values. false otherwise.
Comparison is done with shallow-equals.
The whole-form submission error returned by onSubmit under the FORM_ERROR
key.
An object containing all the current submission errors. The shape will match the shape of the form's values.
true if the form was submitted, but the submission failed with submission
errors. false otherwise.
true if the form was successfully submitted. false otherwise.
true if the form is currently being submitted asynchronously. false
otherwise.
true if neither the form nor any of its fields has a validation or submission
error. false otherwise. Note that a form can be invalid even if the errors do
not belong to any currently registered fields.
true if the form is currently being validated asynchronously. false
otherwise.
The current values of the form.
FormSubscription is an object containing the following:
When true the FormSubscriber will be notified of changes to the active
value in FormState.
When true the FormSubscriber will be notified of changes to the dirty
value in FormState.
When true the FormSubscriber will be notified of changes to the error
value in FormState.
When true the FormSubscriber will be notified of changes to the errors
value in FormState.
When true the FormSubscriber will be notified of changes to the
initialValues value in FormState.
When true the FormSubscriber will be notified of changes to the invalid
value in FormState.
When true the FormSubscriber will be notified of changes to the pristine
value in FormState.
When true the FormSubscriber will be notified of changes to the
submitError value in FormState.
When true the FormSubscriber will be notified of changes to the
submitErrors value in FormState.
When true the FormSubscriber will be notified of changes to the
submitFailed value in FormState.
When true the FormSubscriber will be notified of changes to the
submitSucceeded value in FormState.
When true the FormSubscriber will be notified of changes to the submitting
value in FormState.
When true the FormSubscriber will be notified of changes to the valid
value in FormState.
When true the FormSubscriber will be notified of changes to the validating
value in FormState.
When true the FormSubscriber will be notified of changes to the values
value in FormState.
Very similar to the published FieldState.
Whether or not the field currently has focus.
A function to blur the field (mark it as inactive).
A function to change the value of the field.
A place for arbitrary values to be placed by mutators.
A function to focus the field (mark it as active).
A function to determine if two values are equal. Used to calculate
pristine/dirty.
The name of the field.
true if the current value is === to the initial value, false if the values
are !===.
true if this field has ever gained and lost focus. false otherwise. Useful
for knowing when to display error messages.
Fields to validate when this field value changes.
Field-level validators for each field that is registered.
true if this field has no validation or submission errors. false otherwise.
true if this field has ever gained focus.
Very similar to the published FormState, with a few minor
differences.
The name of the currently active field. undefined if none are active.
The whole-form error returned by a validation function under the FORM_ERROR
key.
An object containing all the current validation errors. The shape will match the shape of the form's values.
The values the form was initialized with. undefined if the form was never
initialized.
true if the form values are the same as the initial values. false otherwise.
Comparison is done with shallow-equals.
The whole-form submission error returned by onSubmit under the FORM_ERROR
key.
An object containing all the current submission errors. The shape will match the shape of the form's values.
true if the form was submitted, but the submission failed with submission
errors. false otherwise.
true if the form was successfully submitted. false otherwise.
true if the form is currently being submitted asynchronously. false
otherwise.
true if neither the form nor any of its fields has a validation or submission
error. false otherwise. Note that a form can be invalid even if the errors do
not belong to any currently registered fields.
The number of asynchronous validators currently running.
The current values of the form.
MutableState is an object containing the following:
The InternalFormState.
An object of InternalFieldStates.
A mutator function that takes some arguments, the internal form
MutableState, and some Tools and optionally
modifies the form state.
RegisterField: (name: string, subscriber: FieldSubscriber, subscription: FieldSubscription, config?: FieldConfig) => Unsubscribe
Takes a name, and a
FieldSubscriber,
FieldSubscriber, and a
FieldConfig and registers a field subscription.
An object containing:
A utility function to modify a single field value in form state. mutate()
takes the old value and returns the new value.
A utility function to get any arbitrarily deep value from an object using
dot-and-bracket syntax (e.g. some.deep.values[3].whatever).
A utility function to set any arbitrarily deep value inside an object using
dot-and-bracket syntax (e.g. some.deep.values[3].whatever). Note: it does
not mutate the object, but returns a new object.
A utility function to compare the keys of two objects. Returns true if the
objects have the same keys and the values are ===, false otherwise.
Unsubscribes a listener.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent