
[Five years ago](/blog/final-form-announcement), I challenged myself to create a
form state management library that was framework independent. In 2017, the idea
that maybe React wasn't the best place to manage application state was not
nearly as common as it has become. Formik had just been released and took all of
the form library NPM downloads for the following few years. Formik went _all-in_
on React for state management. The current King of Forms in React is
[React Hook Form](https://react-hook-form.com), again, betting all the marbles
on React's state management prowess.

From the very beginning of Final Form, it was designed to outlive existing
popular frontend frameworks. Form state is two things:

1. more complicated than you think
2. not inherently related to any frontend framework

When our great grandkids are filling out their applications for Space Academy,
they are going to be entering data, be it with a keyboard or a neural implant,
into a form field that is going to have some validation rules on it, and the UX
is gonna _SUCK_ because the engineers at Space Academy didn't spend enough
effort making the form entry experience good.

Just because the form is rendered in the then-popular `Neural4D-VR.js` UI
framework, the flow of the form data will be just like it is now.

> Form State is framework independent.

## Solid JS

I've been hearing rumors of this new React competitor getting more and more
popular. I'd glanced at it a few times, but at a recent conference, I got to
meet the creator, and generally sense the wind of interest headed in its
direction.

The "no virtual DOM" and "reactivity" claims are incredibly intriguing.

[insert React is not
[reactive](https://en.wikipedia.org/wiki/Reactive_programming) joke here]

What really put me over the edge to attempt what I'm about to present to you is
realizing that Solid lets you tack on "directives" to your JSX, which are little
functions that get to manipulate the DOM directly, a benefit of not having a
virtual DOM. This could make a very interesting way to connect inputs to a form
management library.

Especially if there were a form state management library that were framework
agnostic... 🤔

## Proof of Concept

What I'm about to show you is an example of what a Solid Final Form library
_might_ look like. It calls `useForm()` to create a form instance and expose its
API. Potentially all form state could be exposed via Solid's
[signals](https://www.solidjs.com/docs/latest/api#createsignal). From the docs:

> Signals are the most basic reactive primitive. They track a single value
> (which can be any JavaScript object) that changes over time.

In this proof of concept, I have only exposed `values` and `isSubmitting`, but
Final Form has a
[veritable plethora](https://final-form.org/docs/final-form/types/FormState) of
other form state it manages.

`useForm()` also gives us two
[directives](https://www.solidjs.com/docs/latest/api#use___), `field` and
`error`. To connect an input (i.e. attach blur, change, and focus listeners) to
Final Form, we:

1. Throw a `use:field` directly on the `<input/>`
2. There is no step 2, you're done already!
3. How fun are `<li>` gags?

The `field` directive reads the `name` prop on the `input` and knows what field
it is.

To show errors, we don't have a `name` prop, so we have to tell the `error`
directive with:

```jsx
<span use:error="firstName" />
```

Here's the full form component:

```tsx
export const App: Component = () => {
  // Create Form
  const { error, field, handleSubmit, isSubmitting, values } = useForm(
    onSubmit,
    initialValues,
    validate
  );
  // Calculated Signal
  const formattedValues = () => JSON.stringify(values(), undefined, 2);
  return (
    <form onSubmit={handleSubmit}>
      <h1>Solid Final Form 🏁</h1>
      <label>
        <input name="firstName" placeholder="First Name" use:field />
        <span use:error="firstName" />
      </label>
      <label>
        <input name="lastName" placeholder="Last Name" use:field />
        <span use:error="lastName" />
      </label>
      <label>
        <select name="favoriteColor" use:field>
          <option value="">Choose a color</option>
          <option value="#FF0000">Red</option>
          <option value="#00FF00">Green</option>
          <option value="#0000FF">Blue</option>
        </select>
        <span use:error="favoriteColor" />
      </label>
      <button type="submit" disabled={isSubmitting()}>
        Submit
      </button>
      <pre>{formattedValues()}</pre>
    </form>
  );
};
```

In this
[100-line proof of concept](https://codesandbox.io/s/agitated-maxwell-7jpnxw?file=/src/useForm.tsx),
what are the features we're getting?

- Realtime client side validation (as you fix errors, they go away)
- Tracking if a field is "touched" (focused and then blurred) to only show the
  error if a user has visited the field _or attempted to submit the form_
- Blocking submission when there are validation errors
- A signal to tell us if the form is being submitted
- None of that "Is the whole form rerendering? Waaahhh!! 😭🍼" nonsense that
  React gives us
- Render props? What are those??
- A robust battle-tested framework (300k weekly downloads) for managing our form
  state

## Sandbox

<iframe
  src="https://codesandbox.io/embed/solid-final-form-7jpnxw?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: 500,
    border: 0,
    borderRadius: 4,
    overflow: "hidden",
  }}
  title="Solid Final Form"
  allow="accelerometer; ambient-light-sensor; camera;
encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb;
vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups
allow-presentation allow-same-origin allow-scripts"
></iframe>

## Future

At the time of writing, this is just a fun Saturday morning fun project. I don't
really feel like I have the bandwidth right now to pursue maintaining another
open source library, but I'd be happy to work closely with anyone who would like
to take this and run with it. You can find me
[on Twitter](https://twitter.com/intent/follow?screen_name=erikras).


Solid Final Form – Proof of Concept


It was _so_ nice to go back to an in-person conference! The
[Infobip Shift](https://shift.infobip.com) conference organizers did an amazing
job of making it as safe as possible. Everyone entering the conference venue was
required to show a European COVID vaccination certificate (which I have), or a
negative test from that morning. Then, once inside... _WE COULD REMOVE OUR
MASKS_!!! I've never been so happy to see so many noses and mouths!

It was also great to finally meet in person some folks I've known online for
years, like [Shawn Wang](https://twitter.com/swyx),
[Nader Dabit](https://twitter.com/dabit3),
[Ives van Hoorne](https://twitter.com/CompuIves), and
[Kent C. Dodds](https://twitter.com/kentcdodds). And it was also great to hang
out with some other folks whom I already consider friends, like
[David 🎹](https://twitter.com/DavidKPiano),
[Tomasz Łakomy](https://twitter.com/tlakomy), and
[Kitze](https://twitter.com/thekitze), as well meeting many new friends that I
hope to see again. I'd like to say a special _obrigada_ to
[Atila Fassina](https://twitter.com/atilafassina); we were complete strangers
when we met up at the hotel lobby, but we decided to spend a day together
walking around the historical district of Zadar. We had a great time, talking
not about tech, but about being expat fathers.

The venue for this particular talk was pretty wild. It was in a
[UFO-shaped basketball stadium](https://www.youtube.com/watch?v=yWqQoovu93M),
where I was in the center of the circle, and the audience was all around me at
360º. Because I'm such a big fan of live coding talks, both seeing and giving, I
was a little restricted in the time where I could be facing those behind me, but
I did my best.

## The Talk

<video>0bY9_DasGEg</video>

<caption>
  The slides can be found{" "}
  <a
    href="https://speakerdeck.com/erikras/youre-a-wizard-form-harry"
    target="_blank"
  >
    here
  </a>
  , and the code <a
    href="https://github.com/erikras/potionocean"
    target="_blank"
  >
    here
  </a>, if you so desire.
</caption>

## Photos

<p>
<img
  src="/images/infobip-shift-2021-1.jpg"
  alt="Pre-talk Selfie"
  width={4032}
  height={3024}
/>

<caption>Obligatory Pre-talk Selfie</caption>
</p>

<p>
<img
  src="/images/infobip-shift-2021-2.jpg"
  alt="Front Row Groupies"
  width={4032}
  height={3024}
/>

<caption>
  My front-row groupies: <a href="https://twitter.com/tlakomy">Tomasz Łakomy</a>, <a href="https://twitter.com/jen_ayy_">Jenny Truong</a>, <a href="https://twitter.com/jacobmparis">Jacob Paris</a>, <a href="https://twitter.com/DavidKPiano">David 🎹</a>, and <a href="https://twitter.com/kentcdodds">Kent C. Dodds</a>.
</caption>
</p>

<p>
<img
  src="/images/infobip-shift-2021-3.jpg"
  alt="360º Crowd"
  width={4032}
  height={3024}
/>

<caption>
  360º Crowd. Photo by <a href="https://twitter.com/swyx">Shawn Wang</a>.
</caption>
</p>

<p>
<img
  src="/images/infobip-shift-2021-4.jpg"
  alt="Panorama"
  width={13056}
  height={3918}
/>

<caption>
  It was a <em>huge</em> venue! Photo by <a href="https://twitter.com/swyx">Shawn Wang</a>.
</caption>
</p>

<p>
<img
  src="/images/infobip-shift-2021-5.jpg"
  alt="Flow"
  width={3024}
  height={4032}
/>

<caption>
  I ended with a pitch for my new employer, <a href="https://www.centered.app/">Centered</a>.
  Photo by <a href="https://twitter.com/swyx">Shawn Wang</a>.
</caption>
</p>

<p>
<img
  src="/images/infobip-shift-2021-6.jpg"
  alt="Speaker's Dinner"
  width={4032}
  height={3024}
/>

<caption>
  We had a speakers dinner in an abandoned church, where I enjoyed the company of <a href="https://twitter.com/atilafassina">Atila Fassina</a>, <a href="https://twitter.com/mhevery">Misko Hevery</a>, <a href="https://twitter.com/kentcdodds">Kent C. Dodds</a>, and <a href="https://twitter.com/CompuIves">Ives van Hoorne</a>.
</caption>
</p>

<p>
<img
  src="/images/infobip-shift-2021-7.jpg"
  alt="Ives and Kitze"
  width={4032}
  height={3024}
/>

<caption>
  Me with the legendary <a href="https://twitter.com/CompuIves">Ives van Hoorne</a> and <a href="https://twitter.com/thekitze">Kitze</a>.
</caption>
</p>


You're a Wizard Form, Harry.

Modern Forms in React

🏁 Final Form: Form state management via Observers

Next Generation Forms with React Final Form


Validation is probably the most complicated part of maintaining form state:
deciding _when_ to validate values, and _when_ and _where_ to display error
messages are important design decisions for making your forms as useable as
possible by the widest range of users.

Over a decade ago, the W3C set out some guidelines for what they thought the
next version of HTML should look like, and they called it HTML5. Part of that
standard included a system for validating form fields, both with native browser
rules, and also the ability to set a custom validation error on a field. These
days, the HTML5 validation standard is
[more-or-less supported by all web browsers](https://caniuse.com/#search=setCustomValidity).

## Why use HTML5 Validation?

I see three primary reasons why HTML5 form validation is a good thing to
incorporate into your application:

### Consistency of Design

By using the browser’s built-in mechanism for displaying form errors, your users
will be given a consistent UI for form errors across the entire internet (or at
least those very few sites that are advanced as yours will be when you start
using HTML5 form validation).

### Accessibility

This is the big one. Screen readers and other accessibility tools need a lot of
help understanding what exactly went wrong when a form submission fails. Some
screen readers will also let the user know a field is required when they enter
the field for the first time.

### Built-In Focus On Errors

As of last week, 🏁 Final Form supports [a plugin](/blog/focus-on-errors) to
focus on the first form field with an error. But with HTML5 Form Validation, it
comes for free from the browser! The browser stops the form submission and
focuses on the first error even before React is given the `onSubmit` event.

---

Introducing...

## [🏁 React Final Form HTML5 Validation](https://github.com/final-form/react-final-form-html5-validation)

I’ve written a drop-in replacement for the `Field` component in 🏁 React Final
Form that wraps the official `Field` component and adds the additional HTML5
validation onto it by doing three things:

- Deducing which DOM input corresponds to the field
- Injecting a special field-level validation function that reads from the
  `input.validity` DOM structure.
- Setting the HTML5 validation error with `input.setCustomValidity()` if there
  is an error from a specified field-level validation function.

The result is a two-way binding between the browser native HTML5 Validation, and
any field-level validation function specified to the component. The bindings are
two-way because any
[HTML5 contraint validation errors](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#the-constraint-validation-api)
will be added to the 🏁 Final Form state, and any _field-level_ validation
errors from 🏁 Final Form will be set into the HTML5 `validity.customError`
state. Unfortunately, this functionality is not compatible with 🏁 React Final
Form _record-level_ validation, so the two should not be mixed.

> “Why not add this functionality directly into the officially bundled `Field`
> component?”

Good question. The reason is that not everyone needs this functionality, and not
everyone is using 🏁 React Final Form with the DOM (e.g. some people use it with
React Native). Therefore it makes sense to make this a separate package. This
version of `Field` is a thin wrapper over the official `Field` component, and
the only `Field` API that this library uses/overrides is the field-level
validate prop, so even if you are using this library’s `Field` component, you
will still get improvements as features are added to the 🏁 React Final Form
library in the future.

> "How to use it?"

Well, first you change this:

```js
import { Field } from "react-final-form";
```

to this:

```js
import { Field } from "react-final-form-html5-validation";
```

All the regular API of `Field` stays the same, except that now you can pass in
props like `maxLength={25}` or `required` and, optionally, messages to display
when those rules are broken, e.g. `tooLong="Be more concise!"` or
`valueMissing="You need to answer this"` respectively. All of these prop names
are taken from the
[HTML5 Specification](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#the-constraint-validation-api),
so if you have staff already trained to the standards, they should pick it up
right away.

## What does it look like?

Well, the error UI look slightly different in every browser. No doubt the users
of each of these browsers will recognize this format of displaying error
messages.

<div style={{ textAlign: "center" }}>
  <img
    src="/images/html5-validation-safari.gif"
    alt="HTML5 Validation in Safari"
    width={500}
    height={368}
  />
</div>

<caption>Safari</caption>

<div style={{ textAlign: "center" }}>
  <img
    src="/images/html5-validation-chrome.gif"
    alt="HTML5 Validation in Chrome"
    width={500}
    height={355}
  />
</div>

<caption>Chrome</caption>

<div style={{ textAlign: "center" }}>
  <img
    src="/images/html5-validation-firefox.gif"
    alt="HTML5 Validation in Firefox"
    width={500}
    height={357}
  />
</div>

<caption>Firefox</caption>

And here’s the obligatory sandbox embed for you to play with…

<iframe
  src="https://codesandbox.io/embed/14r018yjp4?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: 500,
    border: 0,
    borderRadius: 4,
    overflow: "hidden",
  }}
  title="🏁 React Final Form - HTML5 Validation Example"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

<caption>Go ahead! Play around with it!</caption>

## Conclusion

HTML5 Form Validation is yet another step towards making 🏁 Final Form the most
versatile, extensible form state management framework for React and beyond. Just
think how pleased your boss will be when you inform her that you’ve made all
your forms much more accessible! 😜

❤️ Thanks for reading. ❤️


🏁 React Final Form HTML5 Validation


The users of [🏁 React Final Form](https://react-final-form.org) continue to
suggest interesting use cases that challenge just what is possible from a form
library, and stimulate my imagination about possible solutions.

Today’s problem was:

> How can I update field B when field A changes from X to Y?

As the API stands currently, this could not be accomplished with
[🏁 Final Form Calculate](/blog/final-form-decorators), as it matters what the
_previous value_ was. We need a way to run some code to update another field
when one field changes, _without calling the update in `render()`_.

This requires a _**stateful**_ component to subscribe to changes to a field and
keep track of what the previous value was. It was pretty trivial to code up an
`OnChange` component that doesn’t render anything, but calls a callback when the
field value changes. This seemed so potentially useful that I went ahead and,
for completeness, created `OnBlur` and `OnFocus`, resulting in the library
[🏁 React Final Form Listeners](https://github.com/final-form/react-final-form-listeners#-react-final-form-listeners).

Having just discovered this idea, I have not yet decided how useful it is, or
whether or not it’s a good idea, but I’m sharing it to get feedback from others.
These components allow us to write “form rules” as non-rendering components,
like this:

```jsx
<WhenFieldChanges
  field="pickup"
  becomes={true}
  set="delivery.street"
  to={undefined}
/>
```

How do we write `WhenFieldChanges`? Well, we need a `Field` to get the
`onChange` function for the field we want to change, and then the OnChange
component to notify us when the field we want to listen to has changed value.

```jsx
const WhenFieldChanges = ({ field, becomes, set, to }) => (
  <Field name={set} subscription={{}}>
    {(
      // No subscription. We only use Field to get to the change function
      { input: { onChange } }
    ) => (
      <OnChange name={field}>
        {(value) => {
          if (value === becomes) {
            onChange(to);
          }
        }}
      </OnChange>
    )}
  </Field>
);
```

It’s important to notice that the function given to `OnChange` will _only_ be
called when the value changes, not on every render. Let’s see how it looks in
practice.

<iframe
  src="https://codesandbox.io/embed/52q597j2p?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: 500,
    border: 0,
    borderRadius: 4,
    overflow: "hidden",
  }}
  title="🏁 React Final Form - Declarative Form Rules"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

## Conclusion

I’m still not convinced how useful this concept is, but it’s kind of fun to
explore the boundaries of what React allows us to do. Component composition, and
letting them keep state as the data cascades through them, is extremely
powerful.

As always, feedback welcome and encouraged! 🤔


Declarative Form Rules


Without a doubt, one of the most common questions I hear from people using my
forms libraries is:

> “How can I focus on the first field that has an error?”

Merely asking this question demonstrates a perceptive level of UX intelligence.
Clearly it’s an order of magnitude better to actually take a user to the problem
spot rather than just tell them “There’s an error up there somewhere. Scroll up
and try to find it!”

Here’s the answer I usually give:

> Well, that’s a tough problem, because calling focus() on an input requires
> having direct access to the DOM instance, and [form library] does not have
> that; all [form library] does is provide a `value` and `onChange` (and other
> listeners) to you, the developer that actually renders the `<input>`, and
> there is no good way for you, who may have a DOM reference to the input, to
> give that back to [form library] to allow [form library] to call focus() on
> the DOM element.

🙄 Just typing that practically put me to sleep. Yawn! 😴

<div style={{ textAlign: "center" }}>
  <img
    src="/images/sleepy-girl.gif"
    alt="Sleepy...zzzz"
    width={400}
    height={282}
  />
</div>

## 🤔 Can we do better?

It ocurred to me that, at least in DOM-land (sorry React Native folks!), we have
this ancient structure which, like Seinfeld — _“What’s the deal with render
props?!”_ — dates back to the early 1990’s, that modern web developers might not
know about. Did you know that _document.forms[0][0]_ will give you a reference
to the first input on the first form on your page? Or, that if you give your
form a name, e.g. `<form name="foo">`, that you can iterate through an
`HTMLCollection` of its inputs at `document.forms.foo`? 🤯

So, maybe a higher level form library can gain access to the input DOM elements,
as long as they are given the name value that matches the field name the form
library knows about?

---

🥁 🥁 🥁 Introducing, the alliterative…

## 🏁 Final Form Focus 🧐

[🏁 Final Form Focus 🧐](https://github.com/final-form/final-form-focus) is a
decorator for 🏁 Final Form. That means that you just import it and plug it in,
and it does all the rest. There is only one possible change in configuration: in
the interest of future proofing it and maybe allowing non-DOM platforms, like
React Native, to take advantage of it, you may provide a `getInputs()` function
that will give a list of “focusable inputs” (i.e. objects with a `name` property
and a `focus()` method) that correspond to the fields in your form. For those of
us in DOM land, you can omit that parameter and it will default to searching
through your `document.forms` structure and will "just work".

Whenever your form is submitted and the submission fails due to synchronous,
asynchronous, or submission validation errors, the first input on the page that
has a `name` prop that matches the path to an error will have `focus()` called
on it.

What does it look like? Well, if you’re using 🏁 React Final Form, you just add
the decorator like this:

```jsx

import React from 'react'
import { Form, Field } from 'react-final-form
import createDecorator from 'final-form-focus'

const focusOnErrors = createDecorator()
...
<Form
  onSubmit={submit}
  decorators={[ focusOnErrors ]} // <--------- 😎
  validate={validate}
  render={({ handleSubmit }) =>
    <form onSubmit={handleSubmit}>

      ... inputs here ...

    </form>
  }
/>
```

<caption>
  Step 1: Add the decorator to your form. Step 2: There is no Step 2!
</caption>

Let’s see it in action:

<iframe
  src="https://codesandbox.io/embed/6174kqr403?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: 500,
    border: 0,
    borderRadius: 4,
    overflow: "hidden",
  }}
  title="🏁 React Final Form - Focus On First Error"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

## Vanilla JS Code

For those of you that have arrived to this post by googling “how to focus on the
input with the first validation error” (_Look, ma! I’m SEOing!!_), or looking to
add this functionality to your own form solution, this is all it takes:

```js
function focusOnFirstError(formName, hasError) {
  const form = document.forms[formName];
  for (let i = 0; i < form.length; i++) {
    if (hasError(form[i].name)) {
      form[i].focus();
      break;
    }
  }
}
```

<caption>
  `hasError()` is a predicate that returns truthy if a field has an error
</caption>

## Conclusion

Almost none of the web forms — or native forms, for that matter — I use on a
daily basis are sophisticated enough to bring focus to the first field with an
error, and thus introduce friction and frustration into the user experience.
Implementing “focus on first error” manually on every form is quite difficult,
e.g. keeping track of all the DOM refs, sorting them by which is first on the
page, and examining the error structure at submission to determine which one to
focus on.

But now, with 🏁 Final Form, there is a pluggable way to get that functionality
_**on every form you write**_.

❤️ Thanks for reading, and I look forward to your feedback! ❤️


Focus On Errors 🧐


Last week, I introduced
[the concept of mutators and array fields](/blog/final-form-arrays-mutators) to
🏁 Final Form. This week, I’d like to introduce the concept of decorators, and
show two examples of how powerful decorators and mutators can be, when combined
with the subscription-based paradigm of 🏁 Final Form.

## Decorators

The term comes from
[ye olde ancient forgotten land of OOP](https://en.wikipedia.org/wiki/Decorator_pattern).

> In object-oriented programming, the **decorator pattern** is a design pattern
> that allows behavior to be added to an individual object, either statically or
> dynamically, without affecting the behavior of other objects from the same
> class.

In terms of 🏁 Final Form, a decorator is just a function that takes the form
object, subscribes to it somehow, and returns a function that can be called to
“undecorate” (undo all of its subscriptions). This allows a decorator to listen
for changes and enact side-effects.

This simple pattern allowed me to write a
[45 line](https://github.com/final-form/final-form-calculate/blob/master/src/decorator.js)
— and those are post-[Prettier](https://prettier.io/) lines! — library to
perform realtime calculations between fields, not unlike a spreadsheet.

## [🏁 Final Form Calculate](https://github.com/final-form/final-form-calculate)

This library creates a 🏁 Final Form decorator based on a set of calculation
rules you provide. Here’s what it looks like:

```js
import { createForm } from "final-form";
import createDecorator from "final-form-calculate";

// Create Form
const form = createForm({ onSubmit });

// Create Decorator
const decorator = createDecorator(
  // Calculations:
  {
    field: "foo", // when the value of foo changes...
    updates: [
      {
        // ...set field "doubleFoo" to twice the value of foo
        doubleFoo: (fooValue, allValues) => fooValue * 2,
      },
    ],
  },
  {
    field: /items\[\d+\]/, // when a field matching this pattern changes...
    updates: {
      // ...sets field "total" to the sum of all items
      total: (itemValue, allValues) =>
        (allValues.items || []).reduce((sum, value) => sum + value, 0),
    },
  }
);

// Decorate form
const undecorate = decorator(form);

// Use form as normal
```

Here is a live demo showing what this looks like.

<iframe
  src="https://codesandbox.io/embed/oq52p6v96y?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: 500,
    border: 0,
    borderRadius: 4,
    overflow: "hidden",
  }}
  title="🏁  React Final Form - Calculated Fields"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

Kind of a silly example, but there are valid use cases for this feature.

## [🏁 Final Form Set Field Data](https://github.com/final-form/final-form-set-field-data)

This library is a trivial little thing that provides a mutator that set any
arbitrary metadata for a field. You use it like this:

```js
import { createForm } from "final-form";
import setFieldData from "final-form-set-field-data";

// Create Form
const form = createForm({
  mutators: { setFieldData },
  onSubmit,
});

form.mutators.setFieldData("firstName", { awesome: true });

form.registerField(
  "firstName",
  (fieldState) => {
    const { awesome } = fieldState.data; // true
  },
  {
    // ...other subscription items
    data: true,
  }
);
```

Why would you want this? Well, for one, it allows you to create…..

## ⚠️ Field Warnings ⚠️

Way back in September of 2016 — in the horrible Dark Times before Prettier–a
user and prolific contributor to Redux-Form submitted
[a pull request](https://github.com/erikras/redux-form/pull/1780) for a feature
that never would have occurred to me. He needed fields to have what he called
“warnings”, which are just like synchronous validation errors, but they don’t
prevent submission. The way it was implemented was the way new features are
often added to software: by taking the existing validation pipeline and
duplicating all the methods and data structures to create a warning pipeline. It
worked perfectly, of course, but as is often the case with code duplication, it
created problems in the future, where someone fixed a bug in the error-handling
code, but not in the mirror image _warning_-handling code. And, of course, it
wasn’t long before someone came along and said, “You know, it’d be cool if we
could set, just, like, any arbitrary metadata on a field that we want, maaaan.”

With the ability to set arbitrary metadata into fields provided by
`final-form-set-field-data`, coupled with the subscription-based form state
paradigm of 🏁 Final Form, it becomes trivial to implement your own warning
system. Behold:

```jsx
const WarningEngine = ({ mutators: { setFieldData } }) => (
  // FormSpy lets you listen to any part of the form state you want.
  // If you provide an onChange prop, FormSpy will not render to the DOM.
  <FormSpy
    subscription={{ values: true }}
    onChange={({ values }) => {
      setFieldData("firstName", {
        warning: values.firstName ? undefined : "Recommended",
      });
      setFieldData("lastName", {
        warning: values.lastName ? undefined : "Recommended",
      });
    }}
  />
);
```

This component subscribes to the form values, so its onChange function gets
called every time they change, and it sets or removes a warning value in the
fields. All you have to do is include this somewhere inside your form — after
all the fields, so that they are registered when onChange is called the first
time.

Here it is in action: (tab through the fields to see the warnings appear)

<iframe
  src="https://codesandbox.io/embed/react-final-form-warnings-m5qwxpr6o8?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: 500,
    border: 0,
    borderRadius: 4,
    overflow: "hidden",
  }}
  title="🏁  React Final Form - Warnings"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

## Conclusion

My goals with 🏁 Final Form is to be as lean and flexible as possible. Rather
than implementing a feature like field arrays or field warnings or calculated
fields directly in the core library, the core library allows ways for them to be
implemented outside, so that each application can only use the tools and pieces
it needs, and unforeseen use cases can be implemented for their specific project
and not for all. What interesting form features can you imagine building?

Happy coding, y’all. ❤️👩‍💻👨‍💻


🏁 Final Form — Decorators, Calculated Fields, and Warnings


After the release of [🏁 Final Form](https://final-form.org) and
[🏁 React Final Form](https://react-final-form.org)
[seven days ago](/blog/final-form-announcement), the very first feature that
[people asked for](https://github.com/erikras/react-final-form/issues/2) was
array fields / arrays of fields. I could have pretty easily implemented the
ability to push, pop, insert, etc. into array values as part of 🏁 Final Form,
but the reason that Redux Form got so gargantuan was from exactly this sort of
feature bloat, where many individuals added on their own pet feature, and
everyone that uses the library has to download _all of these features_ whether
they use them or not. How could I avoid this with 🏁 Final Form?

🏁 Final Form is already more or less feature complete (famous last words) as
far as editing flat or arbitrarily deep form values. But how could it be made
more _extensible_? Well, here’s what I came up with:

## Mutators

Mutators are functions that can be provided to 🏁 Final Form that are allowed to
mutate any part of the form state. You provide an object of mutators when you
call `createForm()`, and then they are exposed (bound to the form state) on the
form instance you get back, under `form.mutators.whatever()`. A mutator function
is given: the arguments it was called with, the form state, and a collection of
utility functions, like `getIn` and `setIn` to read and mutate arbitrarily deep
values, as well as `changeValue`, which updates a field value in the form state.
They can mutate the state however they wish, and then the form and field
subscribers that need to be notified will be notified.

What does this look like? Well, here’s a somewhat simplistic example that I
created when writing the unit tests:

```js
/** Clears a form value */
const clear = ([name], state, { changeValue }) => {
  changeValue(state, name, () => undefined)
}

/** Converts a form value to uppercase **/
const upper = ([name], state, { changeValue }) => {
  changeValue(state, name, value => value && value.toUpperCase())
}

const form = createForm({
  onSubmit,
  mutators: { clear, upper }
})

...

form.mutators.upper('foo')

...

form.mutators.clear('foo')
```

These are dumb examples, but what else does this allow? Well, for one, it
allows…..

## Field Arrays

Everyone doesn’t need to include the code for field arrays in their bundle, but
for those that do…..

Introducing:

## [🏁 Final Form Arrays](https://final-form.org/arrays)

This library
([687 bytes gzipped](https://bundlephobia.com/result?p=final-form-arrays@1.0.0))
contains mutators for performing array operations on form values in 🏁 Final
Form.

```js
import { createForm } from "final-form";
import arrayMutators from "final-form-arrays";

// Create Form
const form = createForm({
  mutators: {
    // potentially other mutators here
    ...arrayMutators,
  },
  onSubmit,
});

// push
form.mutators.push("customers", { firstName: "", lastName: "" });

// pop
const customer = form.mutators.pop("customers");
```

And of course it needs a companion:

## [🏁 React Final Form Arrays](https://github.com/final-form/react-final-form-arrays)

This library
([1.7 kB gzipped](https://bundlephobia.com/result?p=react-final-form-arrays@1.0.0))
consists of a `<FieldArray/>` component that very closely mimics the
functionality of
[Redux Form's `<FieldArray/>` component](https://redux-form.com/7.2.0/examples/fieldarrays/),
providing a fields object that is very array-like, with methods like `forEach`,
`map`, `push`, `pop`, `shift`, `splice`, etc. When you iterate through it, it
gives you the array-syntax strings (e.g. `foo[0]`) for the array value in your
form, ready to be used with the `<Field/>` component.

An example is worth 1,024 words…

<iframe
  src="https://codesandbox.io/embed/distracted-bhaskara-kx8qv67nk5?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: 500,
    border: 0,
    borderRadius: 4,
    overflow: "hidden",
  }}
  title="🏁 React Final Form - Field Arrays"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

## Going Forward

I have some other ideas of functionality that can be provided by mutators, and
I’m sure you do, too. They could provide some very powerful features to your
forms in the future, without imposing feature bloat on applications that just
need a simple login and account form.

As always, feedback welcome! Thanks for reading. ❤️


🏁 Final Form – Field Arrays and Mutators


Two and a half years ago, about a month after
[Dan Abramov](https://overreacted.io)’s
[unforgettable launch](https://www.youtube.com/watch?v=xsSnOQynTHs) of Redux at
React Europe 2015, I released a humble little library that managed form state in
Redux, called [Redux-Form](https://redux-form.com), which, over the intervening
period, has grown quite substantially in popularity.

<div style={{ textAlign: "center" }}>
  <img
    src="/images/redux-form-logo.png"
    width={300}
    height={181}
    alt="Redux Form Logo"
  />
</div>

As I write this in late 2017, Redux-Form has well over 8k stars on Github and
800k monthly downloads on NPM. By my recent calculations, based entirely on NPM
download figures, about half of React projects use Redux, and about a quarter of
those use Redux-Form, so about 11% of the _7 million_ projects that download
React, also download Redux-Form.

With this popularity and usage has come a deluge of feedback. Everyone has had a
slightly different use case and requested a slightly different behavior out of
Redux-Form. I have done my best to accommodate these, and merge in pull requests
for features that never would have occurred to me. I’ve done a lot of thinking
about forms and form state management.

## Problems with Redux-Form

Over these years, I have heard four primary complaints about Redux-Form. For
some reason, unlike with most complaints, I have most heard these in person at
conferences than on Twitter or Github or Stackoverflow. They are as follows, in
no particular order, but with growing emoji angst:

1. **🙁 It’s only for React?**

“Redux works with Angular, _et. al._, it’s too bad that Redux-Form doesn’t.”

2. **😢 I have to use Redux?**

“I really need a form solution, but my project isn’t using Redux.” Also,
everyone high up in the React community,
[_including both inventors of Redux_](https://github.com/reactjs/redux/issues/1287#issuecomment-175351978),
say that Redux is **_not_** the best place to keep form data. Oops.

3. **😖 I can’t use inline render functions?**

“Why does my input lose focus on first keypress?” Well, it’s because Redux has
asynchronously updated both your input and the surrounding form component
(because now `dirty === true`), and because your inline render function is !==
the previous one, blah blah blah 😢

4. **😭 It’s [over 26k gzipped?](https://bundlephobia.com/result?p=redux-form)
   No way!**

“Bundle size, bro. I’m watching my weight.”

## Premature Optimization

As `v5` of Redux-Form became very popular, the biggest complaint I had was that
it was slow. The theory behind why was that it was rerendering the _entire_ form
on every single keypress, since the `values` were provided to the form
component.

In early 2016, I solved this, by completely rewriting it from scratch, in what
became `v6`, creating a `<Field/>` component, which only updated when _its_
state changed, but did not update when another field’s state changed. This
complicated matters greatly, because now the whole `<Form/>` only received a few
select form-wide props, so the people that needed more information had to
`connect()` with a
[suite of selectors](https://redux-form.com/8.3.0/docs/api/selectors.md/) to get
other form state that was no longer provided by default.

It is entirely possible that the fear of rerendering the entire form drummed
into me by the complaints that lead to Redux-Form `v6` is unfounded, but,
whether or not the user notices it, it must be true that rerendering parts of
your tree needlessly _is_ going to be slower than avoiding it. I decided that my
next form solution should have built-in “only rerender if you need to” logic,
which most people will never need, but that will allow fine tuning of complex
forms.

## Solution

Some time in early 2017, I had the idea to create a “form state management
engine” that was totally independent of React or Redux, just pure javascript. My
first attempt was using Immutable.js, leveraging its power for fast “has this
whole tree changed?” checks. I was about halfway done with it in May, when I
mentioned it to fellow form library author,
[David Khourshid 🎹](https://twitter.com/davidkpiano). His reaction to involving
Immutable.js (15.3k gzipped) was negative, and it made me rethink my approach;
could I do it without the help of _any_ third party libraries? In August, during
an offline vacation, I began coding a dependency-free form management library.

## Going with the Flow

Normally I would build a library from the inside out, from the core to the
public API, but this time, I defined the API first, even writing some tests,
before implementing the core functionality. By strongly typing my API with
[Flow](https://flow.org/), I was able to catch bugs and ensure that the
internals were satisfying the contracts of the API. It felt a little like pair
programming with an annoying partner that was constantly saying, “Well actually,
that’s supposed to return a string!”, _but in a good way!_ Flow is awesome. 😍

## Clogged Namespace

Before I get to the _finish line_ of this post, I’d like to talk about the
process of choosing library names. I probably tried a hundred different names
involving the word “form” before finding one that was not taken already on NPM.
So many of them are rotten unused/unfinished/undocumented libraries that have
not been updated in a long time, and others are just empty namespace squatters —
a tactic I was forced to resort to in reserving the name of my library until
launch. I guess it was inevitable that a good NPM library name would become as
hard to acquire as a good .com domain, but it’s still frustrating.

Speaking of namespace..._Emojispace!_ After seeing the emoji branding succcesses
of popular 2017 libraries
[Styled Components 💅](https://www.styled-components.com/),
[Glamorous 💄](https://github.com/paypal/glamorous), and
[Downshift 🏎️](https://github.com/paypal/downshift), I decided that my library
needed an emoji to go with it. I have been very nervous that someone might steal
the one I chose (months ago) before launch, which has been very motivating!

Okay, now on to the announcement…..

<div style={{ textAlign: "center" }}>
  <img
    src="/images/final-form-banner.png"
    width={700}
    height={178}
    alt="Final Form Banner"
  />
</div>

## 🏁 Final Form

Today I am launching a new form library, called
[🏁 Final Form](https://final-form.org/). It’s based on the
[Observer pattern](https://en.wikipedia.org/wiki/Observer_pattern), so observers
can subscribe to receive updates for either form or field state changes. Each
observer must explicitly define _which_ parts of the state they want to be
notified about, and they will _only_ be called when the parts they have
subscribed to have been changed.

It has **zero** dependencies, is framework agnostic, and weighs in at 💥
**3.5k** gzipped 💥.

<div style={{ textAlign: "center" }}>
  <img
    src="/images/react-final-form-banner.png"
    width={700}
    height={178}
    alt="React Final Form Banner"
  />
</div>

## 🏁 React Final Form

Of course it had to come with a companion library,
[🏁 React Final Form](https://final-form.org/react), which is a thin wrapper
around 🏁 Final Form that allows it to be used in React. And when I say thin… it
weighs in at 💥 **2.2k** gzipped 💥, for a combined weight of **5.7k** gzipped.
It has no dependencies, and only two peer dependencies: 🏁 Final Form and
React…..as the name would suggest 🙄.

## Problems with Redux-Form: ✅ Solved!

1. **🙂 Is it only for React?**

Nope! There’s nothing stopping anyone from implementing a 🏁 Final Form wrapper
in Angular, Ember, Vue, Preact, Elm, ReasonML, TheNextHotness™, etc.

2. **😊 Do I have to use Redux?**

Nope! State is canonically kept inside the 🏁 Final Form instance, and the React
components know when to rerender by calling `setState()` when they are notified
of a state change.

3. **😀 Can I use inline render functions?**

Of course you can! It’s almost 2018, for Pete Hunt’s sake! And to paraphrase a
prominant thoughtleader of the React community:

> “OMG!! Render functions! RENDER FUNCTION ALL THE THINGS!!!11one11"
>
> –– Michael Jackson

Both the `<Form/>` and `<Field/>` components use the three ways of rendering
that I have humbly stolen from the awesome rival library,
[Formik](https://github.com/jaredpalmer/formik#formik-render-methods), by
[Jared Palmer](https://twitter.com/jaredpalmer). Brilliant idea. You can either
pass a component, a render prop, or a render function to the children prop
([see docs](https://final-form.org/docs/react-final-form/types/FormProps#render)).

4. **😍 It’s only 5.7k gzipped? 21% the size of Redux-Form? AWESOME!**

Lean and mean. 😎

## What does it look like?

People familiar with the Redux-Form syntax should feel right at home, in fact
many custom component libraries that have been adapted for Redux-Form should
Just Work™ in 🏁 React Final Form. I will eventually write a Migration Guide,
but I haven’t gotten around to that yet.

August 2019 Update:
[Migration Guide!](https://final-form.org/docs/react-final-form/migration/redux-form)

<iframe
  src="https://codesandbox.io/embed/ww40y2m595?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: "500px",
    border: 0,
    borderRadius: "4px",
    overflow: "hidden",
  }}
  title="🏁 React Final Form - Simple Example"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

<caption>Simple Example — No custom inputs</caption>

## Roadmap

🏁 Final Form is not yet up to feature parity with Redux-Form. For example, at
launch, it’s missing the concept of `<FieldArray/>` to edit an array of values
(**EDIT:** `<FieldArray/>` functionality
[released 7 days after this post](https://erikras.com/blog/final-form-arrays-and-mutators)
and `<Fields/>` to edit several fields in a single component. Nor does it have
some of the more esoteric features such as `autofill`. I plan on being a little
more willing to say, “No, I will not implement your specific feature,” with this
library, to minimize its complexity and surface area. I suspect that most edge
cases that previously required a new Redux action could be managed within React
state.

I very much look forward to working with others who want to wrap 🏁 Final Form
into another view framework, or even other implementations of 🏁React Final
Form. One suggestion: get in early if you want to be the dominant library (see
first paragraph).

## Conclusion

I cannot wait to get feedback from the community; I have learned so much from
you all in my years with Redux Form. ❤️

I do plan on continuing to maintain Redux Form. If you’ve built a huge
enterprise application on top of Redux Form, don’t worry; I’m not going
anywhere. But maybe you could try out 🏁 Final Form on the next form page you
build?

🙏 Thanks for reading. Go install it, star it, and give it a try! 🎉


🏁 Final Form

Posted in 🏁 Final Form