Migration to v2

Version 2.0.0 focuses on adding robust hooks support as well as streamlining the public API towards simplicity and consistency. It also adds first class TypeScript support!

#Key Features

• New hooks for custom fields and common use-cases makes accessing Form data significantly easier
  • useFormValue
  • useField
  • useFieldArray
  • useFormSubmit
  • useErrors
  • useTouched
• Out-of-the-box support for <select multiple> as well as checkbox groups
• Better FieldArray validation behavior; arrayHelpers only trigger validation on the list itself, not nested fields
• Library is now written in TypeScript.

#Breaking Changes

There is lot of rewritten code, so there may be subtle changes that I've missed. Please test in your apps thoroughly.

#Package exports have been rearranged

Previously, most library components and utils were exported as static properties of the <Form> component as well as being named exports from the package. For ESM consumers the default export is the <Form> component and the <Field>, <FieldArray>, <Message>, <Submit>, and <Summary> components are still static properties of Form:

import Form from 'react-formal';
<Form>
  <Form.Field />
</Form>;

Every thing else is exported as a named export including an object called formStatics which is all the static properties on Form.

import { useField, setter, toFormErrors } from 'react-formal';

For CommonJS consumers the import is the Form component with all other exports as static properties.

#Field render prop arguments

Instead of passing a single props argument and the resolved Input, Field and FieldArrays now pass props and meta as seperate arguments. The resolved input has been removed entirely as it was unnecessary for custom components. For details about how fields resolve to native elements field meta now contains nativeTagName and nativeType

<Form.Field name="birthDate">
  {(props, meta) => <DatePicker {...props} />}
</Form.Field>

For very custom Field components consider useField and friends.

#Change: events -> validateOn

The validation events prop has been changed to validateOn and limited to only change and blur. Arbitrary events cannot be configured any longer. To support other sorts of event handlers use the Field render prop.

<Field>
  {({ onBlur, ...pros }) => <MyInput onValidate={onBlur} {...props} />}
</Field>

#Field's always inject onChange

Previously Fields would only inject handlers for their configured events. This meant that when set to null a Field could not trigger updates. This has been fixed, so events (now validateOn) now refer exclusively to handlers that trigger validation and onChange is always injected, even when events is null.

Note that onChange can still trigger validation, e.g. validateOn="change" will inject an onChange handler that triggers an update as well as validation, validateOn={null} will still inject onChange but it will only trigger an update to the field value, not validation.

#FieldArray render prop arguments

<FieldArray> have switched to be entirely non-presentational components. Meaning, they no longer accept an as prop or element children. It's generally recommended that FieldArray be used to compose other Fields via the render prop (but not required).

For uses existing renderProp usage the arguments are now:

<Form.FieldArray>
  {(values, arrayHelpers, meta) => ... }
</Form.FieldArray>

useFieldArray is also now available as an alternative to render props.

#Migrating FieldArray Components

This is likely an uncommon pattern, but Field Arrays like the following:

<Form.FieldArray as={MyListComponent} />

Will no longer work, instead switch to the render prop and pass the helpers and values in as props to your component, or take ad avantage of useFieldArray in MyListComponent.

<Form.FieldArray>
  {(values, arrayHelpers, meta) => (
    <MyListComponent values={values} helpers={arrayHelpers} meta={meta} />
  )}
</Form.FieldArray>

#FieldArray validation

Previously, <FieldArray>s would trigger validation the same as <Field>s, validating the entire branch below their name. Now validation is only triggered for the list itself. Practically this means that it's no longer required to set events={null} on FieldArrays as a well of disabling top level validation.