RFC: Make Form the context provider

[jaredpalmer]

I have been thinking of ways to make Formik and useFormik even less verbose recently. My idea is to introduce a new context provider (or document the existing <FormikProvider>) as the "right" way of using Formik instead of the render prop.

Proposal 1: Document useFormik + FormikProvider pattern

We probably should do this no matter what, but the idea is that people should use useFormik and FormikProvider together instead of the render prop <Formik> going forward. This allows Field and other context based components to be easily used without ceremony or added verbosity. It also lets folks easily do effects with useEffect.

No changes need to made internally to support this as FormikProvider is already exported, we just would need to update the docs.

import { useFormik, FormikProvider, Form, Field } from 'formik'

const MyApp = () => {
  const formik = useFormik({...})
  const { values } = formik

  React.useEffect(() => {
    // do stuff to values
  }, [values])

  return (
    <FormikProvider value={formik}>
      <Form>
        <Field name="firstName" />
      </Form>
    </FormikProvider>
  )
}

There aren't any downsides to this as this is exactly what the <Formik> component does internally. However, I think we can make this even more intuitive and look more like HTML...

Proposal 2: Make Form a context provider

To further cut down on verbosity, we could allow <Form> to render the Context provider. This would save us from several keystrokes and another import. In React DOM, it would still render a <form onSubmit={formik.handleSubmit}>. In React native, it would just render children under the provider.

External API

import { useFormik, Form, Field } from 'formik'

const MyApp = () => {
  const formik = useFormik({...})

  return (
    <Form formik={formik}>
      <Field name="firstName" />
    </Form>
  )
}

Implementation

import { FormikProvider, FormikContext } from 'formik'

export const Form = ({ formik, children,...props }) => {
  if (isReactNative) {
     return <FormikProvider value={formik}>{children}</FormikProvider>
  }
  
  const maybeContext = React.useContext(FormikContext)
  if (maybeContext) {
    return (
      <form onSubmit={maybeContext.handleSubmit} onReset={maybeContext.onReset} {...props}>
       {children}
      </form>
    );
  }
  
  return (
     <FormikProvider value={formik}>
       <form onSubmit={formik.handleSubmit} onReset={formik.onReset} {...props}>
        {children}
       </form>
     </FormikProvider>
  )
  
}

One thing we would need to do in React Native docs is to state that <Form> doesn't render anything and re-iterate that formik.handleSubmit still needs to be passed to <Button>.

Proposal 3: Make it a spread

Looking back at my usage of <Form> over the years, I can count the number of times I have passed it an additional prop on one hand. And that was just to fix a typescript bug with @types/react. I know typing out <Form formik={formik}> isn't a lot, but it looks awful. Instead we could make <Form> accept the spread. In React DOM, we could sniff out the keys of formik context and passing any other props to the root form element.

import { useFormik, Form, Field } from 'formik'

const MyApp = () => {
  const formik = useFormik({...})

  return (
-    <Form formik={formik}>
+    <Form {...formik}>
      <Field name="firstName" />
    </Form>
  )
}

Alternative 3a: Keep <FormikProvider> and make it a spread.

Keep FormikProvider but have it take a spread. Less typing. Also works flawlessly in React Native. The downside is that this is another import (4 vs. 3).

import { useFormik, Form, Field, FormikProvider } from 'formik'

const MyApp = () => {
  const formik = useFormik({...})

  return (
   <FormikProvider {...formik}>
      <Form>
       <Field name="firstName" />
     </Form>
   </FormikProvider>
  )
}

Wanted to open this up to discussion and gather feedback.

[johnrom]

I keep thinking, can't we just allow the user to pass useFormik to Formik since it is already a FormikProvider? But I guess it would trigger a warning about Conditionally Calling React Hooks.

const MyForm = () => {
  const formik = useFormik({ onSubmit, initialValues, ...etc });

  return <Formik formik={formik} /> // inb4 xzibit reference
}

const Formik = (props) => {
  const formikBag = props.formik || useFormik(props);

  return `<FormikProvider {...formikBag}>{props.children}</FormikProvider>`;
}

I personally use the useFormik and FormikProvider pattern currently and it works great. I think it would be extremely weird for Form to be a provider and not a consumer, since in my mind it's just icing on top of a plain <form /> element.

[johnrom]

if we're really concerned about adding another import, another option would be to return the Provider from useFormik. but it's also extremely weird and would probably somehow end up getting passed to form elements via destructuring. bonus points if we call the provider Formik and confuse everyone.

const { Formik, ...formik } = useFormik({});

return <Formik>
  <Form />
</Formik>;

