Security News
Cloudflare Adds Security.txt Setup Wizard
Cloudflare has launched a setup wizard allowing users to easily create and manage a security.txt file for vulnerability disclosure on their websites.
react-final-form
Advanced tools
π High performance subscription-based form state management for React
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.7k 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
allowNull?: boolean
children?: ((props: FieldRenderProps) => React.Node) | React.Node
component?: React.ComponentType<FieldRenderProps>
format?: ((value: any, name: string) => any) | null
isEqual?: (a: any, b: any) => boolean
name: string
parse?: ((value: any, name: string) => any) | null
render?: (props: FieldRenderProps) => React.Node
subscription?: FieldSubscription
validate?: (value: ?any, allValues: Object) => ?any
validateFields?: string[]
value?: any
FieldRenderProps
input.name: string
input.onBlur: (?SyntheticFocusEvent<*>) => void
input.onChange: (SyntheticInputEvent<*> | any) => void
input.onFocus: (?SyntheticFocusEvent<*>) => void
input.value: any
meta.active?: boolean
meta.data: Object
meta.dirty?: boolean
meta.error?: any
meta.initial?: any
meta.invalid?: boolean
meta.pristine?: boolean
meta.submitError?: any
meta.submitFailed?: boolean
meta.submitSucceeded?: boolean
meta.touched?: boolean
meta.valid?: boolean
meta.visited?: boolean
FormProps
children?: ((props: FormRenderProps) => React.Node) | React.Node
component?: React.ComponentType<FormRenderProps>
debug?: DebugFunction
decorators?: Decorator[]
initialValues?: Object
mutators?: { [string]: Mutator }
onSubmit: (values: Object, form: FormApi, callback: ?(errors: ?Object) => void) => ?Object | Promise<?Object> | void
render?: (props: FormRenderProps) => React.Node
subscription?: FormSubscription
validate?: (values: Object) => Object | Promise<Object>
validateOnBlur?: boolean
FormRenderProps
FormSpyProps
FormSpyRenderProps
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.
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.
Demonstrates how easy it is to use third party input components. All the third
party component really needs is value
and onChange
, but more complex
components can accept things like errors.
Demonstrates how, by restricting which parts of form state the form component
needs to render, it reduce the number of times the whole form has to rerender.
Yet, if some part of form state is needed inside of it, the
FormSpy
component can be used to
attain it.
Demonstrates how to make an independent Error component to subscribe to and display the error for any form field.
Demonstrates how a form can be initialized, after fetching data, by passing in
initialValues
as a prop.
Demostrates how to use the <FieldArray/>
component, from
react-final-form-arrays
,
to render an array of inputs, as well as use push
, pop
, and remove
mutations.
Demonstrates how to use the
final-form-calculate
decorator to achieve realtime field calculations through easily defined rules.
Demonstrates how the power of subscriptions and mutators can be used to build a warning engine: logic to display a message next to each field that is not an error that prevents form submission.
Demonstrates how fields can be grouped into reusable components.
Demonstrates how you can use document.getElementById()
or a closure to trigger
a submit from outside of the form. For more information, see
How can I trigger a submit from outside the form?
Demonstrates how to use π React Final Form to create a multi-page "wizard" form, with validation on each page.
Demonstrates how to use π React Final Form's parse
and format
props to control exactly how the data flows from the form state through the input and back to the form state. Notice that you can use parse
to "normalize" your values.
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 react-final-form
.
Field : React.ComponentType<FieldProps>
A component that takes FieldProps
and renders an individual
field.
Form : React.ComponentType<FormProps>
A component that takes FormProps
and surrounds your entire form.
FormSpy : React.ComponentType<FormSpyProps>
A component that takes FormSpyProps
and can listen to form
state from inside an optimized <Form/>
.
version: string
The current used version of π React Final Form.
FieldProps
These are props that you pass to
<Field/>
. You must provide one of the
ways to render: component
, render
, or children
.
allowNull?: boolean
By 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.Node) | React.Node
A 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.
format?: ((value: any, name: string) => any) | null
A function that takes the value from the form values and the name of the field and formats the value to give to the input. Common use cases include converting javascript Date
values into a localized date string. Almost always used in conjunction with parse
.
Note: If you pass null
to format
, it will override the default behavior of converting undefined
into ''
. If you do this, making sure your inputs are "controlled" is up to you.
isEqual?: (a: any, b: any) => boolean
See the π Final Form docs on isEqual
.
name: string
The name of your field.
parse?: ((value: any, name: string) => any) | null
A function that takes the value from the input and name of the field and converts the value into the value you want stored as this field's value in the form. Common usecases include converting strings into Number
s or parsing localized dates into actual javascript Date
objects. Almost always used in conjuction with format
.
Note: If you pass null
to parse
, it will override the default behavior of converting ''
into undefined
, thus allowing you to have form values of ''
.
render?: (props: FieldRenderProps) => React.Node
A render function that is given FieldRenderProps
, as well
as any non-API props passed into the <Field/>
component.
subscription?: FieldSubscription
A
FieldSubscription
that selects all of 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) => ?any
A 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.
validateFields?: string[]
See the π Final Form docs on validateFields
.
value?: any
This 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.
FieldRenderProps
These 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: string
The name of the field.
input.onBlur: (?SyntheticFocusEvent<*>) => void
The 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) => void
The 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<*>) => void
The 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: any
The current value of the field.
meta.active?: boolean
See the π Final Form docs on active
.
meta.data: Object
See the π Final Form docs on data
.
meta.dirty?: boolean
See the π Final Form docs on dirty
.
meta.error?: any
See the π Final Form docs on error
.
meta.initial?: any
See the π Final Form docs on initial
.
meta.invalid?: boolean
See the π Final Form docs on invalid
.
meta.pristine?: boolean
See the π Final Form docs on pristine
.
meta.submitError?: any
See the π Final Form docs on submitError
.
meta.submitFailed?: boolean
See the π Final Form docs on submitFailed
.
meta.submitSucceeded?: boolean
See the π Final Form docs on submitSucceeded
.
meta.touched?: boolean
See the π Final Form docs on touched
.
meta.valid?: boolean
See the π Final Form docs on valid
.
meta.visited?: boolean
See the π Final Form docs on visited
.
FormProps
These 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.Node) | React.Node
A 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?: DebugFunction
See the π Final Form docs on debug
.
decorators?: Decorator[]
Decorator
s
to apply to the form.
initialValues?: Object
See the π Final Form docs on initialValues
.
mutators?: { [string]: Mutator }
See the π Final Form docs on mutators
.
onSubmit: (values: Object, form: FormApi, callback: ?(errors: ?Object) => void) => ?Object | Promise<?Object> | void
See the π Final Form docs on onSubmit
.
render?: (props: FormRenderProps) => React.Node
A render function that is given FormRenderProps
, as well
as any non-API props passed into the <Form/>
component.
subscription?: FormSubscription
A
FormSubscription
that selects all of 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) => Object | Promise<Object>
See the π Final Form docs on validate
.
validateOnBlur?: boolean
See the π Final Form docs on validateOnBlur
.
FormRenderProps
These 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: (fn: () => void) => void)
A function that allows batch updates to be done to the form state.
See the π Final Form docs on batch
.
blur: (name: string) => void
A function to blur (mark inactive) any field.
change: (name: string, value: any) => void
A function to change the value of any field.
focus: (name: string) => void
A function to focus (mark active) any field.
handleSubmit: (SyntheticEvent<HTMLFormElement>) => void
A function intended for you to give directly to the <form>
tag: <form onSubmit={handleSubmit}/>
.
initialize: (values: Object) => void
A function that initializes the form values.
See the π Final Form docs on initialize
.
mutators?: { [string]: Function }
See the π Final Form docs on mutators
.
reset: () => void
A function that resets the form values to their last initialized values.
See the π Final Form docs on reset
.
FormSpyProps
These are the props that you pass to
<FormSpy/>
. You must provide one
of the ways to render: component
, render
, or children
.
children?: ((props: FormSpyRenderProps) => React.Node) | React.Node
A render function that is given FormSpyRenderProps
, as
well as any non-API props passed into the <FormSpy/>
component. Will not be
called if an onChange
prop is provided.
component?: React.ComponentType<FormSpyRenderProps>
A component that is given FormSpyRenderProps
as props,
as well as any non-API props passed into the <FormSpy/>
component. Will not be
called if an onChange
prop is provided.
onChange?: (formState: FormState) => void
A change listener that will be called with form state whenever the form state,
as subscribed to by the subscription
prop, has changed. When an onChange
prop is provided, the <FormSpy/>
will not render anything.
render?: (props: FormSpyRenderProps) => React.Node
A render function that is given FormSpyRenderProps
, as
well as any non-API props passed into the <FormSpy/>
component. Will not be
called if an onChange
prop is provided.
subscription?: FormSubscription
A
FormSubscription
that selects all of the items of
FormState
that you wish
to update for. If you don't pass a subscription
prop, it defaults to all of
FormState
.
FormSpyRenderProps
These are the props that
<FormSpy/>
provides to your render
function or component. These props are of type
FormState
. Keep in mind
that the values you receive here are dependent upon which values of
FormState
you have
subscribed to with the
subscription
prop.
FAQs
π High performance subscription-based form state management for React
The npm package react-final-form receives a total of 338,629 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
Cloudflare has launched a setup wizard allowing users to easily create and manage a security.txt file for vulnerability disclosure on their websites.
Security News
The Socket Research team breaks down a malicious npm package targeting the legitimate DOMPurify library. It uses obfuscated code to hide that it is exfiltrating browser and crypto wallet data.
Security News
ENISAβs 2024 report highlights the EUβs top cybersecurity threats, including rising DDoS attacks, ransomware, supply chain vulnerabilities, and weaponized AI.