🗺️ fetcher, submit, and Form Changes

[ryanflorence]

Important

This proposal has changed significantly since originally posted, some comments might not make sense

This proposal has three parts to it:

• Adding <Form navigate={false} /> to create a fetcher instead of a navigation
• Adding submit(data, { navigate: false }) to create a fetcher instead of a navigation
• Changing the internals of fetcher cleanup
• Introducing useFetcher({ key }), <Form fetcherKey> and submit(d, { fetcherKey })

Background

Today fetcher cleanup is coupled to the React lifecycle. When a component with a useFetcher unmounts and the fetcher is pending, the request is cancelled and the fetcher is removed from internal router state. This decision was made to prevent fetchers from being orphaned and causing memory leaks, and the UI lifecycle seemed like a good place to do it.

However, sometimes you want the request to persist beyond the lifecycle of the component, especially with "out of place" optimistic UI and components that open and close like dialogs and menu buttons. The current design makes these kinds of UI more difficult than they should be to build.

Apps need a way to simply toss out a fetcher and not care about the result in-place, but still have access to in useFetchers for optimistic UI and even be able to "pick it back up" in some other part of the UI.

For example, here is an implementation of Optimistic Add today that we think is overly cumbersome and leaks implementation details of fetcher lifecycles.

First is a list that reads loader data and renders all three things: the form, the pending items, and the items from the database.

function List() {
  // real items from the DB
  let { items } = useLoaderData();

  // manage some pending states
  let [submissions, setSubmissions] = useState<FormData[]>([]);

  return (
    <>
      <form
        onSubmit={(e) => {
          event.preventDefault();
          // push submission in to cause a new PendingItem to render
          setSubmissions([
            ...pendingSubmissions,
            new FormData(e.target),
          ]);
        }}
      >
        <input type="text" name="name" />
        <button type="submit">Save Item</button>
      </form>

      {/* Render the pending submissions */}
      {submissions.map((formData, index) => (
        <PendingItem
          key={index}
          formData={formData}
          onComplete={() => {
            // remove the completed pending item
            setPendingColumns(
              pendingSubmissions.filter((f) => f !== formData),
            );
          }}
        />
      ))}

      {/* Render the real items*/}
      {items.map((item) => (
        <Item key={item.id} name={item.name} />
      ))}
    </>
  );
}

The PendingItem component only exists to keep the fetcher alive until the request is complete.

function PendingItem({ formData, onComplete }) {
  let fetcher = useFetcher();
  let name = formData.get("name");

  useEffect(() => {
    fetcher.submit(formData, { method: "post" });
  }, []);

  useEffect(() => {
    if (fetcher.state === "idle" && fetcher.data) {
      onComplete();
    }
  }, [fetcher]);

  return <Item pending name={name} />;
}

And finally the Item component isn't relevant, we'll just assume that might change what it renders based on being an optimistic version or not.

This extra work is only needed because the fetcher lifecycle is coupled to the component lifecycle. There are also some bugs for the observant reader that always creep in when you synchronize state.

Proposal

<Form navigate={bool}> and submit(data, { navigate: bool })

Today <Form> always navigates and <fetcher.Form> creates a fetcher and tracks its state. This proposal adds a navigate prop to <Form> that allows it to create a fetcher instead of navigating.

<Form navigate={false} method="post">
  <input name="title" />
</Form>

Now instead of causing a navigation, an internal fetcher will be created, accessible from useFetchers.

function SomeComp() {
  let [fetcher] = useFetchers();
  fetchers && fetcher.formData.has("title"); // true
}

This allows forms to simply kick off a fetcher and not care about the result, decoupling the fetcher from the lifecycle so that optimistic UIs can render until they are filled in with loader data after revalidation, or conditional UI like dialogs can simply close without cancelling the request and subsequent revalidation.

On the imperative end of the spectrum, submit is simply the imperative version of <Form>. It works the same here: use navigate: false and a fetcher will be created instead of a navigation.

Fetcher Cleanup changes

If <Form navigate={false}> can kick of fetchers that live beyond the lifecycle of the component, we need a new way to clean them up. This proposal changes the internals of fetcher cleanup to decouple it from the React lifecycle.

