blog/react-query-and-forms

[utterances-bot]

React Query and Forms | TkDodo's blog

Forms tend to blur the line between server and client state, so let's see how that plays together with React Query.

https://tkdodo.eu/blog/react-query-and-forms

[joshribakoff]

A better idea might be to just highlight values that are out of sync with the Server State and let the user decide what to do.

I agree! Or another pattern is to use timestamps or include the before/after state in the mutation, the server can detect a conflict and ask the user what to do! Another pattern is to use websockets to keep state in sync across multiple clients, or display a warning “Josh is also editing this record”

[Moshyfawn]

Great great article, as always! And great insight into RQ and forms integration insight!

I was splitting the form and the form data call before I started using suspense. With, say, modal forms, it's quite convenient to get the form data inside the actual form.

What suspense allowed me to do is to suspend the whole modal content until the data is present and render a, say, Skeleton layout in place of the form. Once I get the data, the form's gonna render and get the fresh non-undefined defaultValues.

On the topic of undefined data (and I know the article isn't about RHF; just some additional info): at RHF, we recommend to reset the form's values (including defaultValues) when the data arrives as a side-effect like

const { data } = useQuery()
const {} = useForm()

useEffect(() => {
  if (data) {
    reset(data))
  }
}, [data), reset])

P.S. Thx for choosing RHF and your kind about the package! ❤️

[babycourageous]

@Moshyfawn @TkDodo love seeing maintainers of my two fave React libraries crossing paths. Just popping in to say thanks to you both for such awesome work!!

[TkDodo]

@Moshyfawn that suspense idea is awesome, thanks for pointing me in that direction. I haven't really used suspense much, and for this case, it's pretty perfect, as it simplifies the code and takes away the unwanted component split. Solid advice 👍

at RHF, we recommend to reset the form's values (including defaultValues) when the data arrives as a side-effect

we have discussed this on twitter as well, just for posterity: I think this is good advice with "traditional" data fetching that only happens once. However, this can be dangerous with background refetches. That effect resets your whole form to the server state whenever data changes, even if the user has already started to modify that data. It's similar to the non-solution I have shown in putting props to useState. I know that react-query challenges / changes the way we view state, and you've also mentioned that RHF doesn't have an idiomatic way at the moment to reflect these cases. I would gladly work together with you to come up with an api that would make that possible :)

[babycourageous]

@TkDodo @Moshyfawn wow - i have been following the reset in effect pattern and not until now even considered how background refetches would impact that. Wooooops. Dunno how helpful I'll be but also willing to contribute any thoughts, observations, etc as a user of both these awesome libraries.

[ManuRodgers]

@TkDodo
what makes you choose react-hook-form over formik

[joshribakoff]

@ManuRodgers formik uses “any” in their types so you lose some type safety when compared to react-hook-form, which is why I advocated for and switched libraries in my project personally.

[Moshyfawn]

@TkDodo: I haven't really used suspense much, and for this case, it's pretty perfect

Yea, suspense does up the game in regards to the data flow and has helped me a lot with simplifying the code along with improving the UX, for forms especially. Does require a bit of a mindset change, tho. What what in React doesn't :P

I think this is good advice with "traditional" data fetching that only happens once

First off, thx for clarify this point. That's exactly the case.

That's interesting that "effects like these generally [considered] an anti-pattern". RHF heavily relies on it to "reset" the form with the async "default values" that come from backend or "whatever async else".

As you've correctly mentioned, "RHF doesn't have an idiomatic way at the moment to reflect ["data syncing"]. RQ is the perfect tool to look at to try improving the DX (or even the UX) in this field.

I would gladly work together with you to come up with an api that would make that possible :)

Thank you, Dominik! I appreciate it!

[Moshyfawn]

@babycourageous: Dunno how helpful I'll be but also willing to contribute any thoughts, observations, etc as a user of both these awesome libraries.

As React 18 is here, we might probably discuss including the suspense in the scope of recommended patterns to deal with async data for default values.

Now, that doesn't solve the whole ever-changing backend cache data and how to deal with form values background re-fetching; that's where every input counts (pun intended lol) ;)

P.S. I know, I kinda hijacked the RQ blog post on the ground of having RHF as a form management solution for the example, but the concepts and the ideas behind managing "remote" data while user interaction is universal