[jaredpalmer]

This is a great idea.

[jaredpalmer]

A third option I've thought about: one shared context.

// at root
import { FormikAppProvider } from 'formik'
import { MyApp } from './App'

ReactDOM.render(
  <FormikAppProvider>
    <MyApp />
   </FormikAppProvider>
);

// one less import everywhere else
import { useFormik, form } from 'formik'

export const MyApp = () => {
   const formik = useFormik({...})
   return (
      <Form>
        <Field />
      </Form>
     )
}

// can now use multiple formiks on same page since 
// context is now namespaced instead of shared.
import { useFormik, form } from 'formik'

export const MyApp = () => {
   const formik = useFormik({ id: 'a', ...})
   // this also just works too
   useFormik({ id: 'b', ...})
   return (
     <>
      <Form id="a">
        <Field /> // knows to pull from a
      </Form>
      <Form id="b">
         <Field /> // knows to pull from b
       </Form> 
     </>
     )
}

[johnrom]

Global Context itself I think is a step backwards -- scoped Context differentiates Formik from competitors like Redux Form. Global Context could add to the current Context-related performance problems by causing other forms to re-render when one form's values change if not implemented extremely carefully.

I think the idea of creating a reusable forms is cool, but imagine calling useFormik with the wrong id by accident. It could be hard to tell why your form or values were overridden with settings from somewhere else across the site. We'd also want to add type safety with TypeScript to make sure the same FormValues were always passed to the same id, and probably support sharing configuration declaratively. Maybe there is a way by creating a form definition instead of just using a token identifier.

import { createForm } from 'formik';

// would we do onSubmit here? validators? would we wrap these with withYup(schema)(createForm()) or something?
// would they be overrideable on the component level? it's probably adding an extra layer of complexity
const FriendForm = createForm<FriendValues>(); 

export const EditFriends = ({ friendIds }) => 
  friendIds.map(friendId => <EditFriend key={friendId} friendId={friendId} />);

export const EditFriend = ({ friendId }) => {
  const onSubmit = useCallback((values) => console.log('updating friend', friendId, values), [friendId]);

  // not sure what config would go here vs createForm
  // but importantly Context would be scoped here and not globally to support multiple uses on the same page
  const formik = useFormik(FriendForm, { onSubmit });

  return <FormikProvider formik={formik} />;
  // or
  return <Formik form={FriendForm} onSubmit={onSubmit} />
}

[jaredpalmer]

Agree. That would be extremely frustrating

[JanStevens]

As somebody who just started using formik, proposal 2 is the most declarative and understandable form. It reads as I want to use a form so I pass my formik object to form

The spread is also an option but imo there is little difference in formik={formik} vs {...formik} I even would say that the spread is more frowned upon.

Having an explicit declarative API goes a long way in providing enough magic to make it work but not too much to make it confusing / hard to grasp whats going on. Saying that Form is the Provider that needs a formik object makes sense in that regard. It's the same as Redux Provider needing a store.

[HHK1]

Very interesting, I did not know about the FormikProvider

In my last projects I've already stopped using render props. Instead I'm using small Formik wrappers around my input components and plug it to the context with useField.

When I do need access to the values, I access them via the useFormikContext and usually do that in the concerned component to avoid accessing the context at the top level of my form and trigger a lot of re-rendering. Usually it's for cross input rules like disabling an input if something has been selected, or for the submit button.

What would that mean in terms of rendering to call the useFormik hook at the top level ?

[smakosh]

Proposal 2 looks so simple to me but can we override it for styling the form element by passing the as prop in case we're using styled-components or such?

[jaredpalmer]

@smakosh yes. definitely.

[jaredpalmer]

Okay research update: I was doing some recoil-like experiments and came across https://github.com/dai-shi/use-context-selector. It does what you think it does, but within user land (ie. useContext(Context, (s) => s)) and also works with concurrent mode.

I made a codesandbox that shows off how it effectively optimizes useField and Field the way we've always wanted to.

https://codesandbox.io/s/formik-use-context-selector-2-hso7i?file=/src/App.tsx

One thing I discovered is that it cannot do the optimization with the useFormik + Provider pattern as we've been talking about above, where useFormik is called above the provider. This is because useFormik will rerender everything beneath it. I'm pretty sure this is always true with this pattern (even right now) and something to consider going forward. By promoting this, we could be putting ourselves in a perf hole because we pass back state.

Anyways, use-context-selector absolutely slaps for render props API. I think we can do it without making any breaking changes either.

[jaredpalmer]

FWIW I'm think a solution to the above problem is to make stable state getter functions and move away from passing down objects. Instead of values, we make a getValues() function that is stable between renders.