Today fetcher.data is managed internally by the router outside of React (which is why the React lifecycle for cleanup made sense).

This change will move the "complete" state to React, allowing the router to simply track fetchers while they are pending, giving us a new point of garbage collection decoupled from rendering.

This might be a "breaking bug" (😅) for useFetchers. In some cases, useFetchers returns fetchers that are "idle" and have fetcher.data available on them even though it was never intended to do so. Even the docs explain it differently than the behavior.

Most use cases we've seen and authored check some sort of pending information like fetcher.formData so we don't expect it to affect very many apps. It might, so we're still considering putting this all behind a future flag, but we'd rather not.

Even if it does lead to undesired behavior, useFetchers is ephemeral, so it's unlikely your app will "break break", just some ephemeral states you used to have won't be triggered anymore. We think you'll like the amount of code you can delete by moving to the API updates in this proposal.

useFetcher({ key })

Lastly, this proposal adds a new key API for fetchers that allows you to pick up a fetcher in a different part of the tree from where it was created, or even share it across the tree.

let fetcher = useFetcher({ key: 123 });

Additionally, you can use keys with Form and submit:

<Form navigate={false} fetcherKey="123" />;
submit(formData, { navigate: false, fetcherKey: "123" });

Now an optimistic version of a record can pick up the fetcher that created it, or two distant parts of a tree can share a fetcher.

The fetcher will also have a new prop on fetcher.key which can make it easier to filter out the fetchers you want instead of using formData.

Examples

Optimistic Add to List

We can revisit the optimistic add code and see how simple it gets:

function List() {
  let { items } = useLoaderData();

  // get the optimistic items from the fetchers
  let submissions = useFetchers()
    .filter((fetcher) => fetcher.formData?.get("intent") === "add-item")
    .map((fetcher) => Object.fromEntries(fetcher.formData));

  return (
    <>
      {/* kick off a fetcher instead of navigating */}
      <Form navigate={false} method="post">
        <input type="text" name="name" />
        <button type="submit" name="intent" value="add-item">
          Save Item
        </button>
      </Form>

      {/* Render everything together, optimistic and real */}
      {submissions.concat(items).map((item, index) => (
        <Item
          key={item.id || index}
          pending={Boolean(item.id)}
          name={item.name}
        />
      ))}
    </>
  );
}

Form will create new fetchers, they'll be rendered the duration of their request/revalidation cycle, and then will be filled in by loader data when the action is complete.

For some serious React you could create client IDs and use them as the element key prop and then they could be fully interactive, as long as the backend understands it.

Optimistic Move

Imagine a trello-like interface where cards can be dragged from one column to another. The card that is dragged does not initiate the fetch, but rather the card being dropped does. The onDrop even can get the ID of the dragged card and simply kick of a fetch that that id and key.

function Card({ id }) {
  let submit = useSubmit();

  function handleDrop(event) {
    let { cardId } = JSON.parse(
      event.dataTransfer.getData("application/move-card"),
    );
    submit(
      { cardId: data },
      {
        navigate: false,
        // use a key so it can be picked up by the optimistic card
        key: `move-card:${cardId}`,
      },
    );
  }

  return <div onDrop={handleDrop} />;
}

Now the optimistic card in the new column can pick up the fetcher to render pending states or even use it for other operations.

function Card({ id }) {
  // pick up the fetcher from the other column
  let fetcher = useFetcher({ key: `move-card:${id}` });
  let submit = useSubmit();

  function handleDrop() {
    // ...
  }

  return (
    <div
      // use it for pending UI, even if it's already optimistic
      className={fetcher.state === "idle" ? "" : "pending"}
      draggable
      onDrop={handleDrop}
      onDragStart={handleDragStart}
    />
  );
}

Dialogs and Menus

Dialogs and menus can simply be a form that closes on submission and the fetch won't be cancelled.

function SomeRoute() {
  let [edit, setEdit] = useState(false);
  return (
    <div>
      <h1>Some page</h1>
      {edit ? <MyModal onSave={() => setEdit(false)} /> : null}
    </div>
  );
}