[Moshyfawn]

@ManuRodgers: what makes you choose react-hook-form over formik

RHF stands out as a form management solution that tries to embrace the native web API as closely as possible over "just" using React, which brings out of pocket optimization measures like uncontrolled inputs and native field level validation.

And it's not a biased plug as RHF maintainer lol. I've refactored a giant monolithic B2B app before I looked into working closely with RHF community :P

[Noitidart]

I don't understand why we use useMutation in the first examples. I still don't understand what useMutation gives us over axios.post. Yes we can see if any mutation is in progress globally, but typically that's not used as much. Is there any benefits of useMutation here over axios.post?

Still strugling to learn useMutaiton, great stuff though.

[TkDodo]

@Noitidart I have a separate blog post about mutations: https://tkdodo.eu/blog/mastering-mutations-in-react-query

In a nutshell:

• you can track loading and error states declaratively, not only globally, but also locally. E.g. disable the submit button while the mutation is loading
• has convenient callbacks for onSuccess / onError / onSettled to give you the option to invalidate relevant queries, or perform redirects to other pages
• the callbacks allow for returning promises, which will be awaited - also great for invalidation.
• the onMutate + the context it returns and passes to the other callbacks is very efficient for doing optimistic updates

[Noitidart]

Oh thanks that helps a lot! in the react-hook-form situation, it already has its own success/loading/error on the submit part, so was thinking useMutation here was being extra but not sure.

[Moshyfawn]

@Noitidart, RHF tracks it's own form submission state and is not bound to RQ or whatever else operation you're running inside onSubmit. It can be 100 async calls using RQ, or a mutation and some analytics call after, that has nothing to do with RQ.

You can use RHF isSubmitting state as an aggregated loading state of all your async operations instead of doing something like

const isSubmitting = isMutationLoading || isAnalytics || is1000MoreRequests

Think of it like RHF isSubmitting state is the form's submission state and the mutation isLoading state is a loading state of just this one mutation operation. It might not seem so different when you have a simple backend request inside onSubmit, but as your app's functionality grows, you can start to see the difference.

The thing about RQ mutation here would be that you can invalidate your specific cache entry inside the mutation "life-cycle" (onMutate, onSuccess, onError, onSettled), which is super handy if you're using RQ through out your whole app.

P.S. What I said about isSubmitting state is also applicable to all the other success and error states you've mentioned. I just hadn't have my coffee yet lol

[Noitidart]

Thanks very much @Moshyfawn this is also super helpful. Haha at coffee.

A note about invaliding cache entry. useMutation just allows doing that from inside its lifecycle. If I didn't useMutaiton I still could invalidate from error-handler of handleSubmit I'm thinking.

[Moshyfawn]

@Noitidart: A note about invaliding cache entry. useMutation just allows doing that from inside its lifecycle. If I didn't useMutaiton I still could invalidate from error-handler of handleSubmit I'm thinking.

Sure! it's just if you want to reuse your mutation in multiple places, it better to encapsulate your data handling logic inside a custom reusable hook like

function useUpdateTodo() {
  const queryClient = useQueryClient()
  const { mutate } = useMutation(updateTodo, {
    onSuccess: () => {
      queryClient.invalidateQuery(["todos"])
    }
  })
  
  return {
    updateTodo: mutate
  }
}

and call it in different places like

const { updateTodo } = useCreateTodo()
// INFO: in a "Update Todo" form
const onSubmit = (todo) => {
  updateTodo(todo)
}

// INFO: somewhere else, like a data grid
const onTodoCellUpdate = (todoId, todoTitle) => {
  updateTodo({ todoId, todoTitle })
}

It's even more prominent when you want to do an optimistic update: all your data handling logic will reside in your custom mutation hook; you just need to call the mutation method and handle the UI updates on success in your component, like closing a form dialog or highlighting an updated data grid entry