[sibelius]

I think react-table does a lot of this tricky to avoid rerenders

[furkankly]

I also just started to use Formik and was using render prop. I was quite excited about using my own custom input primitives as suggested in useField docs but as I went further, I had cases where I needed to use useEffect with values just like how you stated in:

import { useFormik, FormikProvider, Form, Field } from 'formik'

const MyApp = () => {
  const formik = useFormik({...})
  const { values } = formik

  React.useEffect(() => {
    // do stuff to values
  }, [values])

  return (
    <FormikProvider value={formik}>
      <Form>
        <Field name="firstName" />
      </Form>
    </FormikProvider>
  )
}

Using this solution, I didn't have to implement many custom primitives for the "same" input type because I can listen for changes on values in the actual form/parent component. Otherwise, I would have to be in the scope of <Formik /> and then use useFormikContext() in the child/primitive component to achieve the same result and that would mean implementing another primitive component just like I mentioned. So that's perfect.

But what you say:

There aren't any downsides to this as this is exactly what the <Formik> component does internally. However, I think we can make this even more intuitive and look more like HTML...

kinda confuses me. Wouldn't having a useEffect in my parent component cause all of the primitives to re-render? So you actually force users to have useEffects in deeper components in specific scenarios by suggesting render prop and that looks more performant to me.

[jaredpalmer]

@symphoniaix This is correct. Which is why I mentioned this in a reply.

One thing I discovered is that it cannot do the optimization with the useFormik + Provider pattern as we've been talking about above, where useFormik is called above the provider. This is because useFormik will rerender everything beneath it. I'm pretty sure this is always true with this pattern (even right now) and something to consider going forward. By promoting this, we could be putting ourselves in a perf hole because we pass back state.

[jaredpalmer]

For what it's worth, the reason for the Formik documentation around useFormik being kind of "plz don't do this" is because I had a gut feeling that the React team wasn't ever going to publish a shouldComponentUpdate equivalent for hooks and we'd work ourselves into a performance black hole by showing everyone an approach that can't be optimized. Turns out I was right. However, I think we still may want to fully document now that we can optimize with use-context-selector because it is still much easier to model effects with useEffect (even if it needs to be encapsulated.

const MyFormik = (props) => {
   const formik = useFormik(props)
   useEffect(() => {
     // stuff should go here
   }, [])
   return <FormikProvider formik={formik}>{children}</FormikProvider>
}

// MyFormik is still optimized, we just need to encapsulate the effect
const App = () => {
   return <MyFormik initialValues={...} onSubmit={...}><Field /></MyFormik>
}

So basically we can/should update our performance optimization discussion to make note that a "naked" useFormik() uses state and will rerender everything on each update. However, the way to mitigate this will be to use <Formik> or make a component such as MyFormik using the custom provider.

[furkankly]

It has been a while I've used <Formik /> ~~ render props in production but as I revisited this discussion, I wanted to ask you if the render props api actually performs any better than using the naked useFormik() right now. We've talked about the flaws of using useFormik naked, but useContext() / useFormikContext() doesn't seem any better to me as the context value is values itself and we don't use use-context-selector "for now" as you mentioned. (It will go very well with Formik, quite happy about it.)
So do we use shouldComponentUpdate anywhere or have any other optimization methods for render props api in the current packages?

Side note: I also get where we're heading with <MyFormik /> but this method also causes every single child component to be wrapped with useContextSelector(), even things like submit button to be used with anything from values (isSubmitting, isValid etc.). So this time, It's not just having an extra wrapper for effectively using useEffect, but having an extra component for each child of <MyFormik />. It still might be more structured than the actual render props api though.

[johnrom]

@jaredpalmer in my experimental PR #2931 @formik/reducer-refs does not share any of the same concerns around re-rendering the Provider and makes it just as performant to use the useFormik + FormikProvider API as any other method.

[shawndewet]

I opt for Proposal 1. Please document the use of <FormikProvider>!!

I am using it in a UI Template that came with my current project.

I have just read your documentation re the use of .useFormik(), which mentions it should be used in the following use cases:

Use cases for useFormik()
You are Jared
You are modifying the returned value and creating a modified version of for your own consumption
You want to avoid using React Context (possibly for perf reasons)

However, in your example of Proposal 1 above, you are also using .useFormik(). Is that one of these mentioned use cases?

Please help...I'm confused about whether I should be using .useFormik() along with <FormikProvider>? Or if I should be using .useFormkContext() instead?

[johnrom]

