The GraphQL API category can be used with TanStack Query to implement optimistic UI, allowing CRUD operations to be rendered immediately on the UI before the request roundtrip has completed. Using the GraphQL API with TanStack additionally makes it easy to render loading and error states, and allows you to rollback changes on the UI when API calls are unsuccessful.
In the following examples we'll create a list view that optimistically renders newly created items, and a detail view that optimistically renders updates and deletes.
To get started, run the following command in an existing Amplify project with a React frontend:
When prompted, use the following schema:
The schema file can also be found under amplify/backend/api/[name of project]/schema.graphql. Save the schema and run amplify push to deploy the changes. For the purposes of this guide, we'll build a Real Estate Property listing application.
Next, at the root of your project, add the required TanStack Query imports, and create a client:
Next, wrap your app in the client provider:
TanStack Query Devtools are not required, but are a useful resource for debugging and understanding how TanStack works under the hood. By default, React Query Devtools are only included in bundles when process.env.NODE_ENV === 'development', meaning that no additional configuration is required to exclude them from a production build. For more information on the TanStack Query Devtools, visit the TanStack Query Devtools docs
For the complete working example, including required imports and React component state management, see the Complete Example below.
How to use TanStack Query query keys with the GraphQL APITanStack Query manages query caching based on the query keys you specify. A query key must be an array. The array can contain a single string or multiple strings and nested objects. The query key must be serializable, and unique to the query's data.
When using TanStack to render optimistic UI with the GraphQL API, it is important to note that different query keys must be used depending on the API operation. When retrieving a list of items, a single string is used (e.g. queryKey: ["realEstateProperties"]). This query key is also used to optimistically render a newly created item. When updating or deleting an item, the query key must also include the unique identifier for the record being deleted or updated (e.g. queryKey: ["realEstateProperties", newRealEstateProperty.id]).
For more detailed information on query keys, see the TanStack Query documentation.
Optimistically rendering a list of recordsTo optimistically render a list of items returned from the GraphQL API, use the TanStack useQuery hook, passing in the GraphQL API query as the queryFn parameter. The following example creates a query to retrieve all records from the API. We'll use realEstateProperties as the query key, which will be the same key we use to optimistically render a newly created item.
To optimistically render a newly created record returned from the GraphQL API, use the TanStack useMutation hook, passing in the GraphQL API mutation as the mutationFn parameter. We'll use the same query key used by the useQuery hook (realEstateProperties) as the query key to optimistically render a newly created item. We'll use the onMutate function to update the cache directly, as well as the onError function to rollback changes when a request fails.
To optimistically render updates on a single item, we'll first retrieve the item from the API. We'll use the useQuery hook, passing in the GraphQL API query as the queryFn parameter. For the query key, we'll use a combination of realEstateProperties and the record's unique identifier.
To optimistically render GraphQL API updates for a single record, use the TanStack useMutation hook, passing in the GraphQL API update mutation as the mutationFn parameter. We'll use the same query key combination used by the single record useQuery hook (realEstateProperties and the record's id) as the query key to optimistically render the updates. We'll use the onMutate function to update the cache directly, as well as the onError function to rollback changes when a request fails.
When directly interacting with the cache via the onMutate function, it should be noted that the newRealEstateProperty parameter only includes the fields that are being updated, until the final return from the GraphQL API returns all fields for the record. When calling setQueryData, include the previous values for all fields in addition to the newly updated fields to avoid only rendering optimistic values for updated fields on the UI.
To optimistically render a GraphQL API delete of a single record, use the TanStack useMutation hook, passing in the GraphQL API delete mutation as the mutationFn parameter. We'll use the same query key combination used by the single record useQuery hook (realEstateProperties and the record's id) as the query key to optimistically render the updates. We'll use the onMutate function to update the cache directly, as well as the onError function to rollback changes when a delete fails.
Both useQuery and useMutation return isLoading and isError states that indicate the current state of the query or mutation. You can use these states to render loading and error indicators.
In addition to operation-specific loading states, TanStack Query provides a useIsFetching hook. For the purposes of this demo, we show a global loading indicator in the Complete Example when any queries are fetching (including in the background) in order to help visualize what TanStack is doing in the background:
For more details on advanced usage of TanStack Query hooks, see the TanStack documentation.
The following example demonstrates how to use the state returned by TanStack to render a loading indicator while a mutation is in progress, and an error message if the mutation fails. For additional examples, see the Complete Example below.
Complete exampleRetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4