// INFO: inside the useCreateTodo hook
const { mutate } = useMutation(updateTodo, {
  onMutate: (todoPayload) => {
    // INFO: pseudo-code _(+ might have bugs lol)_. You'll need to do a bit more to gracefully handle an optimistic update
    const { todoId } = todoPayload
    const currentTodos = queryClient.getQueryData(["todos"])
    const updatedTodoIndex = currentTodos.findIndex(currentTodo => currentTodo === todoId)
    let newTodos = [...currentTodos]
    newTodos[updatedTodoIndex] = todoPayload
    queryClient.setQueryData(["todos"], newTodos)
  },
  onSuccess: () => {
    // INFO: handle request success
  },
  onError: () => {
    // INFO: handle request error
  },
  onSettled: () => {
    queryClient.invalidateQuery(["todos"])
  }
})

As you can see, it's quite a bit of code, which is not pleasant to write every time you mutate a value. With the mutation logic encapsulated like above, you can simply do

const onSubmit = (todo) => {
  updateTodo(todo, {
    onSuccess: () => {
      closeFormDialog()
    }
  })
}

Besides all the points above, having your data handling logic in one place (a custom mutation hook) is just a best practice and much easier to maintain.

Hope that clears things for you ;)

P.S. I did have coffee! xD

[Noitidart]

Thanks @Moshyfawn that is such a helpful reply! I was using both RQ and RHF and struggling on how to cleanly split things, thanks very much! Haha at the coffee!

[Moshyfawn]

I'm glad I could help! ;)

[InSeong-So]

@TkDodo It's an impressive article! It helped me a lot. Can I translate the article related to React query?

[TkDodo]

sure! If you're hosting the translation somewhere, I'm happy to link to it as well :)

[InSeong-So]

Thank you so much, @TkDodo 🥳!! I'll link up the translated article here.
(My domain is about to expire, so I will revise it later🙏)

• #1: Practical React Query
• #2: React Query Data Transformations
• #3: React Query Render Optimizations
• #4: Status Checks in React Query
• #5: Testing React Query
• #6: React Query and TypeScript
• #7: Using WebSockets with React Query
• #8: Effective React Query Keys
• #8a: Leveraging the Query Function Context
• #9: Placeholder and Initial Data in React Query
• #10: React Query as a State Manager
• #11: React Query Error Handling
• #12: Mastering Mutations in React Query
• #13: Offline React Query
• #14: React Query and Forms

[TkDodo]

thank you 🙏 . I've just merged the PR to add the translations, they should be up soon :)

[Calebsworld]

Hey I really enjoyed this article! I am a new player in the React community and I have been playing around with RHF and React Query for the first time in order to build a personal blog. I am trying to use the default values approach to set default values to an update form that will bring in server data. I am having trouble using default values for an array of objects. I am using the useFieldArray API by RHF. I was hoping someone could point me in the right direction on how to dynamically insert the server data into each input field.

[TkDodo]

Can you maybe show a codesandbox reproduction?

[Calebsworld]

Yes, I’ll create one shortly!

[Calebsworld]

I have never used codesandbox and I am having trouble getting my sandbox to render my project after importing via github repo. However, here is the link...
https://codesandbox.io/s/blog-app-sandbox-hxbwq7

[Moshyfawn]

I'm from mobile, so I can say for sure, but if you're having trouble with resetting field array values in your WriteBlogForm, make sure to include the isSubmitSuccessful value in the useEffect deps array instead of the formState proxy object and provide the defaultValues to the reset method

[Calebsworld]

So my issue lies in the UpdateBlogForm. I am trying to reset the values of my form inputs after I get the data from the server. My WriteBlogForm is functional, however I just moved the reset() and navigate() function calls to be executed only if the mutation is successful using the optional object.

[coryhouse]

Great post! There's a minor typo on line 15 in the last code snippet:

// rest client state back to undefined

I believe you mean "reset client..."

[Moshyfawn]

TkDodo/blog#165 just 'cuz I was snooping through the blog code for inspiration :P

[shubham-y]

In an app, using react hook form and react query, which state is suggested to use to prevent Double Submit Prevention the React Query isLoading prop returned from useMutation or React Hook Forms isSubmitting prop returned from useForm ?

[TkDodo]

I guess they'll both work fine

[Moshyfawn]

Depending on your use-case, using useMutation().isLoading can be sufficient enough.