I'm not a fan of the render props pattern either, but you don't need to use render props with Formik component. Instead, you can useFormikContext in child components. I recommend avoiding render props and moving towards encapsulating your logic within child components when possible.

const MyForm = () => <Formik {...formikProps}>
  <Form> // this Formik component is wired up to accept submits from the form and send them to Formik
    <label for="myField">My Field</label>
    <Field // this Formik component will manage field state
      name="myField" 
      id="myField" 
      validate={value => value !== "Hello World" ? "Please enter 'Hello World'" ? ""} 
    />
    <ErrorMessage name="myField" /> // this will print an error message if you set up validation like above

    <MyCustomComponent />

    <input type="submit" /> // this will submit correctly
  </Form>
</Formik>;

const MyCustomComponent = () => {
  const formik = useFormikContext();
  
  return <p>Value of "myField" is {formik.values.myField} and it {formik.errors.myField ? "has an error" : "doesn't have an error" }.</p>;
}

[furkankly]

How this render props api
<Formik> {({ values }) => ( <Form> ....
is more performant than using useFormik(), I really don't understand. I also asked about it on #2746 (reply in thread). All of the render props including values is part of the context provided by <Formik/> which all of the form fields consume and every single change on values causes all fields to rerender just like in useFormik() case.

Even if we didn't use render props and wrap everything custom under <Form/> with another component to be used with useFormikContext() later on, we are still changing/playing with things out of main the context(formikbag) implemented using useFormik() in <Formik/> component.

And well, this is all because of the nature of "Context API" in React which is known to be not performant. To me, only way to not rerender every single field in a form using Formik as we change anything in the main context (which we have to do, literally for anything) is using an api like use-context-selector just like Jared mentioned here #2746 (comment) or shouldComponentUpdate() everywhere.
So I don't understand the whole <Formik/> is more performant than useFormik() debate. What am I missing can you explain please?

[johnrom]

The concern that Jared is trying to raise is specifically that the useFormik + FormikProvider pattern is something we will never be able to optimize on behalf of a developer. We can optimize the internals of Formik however we want. For example, if you check out this PR, I've actually optimized the Formik component so that if a person doesn't pass render or a function child, it never subscribes to updates. This is something you cannot do via useFormik + FormikProvider as it stands. In that same PR, I removed all state from useFormik, because it will trigger renders and things. It doesn't go quite as far as I'd like in terms of optimization, but it's a start, but it would break everyone's code who currently accesses state from useFormik (we'd probably deprecate it instead). Thus, you can see why one might not recommend using useFormik as it is likely we'll have to provide a migration path to optimize renders.

[FBNitro]

(sorry for the late reply)

I have one more reason why I'm doing the useFormik +FormikProvider... my project has custom hooks where I need to pass in some of the formik functions. If I were to use the component I would no longer be able to use it with hooks.

Possibly there's a way I could pull it off using refs, I haven't considered it until just now.

[johnrom]

I agree it's useful to be able to modify the methods passed to FormikProvider. I've been thinking we can implement this functionality another way, though, using a Plugin API as outlined here: #3109

It's just a brainstorm at this point though. I still recommend exposing useFormik + FormikProvider pattern for now.

[dantman]

I'm in favor of 3 or 2. They make useFormik look clean to use, which makes it much more viable as a default pattern to recommend. And I do recommend making useFormik a default pattern.

Using useFormik can hoist the formik state up from a child of the route to the route itself right next to where the submit handler is implemented. This doesn't allow usage of hooks that use the user-friendly hooks like useIsSubmitting(). But it does otherwise allow for implementing route effects outside of the <form> without needing awkward workarounds. e.g. Page header based submit button that still responds to dirty and isSubmitting. A hook based blocker like usePrompt which cannot be used in a render prop without extra steps. A useEffect that resets the values in a section of a form when that section is removed.

[johnrom]

@dantman I would not trust FormikState returned by useFormik. This is because they are determined before the Effect which triggers updates to subscriptions (useContextSelector #2846, or subscriptions PR #3089 [I removed state from useFormik in subscriptions PR to prevent this]). There is a chance that this update won't make the same Batch as the effect, causing tearing between the two values. This will become more prominent in huge forms and in concurrent mode.

#3089 works around this by providing the subscription directly from the API, which convenience hooks like useIsSubmitting use themselves.

// outside of component
const selectIsSubmitting = (state: FormikState<any>) => state.isSubmitting;

// in component
const formik = useFormik(...formikProps);
// you can trust this value
const isSubmitting = formik.useState(selectIsSubmitting);

The only other way to implement this safely in a future proof manner would be a proxy, but I'm not sold on that, especially if each get() to formikState would create a new subscription.