react-final-form
Advanced tools
react-final-form is a framework-agnostic form state management library for React. It provides a simple and flexible way to manage form state, validation, and submission handling in React applications.
Form State Management
This feature allows you to manage the state of your form fields. The code sample demonstrates a simple form with two fields, 'firstName' and 'lastName', and a submit button. The form state is managed and displayed in real-time.
const MyForm = () => (
<Form
onSubmit={formValues => {
console.log(formValues);
}}
render={({ handleSubmit, form, submitting, pristine, values }) => (
<form onSubmit={handleSubmit}>
<div>
<label>First Name</label>
<Field name="firstName" component="input" type="text" placeholder="First Name" />
</div>
<div>
<label>Last Name</label>
<Field name="lastName" component="input" type="text" placeholder="Last Name" />
</div>
<div>
<button type="submit" disabled={submitting || pristine}>
Submit
</button>
</div>
<pre>{JSON.stringify(values, 0, 2)}</pre>
</form>
)}
/>
);Field-Level Validation
This feature allows you to add validation to individual fields. The code sample shows how to add a 'required' validation to the 'firstName' and 'lastName' fields.
const required = value => (value ? undefined : 'Required');
const MyForm = () => (
<Form
onSubmit={formValues => {
console.log(formValues);
}}
render={({ handleSubmit }) => (
<form onSubmit={handleSubmit}>
<div>
<label>First Name</label>
<Field name="firstName" component="input" type="text" placeholder="First Name" validate={required} />
</div>
<div>
<label>Last Name</label>
<Field name="lastName" component="input" type="text" placeholder="Last Name" validate={required} />
</div>
<div>
<button type="submit">
Submit
</button>
</div>
</form>
)}
/>
);Form-Level Validation
This feature allows you to add validation to the entire form. The code sample demonstrates how to validate the 'firstName' and 'lastName' fields at the form level.
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}>
<div>
<label>First Name</label>
<Field name="firstName" component="input" type="text" placeholder="First Name" />
</div>
<div>
<label>Last Name</label>
<Field name="lastName" component="input" type="text" placeholder="Last Name" />
</div>
<div>
<button type="submit">
Submit
</button>
</div>
</form>
)}
/>
);Formik is a popular form library for React that provides a higher-level API for managing form state, validation, and submission. It is similar to react-final-form but offers more built-in hooks and components for easier integration.
React Hook Form is a performant, flexible, and extensible form library for React. It uses hooks to manage form state and validation, making it a lightweight alternative to react-final-form with a focus on performance.
Redux Form is a form state management library that integrates with Redux. It is similar to react-final-form but is more tightly coupled with Redux, making it suitable for applications that already use Redux for state management.
ā Zero dependencies
ā Only peer dependencies: React and š Final Form
ā Opt-in subscriptions - only update on the state you need!
ā š„ 2.09k gzipped š„
npm install --save react-final-form final-form
or
yarn add react-final-form final-form
š React Final Form is a thin React wrapper for š Final Form, which is a subscriptions-based form state management library that uses the Observer pattern, so only the components that need updating are re-rendered as the form's state changes. By default, š React Final Form subscribes to all changes, but if you want to fine tune your form to optimized blazing-fast perfection, you may specify only the form state that you care about for rendering your gorgeous UI.
You can think of it a little like GraphQL's feature of only fetching the data your component needs to render, and nothing else.
Here's what it looks like in your code:
import { Form, Field } from 'react-final-form'
const MyForm = () =>
<Form
onSubmit={onSubmit}
validate={validate}
render={({ handleSubmit, pristine, invalid }) =>
<form onSubmit={handleSubmit}>
<h2>Simple Default Input</h2>
<div>
<label>First Name</label>
<Field name="firstName" component="input" placeholder="First Name"/>
</div>
<h2>An Arbitrary Reusable Input Component</h2>
<div>
<label>Interests</label>
<Field name="interests" component={InterestPicker}/>
</div>
<h2>Render Function</h2>
<Field name="bio" render={({ input, meta }) =>
<div>
<label>Bio</label>
<textarea {...input}/>
{meta.touched && meta.error && <span>{meta.error}</span>}
</div>
}>
<h2>Render Function as Children</h2>
<Field name="phone">
{({ input, meta }) =>
<div>
<label>Phone</label>
<input type="text" {...input} placeholder="Phone"/>
{meta.touched && meta.error && <span>{meta.error}</span>}
</div>
}
</Field>
<button type="submit" disabled={pristine || invalid}>Submit</button>
</form>
}
/>
FieldProps
FieldRenderProps
input.name: stringinput.onBlur: (?SyntheticFocusEvent<*>) => voidinput.onChange: (SyntheticInputEvent<*> | any) => voidinput.onFocus: (?SyntheticFocusEvent<*>) => voidinput.value: anymeta.active?: booleanmeta.dirty?: booleanmeta.error?: anymeta.initial?: anymeta.invalid?: booleanmeta.pristine?: booleanmeta.submitError?: anymeta.submitFailed?: booleanmeta.submitSucceeded?: booleanmeta.touched?: booleanmeta.valid?: booleanmeta.visited?: booleanFormProps
children?: (props: FormRenderProps) => React.Nodecomponent?: React.ComponentType<FormRenderProps>debug?: (state: FormState, fieldStates: { [string]: FieldState }) => voidinitialValues?: ObjectonSubmit: (values: Object, callback: ?(errors: ?Object) => void) => ?Object | Promise<?Object>render?: (props: FormRenderProps) => React.Nodesubscription?: FormSubscriptionvalidate?: (values: Object) => void) => Object | Promise<Object>validateOnBlur?: booleanFormRenderProps
Uses the built-in React inputs: input, select, and textarea to build a
form with no validation.
Introduces a whole-record validation function and demonstrates how to display errors next to fields using child render functions.
Introduces field-level validation functions and demonstrates how to display errors next to fields using child render functions.
Demonstrates how field-level validation rules may be asynchronous (return a
Promise), as well as how to show a "validating" spinner during the lifetime of
the Promise.
Demonstrates how you can mix synchronous and asynchronous validation patterns at
the record-level, by returning errors synchronously, and falling back to an
asynchronous call (by returning a Promise) if sync validation is passing.
This example demonstrates how to return submission errors from failed submits.
Notice that the Promise should resolve to the submission error (not reject).
Rejection is reserved for communications or server exceptions.
There are three ways to tell <Form/> and <Field/> what to render:
| Method | How it is rendered |
|---|---|
component prop | return React.createElement(this.props.component, props) |
render prop | return this.props.render(props) |
a render function as children | return this.props.children(props) |
The following can be imported from final-form.
Form : React.ComponentType<FormProps>A component that takes FormProps.
Field : React.ComponentType<FieldProps>A component that takes FieldProps.
FieldPropsThese are props that you pass to
<Field/>. You must provide one of the
ways to render: component, render, or children.
allowNull?: booleanBy default, if your value is null, <Field/> will convert it to '', to
ensure
controlled inputs.
But if you pass true to allowNull, <Field/> will give you a null value.
Defaults to false.
children?: (props: FieldRenderProps) => React.NodeA render function that is given FieldRenderProps, as well
as any non-API props passed into the <Field/> component.
component?: React.ComponentType<FieldRenderProps>A component that is given FieldRenderProps as props, as
well as any non-API props passed into the <Field/> component.
name: stringThe name of your field.
render?: (props: FieldRenderProps) => React.NodeA render function that is given FieldRenderProps, as well
as any non-API props passed into the <Field/> component.
subscription?: FieldSubscriptionA
FieldSubscription
that selects of all the items of
FieldState that you wish
to update for. If you don't pass a subscription prop, it defaults to all of
FieldState.
validate?: (value: ?any, allValues: Object) => ?anyA function that takes the field value, and all the values of the form and
returns an error if the value is invalid, or undefined if the value is valid.
value?: anyThis is only used for radio buttons! The value of the radio button. The
radio button will render as checked if and only if the value given here ===
the value for the field in the form.
FieldRenderPropsThese are the props that <Field/>
provides to your render function or component. This object separates out the
values and event handlers intended to be given to the input component from the
meta data about the field. The input can be destructured directly into an
<input/> like so: <input {...props.input}/>. Keep in mind that the values
in meta are dependent on you having subscribed to them with the
subscription prop
input.name: stringThe name of the field.
input.onBlur: (?SyntheticFocusEvent<*>) => voidThe onBlur function can take a SyntheticFocusEvent like it would if you had
given it directly to an <input/> component, but you can also just call it:
props.input.onBlur() to mark the field as blurred (inactive).
input.onChange: (SyntheticInputEvent<*> | any) => voidThe onChange function can take a SyntheticInputEvent like it would if you
had given it directly to an <input/> component (in which case it will read the
value out of event.target.value), but you can also just call it:
props.input.onChange(value) to update the value of the field.
input.onFocus: (?SyntheticFocusEvent<*>) => voidThe onFocus function can take a SyntheticFocusEvent like it would if you had
given it directly to an <input/> component, but you can also just call it:
props.input.onFocus() to mark the field as focused (active).
input.value: anyThe current value of the field.
meta.active?: booleanSee the š Final Form docs on active.
meta.dirty?: booleanSee the š Final Form docs on dirty.
meta.error?: anySee the š Final Form docs on error.
meta.initial?: anySee the š Final Form docs on initial.
meta.invalid?: booleanSee the š Final Form docs on invalid.
meta.pristine?: booleanSee the š Final Form docs on pristine.
meta.submitError?: anySee the š Final Form docs on submitError.
meta.submitFailed?: booleanSee the š Final Form docs on submitFailed.
meta.submitSucceeded?: booleanSee the š Final Form docs on submitSucceeded.
meta.touched?: booleanSee the š Final Form docs on touched.
meta.valid?: booleanSee the š Final Form docs on valid.
meta.visited?: booleanSee the š Final Form docs on visited.
FormPropsThese are the props that you pass to
<Form/>. You must provide one of the
ways to render: component, render, or children.
children?: (props: FormRenderProps) => React.NodeA render function that is given FormRenderProps, as well
as any non-API props passed into the <Form/> component.
component?: React.ComponentType<FormRenderProps>A component that is given FormRenderProps as props, as
well as any non-API props passed into the <Form/> component.
debug?: (state: FormState, fieldStates: { [string]: FieldState }) => voidSee the š Final Form docs on debug.
initialValues?: ObjectSee the š Final Form docs on initialValues.
onSubmit: (values: Object, callback: ?(errors: ?Object) => void) => ?Object | Promise<?Object>See the š Final Form docs on onSubmit.
render?: (props: FormRenderProps) => React.NodeA render function that is given FormRenderProps, as well
as any non-API props passed into the <Form/> component.
subscription?: FormSubscriptionA
FormSubscription
that selects of all the items of
FormState that you wish to
update for. If you don't pass a subscription prop, it defaults to all of
FormState.
validate?: (values: Object) => void) => Object | Promise<Object>See the š Final Form docs on validate.
validateOnBlur?: booleanSee the š Final Form docs on validateOnBlur.
FormRenderPropsThese are the props that <Form/>
provides to your render function or component. Keep in mind that the values you
receive here are dependent upon which values of
FormState you have
subscribed to with the
subscription prop.
This object contains everything in
š Final Form's FormState
as well as:
batch: (() => void) => voidA function that allows batch updates to be done to the form state.
See the š Final Form docs on batch.
blur: (name: string) => voidA function to blur (mark inactive) any field.
change: (name: string, value: any) => voidA function to change the value of any field.
focus: (name: string) => voidA function to focus (mark active) any field.
handleSubmit: (SyntheticEvent<HTMLFormElement>) => voidA function intended for you to give directly to the <form> tag: <form onSubmit={handleSubmit}/>.
FAQs
š High performance subscription-based form state management for React
The npm package react-final-form receives a total of 206,883 weekly downloads. As such, react-final-form popularity was classified as popular.
We found that react-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
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.