The RHF formState.isSubmitting "aggregates" the promises inside onSubmit; if you have multiple async operations inside onSubmit, you don't need to track all their states like isFirstLoading || isSecondLoading || isThirdLoading: formState.isSubmitting is true until all promises are resolved inside onSubmit.

[ramseylove]

Working with forms has to be the most frustrating thing when using RQ. I always use to reuse my forms in create and edit mode, especially with the complex ones but find it almost impossible now with RQ. I constantly get undefined data, so i gave up doing this for the most part, found I wasted a lot of time.

Do you or anyone else use the same forms for edit/create and also have a successful strategy you want to share? I really hate having a separate create and edit forms.

[TkDodo]

I can take a look if you can show a codesandbox example

[ramseylove]

https://codesandbox.io/s/compassionateuser-agnesi-37620p-37620p?file=/src/component/UserForm.tsx

Here is a sandbox I set up. Using some of your tips, I think i have something that works. Haven't been able to really test it well.

I actually created the sandbox mostly because the real project i'm working on has RHF issues dealing with a dynamically created array of nested fields.

[xfsnowind]

@ramseylove I think I do have the same situation with you, need to use the same form in create/edit. And I did have the problem of defaultValues undefined. And it got solved by useForm's field values. You can check my comment about it. (it's just right under)

[xfsnowind]

Hi,

Thanks for the blog and actually I did meet the problem that value is undefined defaultValues.

But it got solved in a better way, instead of using reset like what @Moshyfawn mentioned. The thing needs to be done is

1. Add a defaultValues to useForm which would give us better type checking during the coding
2. Add the query's data as values to useForm which would update the forms value with the external or server data

Like this:

  const facilityCameraEventsQuery = useFacilityCameraConfigurationQuery()

  const methods = useForm<CreateEventFormValidationSchemaType>({
    resolver: zodResolver(createEventsFormSchema),
    mode: 'onChange',
    defaultValues: FormDefaultValues,
    // NOTE: this values will replace the default values when we fetch the data from query
    // to avoid default values being undefined
    values: facilityCameraEventsQuery.data,
  })

You can find the explanation in the field values in here.

[Moshyfawn]

values is a somewhat recent addition to the RHF API that didn't exist at the time this post was written 😉 Actually, the discussion we had with @TkDodo when he was doing his research for this blog post spawned the idea for the values API 😊

[xfsnowind]

Ah, ok, understand. Then thanks for the blog.

[natethelen]

Do you know of a way to interrupt the updates from values? There is a case when someone is editing the form and RQ auto-gets newer data from the DB (which then overwrites the form if using values).

[natethelen]

Sorry just found resetOptions.keepDirtyValues. Nevermind!

[bryan-davis]

Do you know what the best practice is for handling search forms? In a nutshell, I want to take user input from a form and pass it to the queryFn from useQuery after the form is submitted. I'm new to react query and haven't been able to find an example for something like this even though it feels like it should be a fairly common need.

I have a sandbox showing a more traditional approach https://codesandbox.io/s/ancient-rgb-3q141l, but I'm not sure how to handle it with useQuery. I can make it work with useMutation as seen in this sandbox https://codesandbox.io/s/brave-ramanujan-o5fl2f but I'm not sure if this is a good practice as I'd be fetching data, not mutating it.

[TkDodo]

The bad thing about doing useMutation is that you have no caching. So every click on Search will trigger a new request, while with useQuery, you get caching depending on your staleTime setting.

It'd be nice if react query had a deferred query that could be called on demand with parameters like useMutation provides. Maybe it already does and I'm just not aware of it?

It's not possible because your input needs to be a part of the QueryKey. New QueryKey means new cache entry. If we only had one cache entry named 'search' and would write to it with different input, caching would be worse and we would get race-conditions.

I need to run an equality check on the form data and if the form is equal then call refetch

This is mainly a form state management problem. If you use something like react-hook-form, I think they have dirty detection, so you know when a form was changed.

[bryan-davis]

I created another sandbox https://codesandbox.io/s/reverent-microservice-pdo0kd that has the query disabled (instead of doing Boolean(form) and uses useEffect to call refetch when the form is updated during the handleSubmit function. This seems to work but is still more verbose than desired.

