final-form
Advanced tools
š Framework agnostic, high performance, subscription-based form state management
Final Form is a framework-agnostic library for managing form state in JavaScript. It provides a simple API for handling form validation, submission, and state management, making it easier to build complex forms with minimal boilerplate code.
Form State Management
Final Form provides a simple way to manage form state. The `Form` component handles the form submission, while the `Field` component is used to define form fields. The form state is managed internally and can be accessed via the `render` prop.
const { Form, Field } = require('react-final-form');
const MyForm = () => (
<Form
onSubmit={formValues => {
console.log(formValues);
}}
render={({ handleSubmit }) => (
<form onSubmit={handleSubmit}>
<Field name="firstName" component="input" placeholder="First Name" />
<Field name="lastName" component="input" placeholder="Last Name" />
<button type="submit">Submit</button>
</form>
)}
/>
);Validation
Final Form allows you to easily add validation to your forms. The `validate` function is used to define validation rules, and it returns an object containing any validation errors. These errors are then displayed in the form.
const { Form, Field } = require('react-final-form');
const validate = values => {
const errors = {};
if (!values.firstName) {
errors.firstName = 'Required';
}
if (!values.lastName) {
errors.lastName = 'Required';
}
return errors;
};
const MyForm = () => (
<Form
onSubmit={formValues => {
console.log(formValues);
}}
validate={validate}
render={({ handleSubmit }) => (
<form onSubmit={handleSubmit}>
<Field name="firstName" component="input" placeholder="First Name" />
<Field name="lastName" component="input" placeholder="Last Name" />
<button type="submit">Submit</button>
</form>
)}
/>
);Field-Level Validation
Final Form supports field-level validation, allowing you to define validation rules for individual fields. The `validate` prop on the `Field` component is used to specify the validation function for that field.
const { Form, Field } = require('react-final-form');
const required = value => (value ? undefined : 'Required');
const MyForm = () => (
<Form
onSubmit={formValues => {
console.log(formValues);
}}
render={({ handleSubmit }) => (
<form onSubmit={handleSubmit}>
<Field name="firstName" component="input" placeholder="First Name" validate={required} />
<Field name="lastName" component="input" placeholder="Last Name" validate={required} />
<button type="submit">Submit</button>
</form>
)}
/>
);Form Submission
Final Form makes it easy to handle form submission. The `onSubmit` prop on the `Form` component is used to define the submission handler, which receives the form values as an argument.
const { Form, Field } = require('react-final-form');
const MyForm = () => (
<Form
onSubmit={formValues => {
console.log('Form submitted with values:', formValues);
}}
render={({ handleSubmit }) => (
<form onSubmit={handleSubmit}>
<Field name="firstName" component="input" placeholder="First Name" />
<Field name="lastName" component="input" placeholder="Last Name" />
<button type="submit">Submit</button>
</form>
)}
/>
);Formik is a popular form library for React that provides a higher-level API for managing form state, validation, and submission. It offers more built-in features and integrations compared to Final Form, but it is specifically designed for React applications.
React Hook Form is a performant, flexible form library for React that leverages hooks for managing form state and validation. It is known for its minimal re-renders and easy integration with existing components, making it a lightweight alternative to Final Form.
Redux Form is a form library that integrates with Redux for managing form state. It provides a robust set of features for handling complex form scenarios but can be more complex to set up and use compared to Final Form. It is suitable for applications already using Redux.
ā Zero dependencies
ā Framework agnostic
ā Opt-in subscriptions - only update on the state you need!
ā š„ 3.5k gzipped š„
npm install --save final-form
or
yarn add final-form
š Final Form works on subscriptions to 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
Config
DebugFunction: (state: FormState, fieldStates: { [string]: FieldState }) => voidFieldState
active?: booleanblur: () => voidchange: (value: any) => voiddata?: Objectdirty?: booleanerror?: anyfocus: () => voidinitial?: anyinvalid?: booleanlength?: numbername: stringpristine?: booleansubmitError?: anysubmitFailed?: booleansubmitSucceeded?: booleantouched?: booleanvalid?: booleanvalue?: anyvisited?: booleanFieldSubscriber: (state: FieldState) => voidFieldSubscription: { [string]: boolean }
FormApi
batch: (fn: () => void) => void)blur: (name: string) => voidchange: (name: string, value: ?any) => voidfocus: (name: string) => voidgetState: () => FormStateinitialize: (values: Object) => voidmutators: ?{ [string]: Function }submit: () => ?Promise<?Object>subscribe: (subscriber: FormSubscriber, subscription: FormSubscription) => UnsubscriberegisterField: RegisterFieldreset: () => voidFormState
FormSubscriber: (state: FormState) => voidFormSubscription: { [string]: boolean }
InternalFieldState
InternalFormState
MutableState: { formState: InternalFormState, fields: { [string]: InternalFieldState } }Mutator: (args: any[], state: MutableState, tools: Tools) => anyRegisterField: (name: string, subscriber: FieldSubscriber, subscription: FieldSubscription, validate?: (value: ?any, allValues: Object) => ?any) => UnsubscribeTools
Unsubscribe : () => voidDemonstrates 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.
The following can be imported from final-form.
createForm: (config: Config) => FormApiCreates a form instance. It takes a Config and returns a
FormApi.
fieldSubscriptionItems: string[]An Ć la carte list of all the possible things you can subscribe to for a field. Useful for subscribing to everything.
formSubscriptionItems: string[]An Ć la carte list of all the possible things you can subscribe to for a form. Useful for subscribing to everything.
FORM_ERROR: SymbolA special Symbol key used to return a whole-form error inside error objects
returned from validation or submission.
version: stringThe current used version of š Final Form.
Configdebug?: DebugFunctioninitialValues?: ObjectThe initial values of your form. These will also be used to compare against the
current values to calculate pristine and dirty.
mutators?: { [string]: Mutator }Optional named mutation functions.
onSubmit: (values: Object, callback: ?(errors: ?Object) => void) => ?Object | Promise<?Object> | voidFunction to call when the form is submitted. There are three possible ways to
write an onSubmit function:
undefined on success, or an Object of submission
errors on failureundefined, calls callback() with
no arguments on success, or with an Object of submission errors on failure.Promise: returns a Promise<?Object> that resolves
with no value on success or resolves with an Object of 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.
validate?: (values: Object) => Object | Promise<Object>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:
{} or undefined when the values are valid, or an
Object of validation errors when the values are invalid.Promise: returns a Promise<?Object> that resolves
with no value on success or resolves with an Object of 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.
validateOnBlur?: booleanIf true, validation will happen on blur. If false, validation will happen on
change. Defaults to false.
DebugFunction: (state: FormState, fieldStates: { [string]: FieldState }) => voidFieldStateFieldState is an object containing:
active?: booleanWhether or not the field currently has focus.
blur: () => voidA function to blur the field (mark it as inactive).
change: (value: any) => voidA function to change the value of the field.
data?: ObjectA place for arbitrary values to be placed by mutators.
dirty?: booleantrue when the value of the field is !== the initial value, false if the
values are ===.
error?: anyThe current validation error for this field.
focus: () => voidA function to focus the field (mark it as active).
initial?: anyThe initial value of the field. undefined if it was never initialized.
invalid?: booleantrue if the field has a validation error or a submission error. false
otherwise.
length?: numberThe length of the array if the value is an array. undefined otherwise.
name: stringThe name of the field.
pristine?: booleantrue if the current value is === to the initial value, false if the values
are !===.
submitError?: anyThe submission error for this field.
submitFailed?: booleantrue if a form submission has been tried and failed. false otherwise.
submitSucceeded?: booleantrue if the form has been successfully submitted. false otherwise.
touched?: booleantrue if this field has ever gained and lost focus. false otherwise. Useful
for knowing when to display error messages.
valid?: booleantrue if this field has no validation or submission errors. false otherwise.
value?: anyThe value of the field.
visited?: booleantrue if this field has ever gained focus.
FieldSubscriber: (state: FieldState) => voidFieldSubscription: { [string]: boolean }FieldSubscription is an object containing the following:
active?: booleanWhen true the FieldSubscriber will be notified of changes to the active
value in FieldState.
data?: booleanWhen true the FieldSubscriber will be notified of changes to the data
value in FieldState.
dirty?: booleanWhen true the FieldSubscriber will be notified of changes to the dirty
value in FieldState.
error?: booleanWhen true the FieldSubscriber will be notified of changes to the error
value in FieldState.
initialValues?: booleanWhen true the FieldSubscriber will be notified of changes to the
initialValues value in FieldState.
invalid?: booleanWhen true the FieldSubscriber will be notified of changes to the invalid
value in FieldState.
length?: booleanWhen true the FieldSubscriber will be notified of changes to the length
value in FieldState.
pristine?: booleanWhen true the FieldSubscriber will be notified of changes to the pristine
value in FieldState.
submitting?: booleanWhen true the FieldSubscriber will be notified of changes to the
submitting value in FieldState.
submitFailed?: booleanWhen true the FieldSubscriber will be notified of changes to the
submitFailing value in FieldState.
submitSucceeded?: booleanWhen true the FieldSubscriber will be notified of changes to the
submitSucceeded value in FieldState.
valid?: booleanWhen true the FieldSubscriber will be notified of changes to the valid
value in FieldState.
validating?: booleanWhen true the FieldSubscriber will be notified of changes to the
validating value in FieldState.
values?: booleanWhen true the FieldSubscriber will be notified of changes to the values
value in FieldState.
FormApibatch: (fn: () => void) => void)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 notified
blur: (name: string) => voidBlurs (marks inactive) the given field.
change: (name: string, value: ?any) => voidChanges the value of the given field.
focus: (name: string) => voidFocuses (marks active) the given field.
getState: () => FormStateA way to request the current state of the form without subscribing.
initialize: (values: Object) => voidInitializes 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.
mutators: ?{ [string]: Function }The state-bound versions of the mutators provided to Config.
submit: () => ?Promise<?Object>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.
subscribe: (subscriber: FormSubscriber, subscription: FormSubscription) => UnsubscribeSubscribes to changes to the form. The subscriber will only be called when
values specified in subscription change. A form can have many subscribers.
registerField: RegisterFieldRegisters 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.
reset: () => voidResets the values back to the initial values the form was initialized with. Or empties all the values if the form was not initialized.
FormStateactive?: stringThe name of the currently active field. undefined if none are active.
dirty?: booleantrue if the form values are different from the values it was initialized with.
false otherwise. Comparison is done with shallow-equals.
error?: anyThe whole-form error returned by a validation function under the FORM_ERROR
key.
errors?: ObjectAn object containing all the current validation errors. The shape will match the shape of the form's values.
initialValues?: ObjectThe values the form was initialized with. undefined if the form was never
initialized.
invalid?: booleantrue 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.
pristine?: booleantrue if the form values are the same as the initial values. false otherwise.
Comparison is done with shallow-equals.
submitError?: anyThe whole-form submission error returned by onSubmit under the FORM_ERROR
key.
submitErrors?: ObjectAn object containing all the current submission errors. The shape will match the shape of the form's values.
submitFailed?: booleantrue if the form was submitted, but the submission failed with submission
errors. false otherwise.
submitSucceeded?: booleantrue if the form was successfully submitted. false otherwise.
submitting?: booleantrue if the form is currently being submitted asynchronously. false
otherwise.
valid?: booleantrue 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.
validating?: booleantrue if the form is currently being validated asynchronously. false
otherwise.
values?: ObjectThe current values of the form.
FormSubscriber: (state: FormState) => voidFormSubscription: { [string]: boolean }FormSubscription is an object containing the following:
active?: booleanWhen true the FormSubscriber will be notified of changes to the active
value in FormState.
dirty?: booleanWhen true the FormSubscriber will be notified of changes to the dirty
value in FormState.
error?: booleanWhen true the FormSubscriber will be notified of changes to the error
value in FormState.
errors?: booleanWhen true the FormSubscriber will be notified of changes to the errors
value in FormState.
initialValues?: booleanWhen true the FormSubscriber will be notified of changes to the
initialValues value in FormState.
invalid?: booleanWhen true the FormSubscriber will be notified of changes to the invalid
value in FormState.
pristine?: booleanWhen true the FormSubscriber will be notified of changes to the pristine
value in FormState.
submitError?: booleanWhen true the FormSubscriber will be notified of changes to the
submitError value in FormState.
submitErrors?: booleanWhen true the FormSubscriber will be notified of changes to the
submitErrors value in FormState.
submitFailed?: booleanWhen true the FormSubscriber will be notified of changes to the
submitFailed value in FormState.
submitSucceeded?: booleanWhen true the FormSubscriber will be notified of changes to the
submitSucceeded value in FormState.
submitting?: booleanWhen true the FormSubscriber will be notified of changes to the submitting
value in FormState.
valid?: booleanWhen true the FormSubscriber will be notified of changes to the valid
value in FormState.
validating?: booleanWhen true the FormSubscriber will be notified of changes to the validating
value in FormState.
values?: booleanWhen true the FormSubscriber will be notified of changes to the values
value in FormState.
InternalFieldStateVery similar to the published FieldState.
active: booleanWhether or not the field currently has focus.
blur: () => voidA function to blur the field (mark it as inactive).
change: (value: any) => voidA function to change the value of the field.
data: ObjectA place for arbitrary values to be placed by mutators.
error?: anyThe current validation error for this field.
focus: () => voidA function to focus the field (mark it as active).
initial?: anyThe initial value of the field. undefined if it was never initialized.
name: stringThe name of the field.
pristine: booleantrue if the current value is === to the initial value, false if the values
are !===.
submitError?: anyThe submission error for this field.
touched: booleantrue if this field has ever gained and lost focus. false otherwise. Useful
for knowing when to display error messages.
valid: booleantrue if this field has no validation or submission errors. false otherwise.
value?: anyThe value of the field.
visited: booleantrue if this field has ever gained focus.
InternalFormStateVery similar to the published FormState, with a few minor
differences.
active?: stringThe name of the currently active field. undefined if none are active.
error?: anyThe whole-form error returned by a validation function under the FORM_ERROR
key.
errors: ObjectAn object containing all the current validation errors. The shape will match the shape of the form's values.
initialValues?: ObjectThe values the form was initialized with. undefined if the form was never
initialized.
pristine: booleantrue if the form values are the same as the initial values. false otherwise.
Comparison is done with shallow-equals.
submitError: anyThe whole-form submission error returned by onSubmit under the FORM_ERROR
key.
submitErrors?: ObjectAn object containing all the current submission errors. The shape will match the shape of the form's values.
submitFailed: booleantrue if the form was submitted, but the submission failed with submission
errors. false otherwise.
submitSucceeded: booleantrue if the form was successfully submitted. false otherwise.
submitting: booleantrue if the form is currently being submitted asynchronously. false
otherwise.
valid: booleantrue 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.
validating: numberThe number of asynchronous validators currently running.
values: ObjectThe current values of the form.
MutableState: { formState: InternalFormState, fields: { [string]: InternalFieldState } }A container for the InternalFormState and an object of
InternalFieldStates.
Mutator: (args: any[], state: MutableState, tools: Tools) => anyA 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, validate?: (value: ?any, allValues: Object) => ?any) => UnsubscribeToolsAn object containing:
Tools.changeValue: (state: MutableState, name: string, mutate: (value: any) => any) => voidA utility function to modify a single field value in form state. mutate()
takes the old value and returns the new value.
Tools.getIn: (state: Object, complexKey: string) => anyA utility function to get any arbitrarily deep value from an object using
dot-and-bracket syntax (e.g. some.deep.values[3].whatever).
Tools.setIn: (state: Object, key: string, value: any) => ObjectA 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.
Tools.shallowEqual: (a: any, b: any) => booleanA utility function to compare the keys of two objects. Returns true if the
objects have the same keys and the values are ===, false otherwise.
Unsubscribe : () => voidUnsubscribes a listener.
FAQs
š Framework agnostic, high performance, subscription-based form state management
The npm package final-form receives a total of 335,618 weekly downloads. As such, final-form popularity was classified as popular.
We found that final-form demonstrated a not healthy version release cadence and project activity because the last version was released a year ago.Ā It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.