🏁 React Final Form

✅ Zero dependencies

✅ Only peer dependencies: React and 🏁 Final Form

✅ Opt-in subscriptions - only update on the state you need!

✅ 💥 1.81k gzipped 💥

Installation

npm install --save react-final-form final-form

or

yarn add react-final-form final-form

Getting Started

🏁 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>
    }
  />

Table of Contents

• Rendering
• API
  • Form : React.ComponentType<FormProps>
  • Field : React.ComponentType<FieldProps>
• Types
  • FieldProps
    • allowNull?: boolean
    • children?: (props: FieldRenderProps) => React.Node
    • component?: React.ComponentType<FieldRenderProps>
    • name: string
    • render?: (props: FieldRenderProps) => React.Node
    • subscription?: FieldSubscription
  • FieldRenderProps
    • input.name: string
    • input.onBlur: (?SyntheticFocusEvent<*>) => void
    • input.onChange: (SyntheticInputEvent<*> | any) => void
    • input.onFocus: (?SyntheticFocusEvent<*>) => void
    • input.value: any
    • meta.active?: boolean
    • 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
    • component?: React.ComponentType<FormRenderProps>
    • debug?: (state: FormState, fieldStates: { [string]: FieldState }) => void
    • initialValues?: Object
    • onSubmit: (values: Object, callback: ?(errors: ?Object) => void) => ?Object | Promise<?Object>
    • render?: (props: FormRenderProps) => React.Node
    • subscription?: FormSubscription
    • validate?: (values: Object, callback: ?(errors: Object) => void) => Object | void
  • FormRenderProps
    • handleSubmit: (SyntheticEvent<HTMLFormElement>) => void

Rendering

There are three ways to tell <Form/> and <Field/> what to render:

API

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.

Types

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

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.

name: string

The name of your field.

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

FieldRenderProps

These are the props that <Field/> provides to your render function or component. This object separates out the values and callbacks 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.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

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?: (state: FormState, fieldStates: { [string]: FieldState }) => void

See the 🏁 Final Form docs on debug.

initialValues?: Object

See 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.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 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, callback: ?(errors: Object) => void) => Object | void

See the 🏁 Final Form docs on validate.

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:

handleSubmit: (SyntheticEvent<HTMLFormElement>) => void

A function intended for you to give directly to the <form> tag: <form onSubmit={handleSubmit}/>.