@TkDodo Do you have any plans on adding an example for this search form scenario? I think having a form with multiple inputs with a Search button is common enough that a best practices example would be beneficial. I didn't see anything in the React Query documentation, but may have missed it.

[Moshyfawn]

I created another sandbox https://codesandbox.io/s/reverent-microservice-pdo0kd that has the query disabled (instead of doing Boolean(form) and uses useEffect to call refetch when the form is updated during the handleSubmit function. This seems to work but is still more verbose than desired.

@TkDodo Do you have any plans on adding an example for this search form scenario? I think having a form with multiple inputs with a Search button is common enough that a best practices example would be beneficial. I didn't see anything in the React Query documentation, but may have missed it.

I don't think you need a side-effect or a mutation to update your search query.

It's a good practice to store your search params inside a global store - URL. But even if you're using a client store like React state, you only need to update that state for Query to detect a change and pass in an enabled condition to it to cover the "initial" state.

Here's a quick example:

function Search () {
  // INFO: url is an imaginary object containing current URL search params (can be a React state or any other store) 
  const search = url.searchParams.get("search")

  const { data } = useQuery({
    queryKey: ["listings", "list", "search", search],
    queryFn: () => getListings(search),
    enabled: !!search
  })
  // INFO: displaying form related logic in the same component for brevity
  const { handleSubmit } = useForm({ defaultValues: search ?? { rent: "", sale: "", zipCode: "" } })
  
  const onSubmit = formData => url.set("search", formData)
  
  return (
    <main>
      <form onSubmit={handleSubmit(onSubmit)}>...</form>
      <Table data={data} />
    <main>
  )
}

[bryan-davis]

@Moshyfawn

But even if you're using a client store like React state, you only need to update that state for Query to detect a change and pass in an enabled condition to it to cover the "initial" state.

One key difference for my use case is that I don't want the results cached and want the query to execute whenever the user clicks Search, even if the form didn't change.