function MyModal({ onSave }) {
  return (
    <Modal>
      <Form navigate={false} onSubmit={onSave}>
        <label>
          <input type="checkbox" name="watermelon" />{" "}
          <span>I would like my watermelon pre-sliced</span>
        </label>
        <button type="submit">Save</button>
      </Form>
    </Modal>
  );
}

[ShafSpecs]

Love this RFC. +1 from me.

The main pro for me personally is the removal of the need for extra states and effects in your app to track fetcher state and data. Asides from that, I see no issue with this RFC since it doesn't deduct anything from original implementation

[ryanflorence]

Should note that useNavigation is basically a singleton that already has these capabilities. It doesn't matter which <Form> started the mutation, useNavigation().formData is available everywhere, so new components can pick up the pending states and unmounting components don't cancel the fetch.

[bronifty]

That's magical. I was going to say it looks like you're inserting a cache key somewhere, but you're passing the formData around as a global instead. Very cool.

[kentcdodds]

Yep. I'm on board! Thanks for solving this with such a simple solution

[zachdtaylor]

I like it! This'll make a few things I'm doing a lot simpler.

[rossipedia]

I was kinda "oh yeah I can see this being useful"... until this

The persist option can also take a key:

let fetcher = useFetcher({ persist: "abc" });

With this key, any other calls to useFetcher with the same key will share the same underlying fetcher, sharing the state and lifecycle.

took me over the edge into full blown convert. Yes. Please.

[brophdawg11]

I chatted with Ryan and just we're probably going to split persist out into useFetcher({ key?: string, persist?: boolean }) so you have the full set of capabilities. key is for sharing, persist is for clean up behavior. Otherwise it was ambiguous when persist:string fetchers would clean up.

[rphlmr]

What would happen for fetcher.load?

[sergiodxa]

Nothing in the RFC suggest it will removed, it should keep working as usual.

[JClackett]

Yes please! all my fetchers that are in collapsable menu's will now just work without any workarounds 🙌🏾

[devstojko]

Perfect! This will also solve issue with form in dialog. Now you can unmount dialog instead of hiding it while fetcher is doing it's job.

@ryanflorence after this we need promise / lifecycle for fetchers and that's it. I can get rid of ugly useEffects

[ryanflorence]

If you had access to the promise, you would now need useEffect and useState to do anything useful with it--unless you want bugs in your app by messing with promises in event handlers. We don't expose the promises so that we can do cancellation correctly and avoid race conditions and other bugs that come with it, all things you would need to do yourself with a promise.

[JClackett]

Even just an onComplete callback to the useFetcher would eliminate essentially all my useEffects, does this have to with promises?

[devstojko]

@ryanflorence Yes you are right, we don't want to deal with that.
The issue that we are facing in our app is when you have

• dependent actions in dialog
• get options on demand before opening dialog

Recently we had to implement like:

Open dialog (modal)

You have 3 select options.

1. When you select first useFetcher to load options for second one => pass result to second select options => select second select => useFetcher to call another loader to get data for third select.

