react-final-form-arrays
    TypeScript icon, indicating that this package has built-in type declarations

    3.1.3 • Public • Published

    💰 Wanna get paid the big bucks writing React? Take this quiz and get offers from top tech companies! 💰


    🏁 React Final Form Arrays

    NPM Version NPM Downloads Build Status codecov.io styled with prettier


    Installation

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

    or

    yarn add react-final-form-arrays react-final-form final-form final-form-arrays

    Usage

    🏁 React Final Form Arrays provides a way to render arrays in 🏁 React Final Form.

    import { Form, Field } from 'react-final-form'
    import arrayMutators from 'final-form-arrays'
    import { FieldArray } from 'react-final-form-arrays'
     
    const MyForm = () => (
      <Form
        onSubmit={onSubmit}
        mutators={{
          // potentially other mutators could be merged here
          ...arrayMutators
        }}
        validate={validate}
        render={({ handleSubmit, pristine, invalid }) => (
          <form onSubmit={handleSubmit}>
            <FieldArray name="customers">
              {({ fields }) => (
                <div>
                  {fields.map((name, index) => (
                    <div key={name}>
                      <div>
                        <label>First Name</label>
                        <Field name={`${name}.firstName`} component="input" />
                      </div>
                      <div>
                        <label>Last Name</label>
                        <Field name={`${name}.lastName`} component="input" />
                      </div>
                      <button type="button" onClick={() => fields.remove(index)}>
                        Remove
                      </button>
                    </div>
                  ))}
                  <button
                    type="button"
                    onClick={() => fields.push({ firstName: '', lastName: '' })}
                  >
                    Add
                  </button>
                </div>
              )}
            </FieldArray>
          </form>
        )}
      />
    )

    Table of Contents

    Examples

    Simple Example

    Demostrates how to use <FieldArray/> to render an array of inputs, as well as use push, pop, and remove mutations.

    React Beautiful DnD Example

    Demostrates how to integrate the simple example with react-beautiful-dnd

    Rendering

    There are three ways to tell <FieldArray/> 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)

    API

    The following can be imported from react-final-form-arrays.

    FieldArray : React.ComponentType<FieldArrayProps>

    A component that takes FieldArrayProps and renders an array of fields

    useFieldArray

    The useFieldArray hook takes two parameters, the first is the name of the field, and the second is an optional object that looks just like FieldArrayProps, except without the name. It returns an object just like FieldArrayRenderProps.

    useFieldArray is used interally inside FieldArray.

    version: string

    The current used version of 🏁 React Final Form Arrays.


    Types

    FieldArrayProps

    These are props that you pass to <FieldArray/>. You must provide one of the ways to render: component, render, or children.

    children?: ((props: FieldArrayRenderProps) => React.Node) | React.Node

    A render function that is given FieldArrayRenderProps, as well as any non-API props passed into the <FieldArray/> component.

    component?: React.ComponentType<FieldArrayRenderProps>

    A component that is given FieldArrayRenderProps as props, as well as any non-API props passed into the <FieldArray/> component.

    name: string

    The name of your field array.

    render?: (props: FieldArrayRenderProps) => React.Node

    A render function that is given FieldArrayRenderProps, as well as any non-API props passed into the <FieldArray/> component.

    defaultValue?: any

    ⚠️ You probably want initialValue! ⚠️

    Before using this prop, read and understand the 🏁 Final Form documentation on initialValue and defaultValue!

    initialValue?: any

    See the 🏁 Final Form docs on initialValue

    isEqual?: (allPreviousValues: Array<any>, allNewValues: Array<any>) => boolean

    A function that can be used to compare two arrays of values (before and after every change) and calculate pristine/dirty checks. Defaults to a function that will === check each element of the array.

    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.

    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 array value is invalid, or undefined if the value is valid.

    FieldArrayRenderProps

    These are the props that <FieldArray/> provides to your render function or component. This object is divided into a fields object that mimics an iterable (e.g. it has map() and forEach() and length), and meta data about the field array. Keep in mind that the values in meta are dependent on you having subscribed to them with the subscription prop

    fields.forEach: (iterator: (name: string, index: number) => void) => void

    Iterates through all of the names of the fields in the field array in bracket format, e.g. foo[0], foo[1], foo[2].

    fields.insert: (index: number, value: any) => void

    A function to insert a value into any arbitrary index of the array.

    fields.map: (iterator: (name: string, index: number) => any) => any[]

    Iterates through all of the names of the fields in the field array in bracket format, e.g. foo[0], foo[1], foo[2], and collects the results of the iterator function. You will use this in almost every implementation.

    fields.move: (from: number, to: number) => void

    A function to move a value from one index to another. Useful for drag-and-drop reordering.

    fields.name: string

    The name of the field array.

    fields.pop: () => any

    A function to remove a value from the end of the array. The value will be returned.

    fields.push: (value: any) => void

    A function to add a value to the end of the array.

    fields.remove: (index: number) => any

    A function to remove a value from an arbitrary index of the array.

    fields.shift: () => any

    A function to remove a value from the beginning of the array. The value will be returned.

    fields.swap: (indexA: number, indexB: number) => void

    A function to swap two values in the array.

    fields.update: (index: number, value: any) => void

    Updates a value of the specified index of the array field.

    fields.unshift: (value: any) => void

    A function to add a value to the beginning of the array.

    fields.value: any[]

    The value of the array. Should be treated as readonly.

    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.

    Keywords

    none

    Install

    npm i react-final-form-arrays

    DownloadsWeekly Downloads

    184,499

    Version

    3.1.3

    License

    MIT

    Unpacked Size

    67.1 kB

    Total Files

    14

    Last publish

    Collaborators

    • erikras