I updated my previously mentioned sandbox to the code below (https://codesandbox.io/s/gifted-farrell-81frb3), which seems similar to your example. It will execute the search the first time the form is filled in, but not again unless the form values change.

With useEffect in my previous example (https://codesandbox.io/s/reverent-microservice-pdo0kd), the form will always search when the Search button is clicked, even if the form values didn't change. If there's a way to do this without useEffect or checking all of the form values and calling refetch then it'd be helpful to see an example.

export default function App() {
  const [formData, setFormData] = useState(null);

  const { isFetching, isSuccess, data } = useQuery({
    queryKey: ["search", formData],
    queryFn: () => getListings(formData.type, formData.zipCode),
    enabled: Boolean(formData),
    refetchOnWindowFocus: false,
    cacheTime: 0
  });

  const handleSubmit = (data) => {
    setFormData(data);
  };

  return (
    <div className="App">
      <SearchForm onSubmit={handleSubmit} isFetching={isFetching} />
      {isFetching && <span>Fetching data...</span>}
      {isSuccess && (
        <pre>
          <code>{JSON.stringify(data, null, 2)}</code>
        </pre>
      )}
    </div>
  );
}

[TkDodo]

One key difference for my use case is that I don't want the results cached and want the query to execute whenever the user clicks Search, even if the form didn't change.

You can create a check for that:

const handleSubmit = (data) => {
  if (data === formData) {
    refetch();
  }
  setFormData(data);
};

yes, the === check might not work if data is a different reference each time the button is clicked, but then you have to diff it yourself. We do export our hashKey util if you want to do the same comparison that react-query is making for the QueryKey:

https://codesandbox.io/p/sandbox/wonderful-surf-2q8f0n?file=%2Fsrc%2FApp.js%3A1%2C1

[AayushKarki714]

I think stale time Infinity can really get you out of sync with your server state, It need's to be used with invalidate Queries and isFetching flag to make sure that the form is getting the latest data after being updated

[h-jennings]

It looks like in RHF V7 you now have additional options that you can pass to reset which would allow you to achieve the same result covered in the Keeping Background Updates On section without having to use a <Controller /> component.

Here's what that might look like now with these new APIs:

function PersonDetail({ id }) {
  const { data } = useQuery({
    queryKey: ['person', id],
    queryFn: () => fetchPerson(id),
  });
  const { register, handleSubmit, reset } = useForm();
  const { mutate } = useMutation({
    mutationFn: (values) => updatePerson(values),
  });

  React.useEffect(() => {
    if (data) {
      // This will populate our form with the data from the API, but will not clear/override the values (dirty) provided by the user
      reset(data, { keepDirtyValues: true });
    }
  }, [data, reset]);

  if (!data) {
    return 'loading...';
  }

  return (
    <form onSubmit={handleSubmit(mutate)}>
      <div>
        <label htmlFor="firstName">First Name</label>
        <input {...register('firstName')} />
      </div>
      <div>
        <label htmlFor="lastName">Last Name</label>
        <input {...register('lastName')} />
      </div>
      <input type="submit" />
    </form>
  );
}

[TkDodo]

I think instead of the useEffect, you'd want the reactive values api:

• https://react-hook-form.com/faqs#Howtoinitializeformvalues

[h-jennings]

Great call! I wasn't aware of this API. Anytime I can get rid of a useEffect I will!

[meotimdihia]

It is weird. Did anyone get this TypeError:

TS2345: Argument of type
UseMutateFunction<unknown, unknown, void, unknown>
is not assignable to parameter of type  SubmitHandler<undefined> 
Types of parameters  options  and  event  are incompatible.
Type  BaseSyntheticEvent<object, any, any>  has no properties in common with type
MutateOptions<unknown, unknown, void, unknown>

at the line:

  <form onSubmit={handleSubmit(mutate)}>

[TkDodo]

Your mutateFn is likely missing types

[Moshyfawn]

The 2nd mutate argument is the MutateOptions while the onValid handleSubmit callback returns the form's BaseSyntheticEvent as the second argument, the submit form's event, which is not what the mutate options are.

handleSubmit((data, event) => mutate(data))

[meotimdihia]

@Moshyfawn Thanks, handleSubmit((data, event) => mutate(data)) works for me.
I think we need to fix the example in the article.

[harshavardhan-reddy]

I find myself contemplating the placement of the useMutation hook. Specifically, I'm weighing the pros and cons of defining it inside the PersonDetail component versus directly within the PersonForm.

From my understanding, if the form is intended for reuse with various mutations or more specifically a reusable form, placing useMutation outside the PersonForm seems logical. However, in scenarios where the form is exclusively designed for a specific update operation, integrating useMutation directly into the PersonForm appears to be a viable approach.

@TkDodo - Could you please share your insights on this? Am I correctly interpreting the best practices for implementing useMutation in such contexts?

[TkDodo]

I'd put it as close as possible to where it is trigger. I sometimes even have a <LikeButton /> that performs the mutation internally. Every layer where we pass things / handlers down as props create another indirection. Not saying that's bad or needs to be avoided, but adding it without reason also doesn't seem right ...

[jovanavukicevicdev]

About putting the form into separate file:

function PersonDetail({ id }) {
  const { data } = useQuery({
    queryKey: ['person', id],
    queryFn: () => fetchPerson(id),
  })
  const { mutate } = useMutation({
    mutationFn: (values) => updatePerson(values),
  })

  if (data) {
    return <PersonForm person={data} onSubmit={mutate} />
  }

  return 'loading...'
}

function PersonForm({ person, onSubmit }) {
  const { register, handleSubmit } = useForm({ defaultValues: person })
  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <div>
        <label htmlFor="firstName">First Name</label>
        <input {...register('firstName')} />
      </div>
      <div>
        <label htmlFor="lastName">Last Name</label>
        <input {...register('lastName')} />
      </div>
      <input type="submit" />
    </form>
  )
}

What if the form is in a Material UI dialog? And we're using react-hook-form. In my case "person" is passed to the dialog component from a parent, and it's not working when I set defaultValues in the dialog

[TkDodo]

I can't answer that without seeing a runnable reproduction

[hanuniye]

thank you for your helping sir! but is it must to use <Controller
name="firstName"
control={control}
render={({ field }) => (
<input
{...field}
value={field.value ?? data.firstName}
/>
)}
/>
instead of this

First Name
<input {...register('firstName')} />

the second question is can i implement the concept you called "Keeping background updates on" on this way First Name
<input {...register('firstName')} />
i just understand this way brother