2. There are also situation where we have multiple selects in dialogs and I want to load (4 fetchers and get data) once user click button to open modal instead of passing them as props and load them initially in loader. (because we don't know if user is going to click button and consume data).

So this is why I am looking for "proper" solution for this kind of job. Using useEffect to track status for fetcher is tricky sometimes and devs in my team often includes "suggested" props in dep array and you get bugs.

Also there are situations when you have case above (get response from first dialog) and when it's done open another one with returned data...

I just want an "easy" solution when you useFetcher to know when it finished job without using useEffect.

Problem that you are going to solve now with this persist change:

• we have to define all fetchers in modals in order to pass them to the forms so we can track fetcher status and when it finish job - show toaster notification, close modal (Unmount from dom) instead of just hiding it

• sometimes you want to close modal right after you submit fetcher (atm you can just "hide" it) instead of unmounting because it will cancel fetcher

[devstojko]

What if useFetcher has callback function where it can emit changes through callback value (same useEffect structure response) and then inline in callback you can use same condition that you would use in use effect to get what you want and need.

[ryanflorence]

@JClackett If a fetcher is inflight, and the user navigates away, unmounting the component, you have an opportunity to do cleanup in useEffect.

If we provided onComplete we also need a cleanup mechanism. In many ways it's just recreating useEffect.

let fetcher = useFetcher();

useEffect(() => {
  if (fetcher.data?.ok) {
    // this is `onComplete`
    return () => {
      // with cleanup when you unmount
    }
  }
}, [fetcher]);

Also, Remix might cancel a fetcher if you submit/load it twice in a row, which is another time you need cleanup.

useEffect properly handles locally scoped variables when the effect requires other variables from your component (like some local state + state of the fetcher).

Non-fetcher state changes, cleanup, and the component lifecycle all need to be considered together. Adding onSuccess, onComplete, etc. is just working against the grain in React and would definitely need to synchronization and stale value bugs in your components.

[otaviobarros]

Perfect, exactly what I needed, no more workarounds and state hoisting 🙌

[sergiodxa]

This will enable a nice pattern here a fetcher could be defined globally with a Symbol key:

const key = Symbol()
export function useMyFetcher() {
  return useFetcher({ persist: key })
}

Now useMyFetcher could have a unique persisted key that nothing else can use, this can be useful for @kentcdodds' Full Stack Components pattern.

// app/routes/api.something.ts
const key = Symbol()

export async function loader() {
  return json(...)
}

export function Something() {
  let fetcher = useFetcher({ persist: key })
  return ...
}

And with this you can import Something which already knows how to fetcher the loader and it will always be a single instance.

If it needs to be rendered in a list, we could also use Symbols by setting it in a state instead of a UUID.

function Something() {
  let [key] = useState(() => Symbol());
  let fetcher = useFetcher({ persist: key });

  return ...
}

And now each instance can have a unique key

[kentcdodds]

With that in mind, it might be useful to be able to initialize the fetcher with data.

[frontsideair]

In a side project of mine, I have a custom Form wrapper that takes an additional handler prop, which is basically like this:

function Form({ handler, ...props }) {
  const fetcher = useFetcher();
  
  useEffect(() => {
    // call handler optimistically with `fetcher.formData` or `fetcher.data`
  }, [handler, fetcher])
  
  return handler ? <Form {...props} /> : <fetcher.Form {...props} />

I take a look at this component from time to time and don't like it a lot, but it provides some kind of symmetry and I can add optimistic stuff by adding a single handler. <Form navigate={false} /> part of the proposal reminds me of this need and may allow me to delete this hack.

[sergiodxa]

With Form supporting navigate={false} and fetcherKey, why would I need useFetcher?

Also how should I access the Form data if it used a fetcher? I imagine I can't use useActionData anymore, same for useNavigation. Will I need to grab it from useFetchers?

[ryanflorence]

With Form supporting navigate={false} and fetcherKey, why would I need useFetcher?

useFetcher is when you need to read the state. If it's all local and unmounts don't matter, you just keep using it the way you always have.

navigate={false} is to send off a fetcher from somewhere in the UI that you don't care about the state. Some other spot, usually optimistic UI, might care about the state. If it does, you bring in fetcherKey to the originator and continue to useFetcher({ key }) to "pick it up". If the optimistic UI doesn't need the fetcher state, you don't need useFetcher.

[ryanflorence]

Also how should I access the Form data if it used a fetcher?

It's still on useFetcher. So if it's all local, nothing changes.

If a <Form navigate={false}> kicks off a fetcher, you'd have access to formData in useFetchers and well as any useFetcher({ key }) that picks it up.

useActionData and useNavigation aren't involved at all with a <Form navigate={false}>.

[brophdawg11]

This is being implemented in remix-run/react-router#10949 and #7704

[brophdawg11]

The above PR has been superseded by:

• Add useFetcher(key) and <Form navigate={false}> react-router#10960
• Add fetcher data layer react-router#10961
• Add future.v7_fetcherPersist flag react-router#10962

[ryanflorence]

I just worked with an experimental version of this and it's :chefs_kiss:

There were some use cases that were way too difficult that I'd been wanting to solve and this nails it.

https://twitter.com/ryanflorence/status/1715440901378720013

[bluefire2121]

I like that this would get rid of fetchers and forms with stale data, but I think this is a big enough change that it should be a feature flag. What would be the need for <fetcher.Form> after this change? The way I understand it, <fetcher.Form> = fetcher and <Form navigate={false}> = fetcher. Is that correct?

[sergiodxa]

I asked something similar here #7698 (comment). While <form navigate={false}> will work as a fetcher you will need to find the data or state in useFetchers so using <fetcher.Form> is going to be useful for when you need the data or state in your UI.

[ryanflorence]

Yep. fetcher.Form gives you that state "in place" and those use cases don't go anywhere and no behaviors change.

This proposal is about when you need that state "out of place" and don't want the originating "in olace" UI to cancel it if it unmounts.

[sergiodxa]

This will also enable another thing, reset a fetcher.

let [key, setKey] = useState(() => Symbol())
let fetcher = useFetcher({ key })

function resetFetcher() {
  setKey(Symbol())
}

Now if you call resetFetcher a new symbol will be created which will be considered a different key and will make useFetcher get a new instance.

[thosmos]

This is still a workaround for a missing fetcher.reset(). It's reasonable to want to tie the key to a data object ID, like if you're editing a user record with id 123 then you'd want to be able to use that as the key. Using this workaround means losing that just to trick the fetcher into resetting its .data field. I'm surprised that .reset() is such a resisted feature, when it tracks directly to the underlying html form functionality that you actually are blocked from by using a fetcher.Form with any reactive UI attached to the .data field.

Here's a more detailed rant about the missing .reset() on a closed PR thread: #3551 (comment) and another comment here: #2749 (comment)

[brophdawg11]

This was released in React Router 6.18.0 and Remix 2.2.0

[kentcdodds]

Just gotta say these improvements are killer 🤘 Great work team!

[Shadowfaxenator]

<Form navigate={false} /> how this works if JS is disabled? Won't it work? Or it'll just post data with navigation?

[brophdawg11]

Correct - it's the same as if you used <fetcher.Form> so it will post to your action as a document navigation

[rodolphoasb]

Was fetcher.key implemented?

Quoting the original RFC: "The fetcher will also have a new prop on fetcher.key which can make it easier to filter out the fetchers you want instead of using formData."

I'm trying to use that to create an optimistic mutation with:

  if (fetcher.formData?.has("value")) {
    value = String(fetcher.formData.get("value"));
  }

[brophdawg11]

Fetchers returned from useFetchers have a key property - this is the intended use-case for "filtering" as per the original RFC.

When using useFetcher( key: 'whatever' }) - there is no need to filter since you already have the specific whatever fetcher, so key is not exposed there. The key you pass to useFetcher effectively does this filtering/finding internally.

[heivo]

Is there any way to still manually cancel a request with this? Previously it was possible to just unmount the component that renders the fetcher.

A use case might be a large file upload that can be aborted by the user.

[brophdawg11]

Hm, right now there might not be a super ergonomic way to do that. Off the top of my head - if you were to issue a separate request from the same fetcher key it would abort the in-flight one. You could use a clientAction/clientLoader then to "intercept" that second request and just no-op without going to the server.

Something like:

export async function action({ request }) {
  // handle large file upload
}

export async function clientAction({ request, serverAction }) {
   // If we see an abort query param, then we don't actually want to submit anything here
   if (new URL(request.url).searchParams .has('abort')) {
     return;
  }
  return await serverAction()
}

function Component() {
  let fetcher = useFetcher({ key: 'something' })l

  // To submit the file  
  fetcher.submit(data, { method: 'post', encType: 'multipart/form-data' });

  // To abort an ongoing upload
  fetcher.submit(null, { method: 'post', encType: 'multipart/form-data', action: '.?abort' });
}

It could be better to use a fetcher.load and a clientLoader too to avoid triggering other revalidations

[heivo]

That's an interesting idea, I was not aware that a client action cancels the previous request when it doesn't call the server action. I'll try that, thank you very much.