Optimistic UI

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.

For more details on TanStack Query, including requirements, supported browsers, and advanced usage, see the TanStack Query documentation. For complete guidance on how to implement optimistic updates with TanStack Query, see the TanStack Query Optimistic UI Documentation. For more on the Amplify GraphQL API, see the API documentation.

To get started, run the following command in an existing Amplify project with a React frontend:

1# Install TanStack Query
2npm i @tanstack/react-query
3
4# Select default configuration
5amplify add api

When prompted, use the following schema:

1type RealEstateProperty @model @auth(rules: [{ allow: public }]) {
2  id: ID!
3  name: String!
4  address: String
5}

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:

1import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
2import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
3
4// Create a client
5const queryClient = new QueryClient()

Next, wrap your app in the client provider:

1<QueryClientProvider client={queryClient}>
2  <App />
3  <ReactQueryDevtools initialIsOpen={false} />
4</QueryClientProvider>

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 API

TanStack 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 records

To 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.

1import { generateClient } from 'aws-amplify/api'
2
3const client = generateClient()
4
5const {
6  data: realEstateProperties,
7  isLoading,
8  isSuccess,
9  isError: isErrorQuery,
10} = useQuery({
11  queryKey: ["realEstateProperties"],
12  queryFn: async () => {
13    const response = await client.graphql({
14      query: queries.listRealEstateProperties,
15    });
16
17    const allRealEstateProperties =
18      response?.data?.listRealEstateProperties?.items;
19
20    if (!allRealEstateProperties) return null;
21
22    return allRealEstateProperties;
23  },
24});

Optimistically rendering a newly created record

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.

1import { generateClient } from 'aws-amplify/api'
2
3const client = generateClient()
4
5const createMutation = useMutation({
6  mutationFn: async (realEstatePropertyDetails: CreateRealEstatePropertyInput) => {
7    const response = await client.graphql({
8      query: mutations.createRealEstateProperty,
9      variables: { input: realEstatePropertyDetails },
10    });
11
12    const newRealEstateProperty = response?.data?.createRealEstateProperty;
13    return newRealEstateProperty;
14  },
15  // When mutate is called:
16  onMutate: async (newRealEstateProperty) => {
17    // Cancel any outgoing refetches
18    // (so they don't overwrite our optimistic update)
19    await queryClient.cancelQueries({ queryKey: ["realEstateProperties"] });
20
21    // Snapshot the previous value
22    const previousRealEstateProperties = queryClient.getQueryData([
23      "realEstateProperties",
24    ]);
25
26    // Optimistically update to the new value
27    if (previousRealEstateProperties) {
28      queryClient.setQueryData(["realEstateProperties"], (old: RealEstateProperty[]) => [
29        ...old,
30        newRealEstateProperty,
31      ]);
32    }
33
34    // Return a context object with the snapshotted value
35    return { previousRealEstateProperties };
36  },
37  // If the mutation fails,
38  // use the context returned from onMutate to rollback
39  onError: (err, newRealEstateProperty, context) => {
40    console.error("Error saving record:", err, newRealEstateProperty);
41    if (context?.previousRealEstateProperties) {
42      queryClient.setQueryData(
43        ["realEstateProperties"],
44        context.previousRealEstateProperties
45      );
46    }
47  },
48  // Always refetch after error or success:
49  onSettled: () => {
50    queryClient.invalidateQueries({ queryKey: ["realEstateProperties"] });
51  },
52});

Querying a single item with TanStack Query

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.

1import { generateClient } from 'aws-amplify/api'
2
3const client = generateClient()
4
5const {
6  data: realEstateProperty,
7  isLoading,
8  isSuccess,
9  isError: isErrorQuery,
10} = useQuery({
11  queryKey: ["realEstateProperties", currentRealEstatePropertyId],
12  queryFn: async () => {
13    if (!currentRealEstatePropertyId) { return }
14
15    const response = await client.graphql({
16      query: queries.getRealEstateProperty,
17      variables: { id: currentRealEstatePropertyId },
18    });
19
20    return response.data?.getRealEstateProperty;
21  },
22});

Optimistically render updates for a record

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.

import { generateClient } from 'aws-amplify/api' const client = generateClient() const updateMutation = useMutation({ mutationFn: async ( realEstatePropertyDetails: UpdateRealEstatePropertyInput ) => { const response = await client.graphql({ query: mutations.updateRealEstateProperty, variables: { input: realEstatePropertyDetails }, }); return response?.data?.updateRealEstateProperty; }, // When mutate is called: onMutate: async (newRealEstateProperty) => { // Cancel any outgoing refetches // (so they don't overwrite our optimistic update) await queryClient.cancelQueries({ queryKey: ["realEstateProperties", newRealEstateProperty.id], }); await queryClient.cancelQueries({ queryKey: ["realEstateProperties"], }); // Snapshot the previous value const previousRealEstateProperty = queryClient.getQueryData([ "realEstateProperties", newRealEstateProperty.id, ]); // Optimistically update to the new value if (previousRealEstateProperty) { queryClient.setQueryData( ["realEstateProperties", newRealEstateProperty.id], /** * `newRealEstateProperty` will at first only include updated values for * the record. To avoid only rendering optimistic values for updated * fields on the UI, include the previous values for all fields: */ { ...previousRealEstateProperty, ...newRealEstateProperty } ); } // Return a context with the previous and new realEstateProperty return { previousRealEstateProperty, newRealEstateProperty }; }, // If the mutation fails, use the context we returned above onError: (err, newRealEstateProperty, context) => { console.error("Error updating record:", err, newRealEstateProperty); if (context?.previousRealEstateProperty) { queryClient.setQueryData( ["realEstateProperties", context.newRealEstateProperty.id], context.previousRealEstateProperty ); } }, // Always refetch after error or success: onSettled: (newRealEstateProperty) => { if (newRealEstateProperty) { queryClient.invalidateQueries({ queryKey: ["realEstateProperties", newRealEstateProperty.id], }); queryClient.invalidateQueries({ queryKey: ["realEstateProperties"], }); } }, });

1import { generateClient } from 'aws-amplify/api'
2
3const client = generateClient()
4
5const updateMutation = useMutation({
6  mutationFn: async (
7    realEstatePropertyDetails: UpdateRealEstatePropertyInput
8  ) => {
9    const response = await client.graphql({
10      query: mutations.updateRealEstateProperty,
11      variables: { input: realEstatePropertyDetails },
12    });
13
14    return response?.data?.updateRealEstateProperty;
15  },
16  // When mutate is called:
17  onMutate: async (newRealEstateProperty) => {
18    // Cancel any outgoing refetches
19    // (so they don't overwrite our optimistic update)
20    await queryClient.cancelQueries({
21      queryKey: ["realEstateProperties", newRealEstateProperty.id],
22    });
23
24    await queryClient.cancelQueries({
25      queryKey: ["realEstateProperties"],
26    });
27
28    // Snapshot the previous value
29    const previousRealEstateProperty = queryClient.getQueryData([
30      "realEstateProperties",
31      newRealEstateProperty.id,
32    ]);
33
34    // Optimistically update to the new value
35    if (previousRealEstateProperty) {
36      queryClient.setQueryData(
37        ["realEstateProperties", newRealEstateProperty.id],
38        /**
39         * `newRealEstateProperty` will at first only include updated values for
40         * the record. To avoid only rendering optimistic values for updated
41         * fields on the UI, include the previous values for all fields:
42         */
43        { ...previousRealEstateProperty, ...newRealEstateProperty }
44      );
45    }
46
47    // Return a context with the previous and new realEstateProperty
48    return { previousRealEstateProperty, newRealEstateProperty };
49  },
50  // If the mutation fails, use the context we returned above
51  onError: (err, newRealEstateProperty, context) => {
52    console.error("Error updating record:", err, newRealEstateProperty);
53    if (context?.previousRealEstateProperty) {
54      queryClient.setQueryData(
55        ["realEstateProperties", context.newRealEstateProperty.id],
56        context.previousRealEstateProperty
57      );
58    }
59  },
60  // Always refetch after error or success:
61  onSettled: (newRealEstateProperty) => {
62    if (newRealEstateProperty) {
63      queryClient.invalidateQueries({
64        queryKey: ["realEstateProperties", newRealEstateProperty.id],
65      });
66      queryClient.invalidateQueries({
67        queryKey: ["realEstateProperties"],
68      });
69    }
70  },
71});

Optimistically render deleting a record

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.

import { generateClient } from 'aws-amplify/api' const client = generateClient() const deleteMutation = useMutation({ mutationFn: async ( realEstatePropertyDetails: DeleteRealEstatePropertyInput ) => { const response = await client.graphql({ query: mutations.deleteRealEstateProperty, variables: { input: realEstatePropertyDetails }, }); return response?.data?.deleteRealEstateProperty; }, // When mutate is called: onMutate: async (newRealEstateProperty) => { // Cancel any outgoing refetches // (so they don't overwrite our optimistic update) await queryClient.cancelQueries({ queryKey: ["realEstateProperties", newRealEstateProperty.id], }); await queryClient.cancelQueries({ queryKey: ["realEstateProperties"], }); // Snapshot the previous value const previousRealEstateProperty = queryClient.getQueryData([ "realEstateProperties", newRealEstateProperty.id, ]); // Optimistically update to the new value if (previousRealEstateProperty) { queryClient.setQueryData( ["realEstateProperties", newRealEstateProperty.id], newRealEstateProperty ); } // Return a context with the previous and new realEstateProperty return { previousRealEstateProperty, newRealEstateProperty }; }, // If the mutation fails, use the context we returned above onError: (err, newRealEstateProperty, context) => { console.error("Error deleting record:", err, newRealEstateProperty); if (context?.previousRealEstateProperty) { queryClient.setQueryData( ["realEstateProperties", context.newRealEstateProperty.id], context.previousRealEstateProperty ); } }, // Always refetch after error or success: onSettled: (newRealEstateProperty) => { if (newRealEstateProperty) { queryClient.invalidateQueries({ queryKey: ["realEstateProperties", newRealEstateProperty.id], }); queryClient.invalidateQueries({ queryKey: ["realEstateProperties"], }); } }, });

1import { generateClient } from 'aws-amplify/api'
2
3const client = generateClient()
4
5const deleteMutation = useMutation({
6  mutationFn: async (
7    realEstatePropertyDetails: DeleteRealEstatePropertyInput
8  ) => {
9    const response = await client.graphql({
10      query: mutations.deleteRealEstateProperty,
11      variables: { input: realEstatePropertyDetails },
12    });
13
14    return response?.data?.deleteRealEstateProperty;
15  },
16  // When mutate is called:
17  onMutate: async (newRealEstateProperty) => {
18    // Cancel any outgoing refetches
19    // (so they don't overwrite our optimistic update)
20    await queryClient.cancelQueries({
21      queryKey: ["realEstateProperties", newRealEstateProperty.id],
22    });
23
24    await queryClient.cancelQueries({
25      queryKey: ["realEstateProperties"],
26    });
27
28    // Snapshot the previous value
29    const previousRealEstateProperty = queryClient.getQueryData([
30      "realEstateProperties",
31      newRealEstateProperty.id,
32    ]);
33
34    // Optimistically update to the new value
35    if (previousRealEstateProperty) {
36      queryClient.setQueryData(
37        ["realEstateProperties", newRealEstateProperty.id],
38        newRealEstateProperty
39      );
40    }
41
42    // Return a context with the previous and new realEstateProperty
43    return { previousRealEstateProperty, newRealEstateProperty };
44  },
45  // If the mutation fails, use the context we returned above
46  onError: (err, newRealEstateProperty, context) => {
47    console.error("Error deleting record:", err, newRealEstateProperty);
48    if (context?.previousRealEstateProperty) {
49      queryClient.setQueryData(
50        ["realEstateProperties", context.newRealEstateProperty.id],
51        context.previousRealEstateProperty
52      );
53    }
54  },
55  // Always refetch after error or success:
56  onSettled: (newRealEstateProperty) => {
57    if (newRealEstateProperty) {
58      queryClient.invalidateQueries({
59        queryKey: ["realEstateProperties", newRealEstateProperty.id],
60      });
61      queryClient.invalidateQueries({
62        queryKey: ["realEstateProperties"],
63      });
64    }
65  },
66});

Loading and error states for optimistically rendered data

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:

1function GlobalLoadingIndicator() {
2  const isFetching = useIsFetching();
3  return isFetching ? <div style={styles.globalLoadingIndicator}></div> : null;
4}

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.

1<>
2  {updateMutation.isError &&
3  updateMutation.error instanceof Error ? (
4    <div>An error occurred: {updateMutation.error.message}</div>
5  ) : null}
6
7  {updateMutation.isSuccess ? (
8    <div>Real Estate Property updated!</div>
9  ) : null}
10
11  <button
12    onClick={() =>
13      updateMutation.mutate({
14        id: realEstateProperty.id,
15        address: `${Math.floor(
16          1000 + Math.random() * 9000
17        )} Main St`,
18      })
19    }
20  >
21    Update Address
22  </button>
23</>

Complete example

1// index.tsx:
2import React from "react";
3import ReactDOM from "react-dom/client";
4import "./index.css";
5import App from "./App";
6import { Amplify } from "aws-amplify";
7import config from "./amplifyconfiguration.json";
8import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
9import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
10import "@aws-amplify/ui-react/styles.css";
11
12Amplify.configure(config);
13
14// Create a client
15const queryClient = new QueryClient();
16
17const root = ReactDOM.createRoot(
18  document.getElementById("root") as HTMLElement
19);
20
21// Provide the client to your App
22root.render(
23  <React.StrictMode>
24    <QueryClientProvider client={queryClient}>
25      <App />
26      <ReactQueryDevtools initialIsOpen={false} />
27    </QueryClientProvider>
28  </React.StrictMode>
29);

// App.tsx: import { useState } from "react"; import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"; import { useIsFetching } from "@tanstack/react-query"; import { generateClient } from 'aws-amplify/api' import * as mutations from "./graphql/mutations"; import * as queries from "./graphql/queries"; import { CreateRealEstatePropertyInput, DeleteRealEstatePropertyInput, RealEstateProperty, UpdateRealEstatePropertyInput } from "./API"; /** * https://www.tanstack.com/query/v4/docs/react/guides/background-fetching-indicators#displaying-global-background-fetching-loading-state * For the purposes of this demo, we show a global loading indicator when *any* * queries are fetching (including in the background) in order to help visualize * what TanStack is doing in the background. This example also displays * indicators for individual query and mutation loading states. */ function GlobalLoadingIndicator() { const isFetching = useIsFetching(); return isFetching ? <div style={styles.globalLoadingIndicator}></div> : null; } const client = generateClient() function App() { const [currentRealEstatePropertyId, setCurrentRealEstatePropertyId] = useState<string | null>(null); // Access the client const queryClient = useQueryClient(); // TanStack Query for listing all real estate properties: const { data: realEstateProperties, isLoading, isSuccess, isError: isErrorQuery, } = useQuery({ queryKey: ["realEstateProperties"], queryFn: async () => { const response = await client.graphql({ query: queries.listRealEstateProperties, }); const allRealEstateProperties = response?.data?.listRealEstateProperties?.items; if (!allRealEstateProperties) return null; return allRealEstateProperties; }, }); // TanStack create mutation with optimistic updates const createMutation = useMutation({ mutationFn: async (realEstatePropertyDetails: CreateRealEstatePropertyInput) => { const response = await client.graphql({ query: mutations.createRealEstateProperty, variables: { input: realEstatePropertyDetails }, }); const newRealEstateProperty = response?.data?.createRealEstateProperty; return newRealEstateProperty; }, // When mutate is called: onMutate: async (newRealEstateProperty) => { // Cancel any outgoing refetches // (so they don't overwrite our optimistic update) await queryClient.cancelQueries({ queryKey: ["realEstateProperties"] }); // Snapshot the previous value const previousRealEstateProperties = queryClient.getQueryData([ "realEstateProperties", ]); // Optimistically update to the new value if (previousRealEstateProperties) { queryClient.setQueryData(["realEstateProperties"], (old: RealEstateProperty[]) => [ ...old, newRealEstateProperty, ]); } // Return a context object with the snapshotted value return { previousRealEstateProperties }; }, // If the mutation fails, // use the context returned from onMutate to rollback onError: (err, newRealEstateProperty, context) => { console.error("Error saving record:", err, newRealEstateProperty); if (context?.previousRealEstateProperties) { queryClient.setQueryData( ["realEstateProperties"], context.previousRealEstateProperties ); } }, // Always refetch after error or success: onSettled: () => { queryClient.invalidateQueries({ queryKey: ["realEstateProperties"] }); }, }); /** * Note: this example does not return to the list view on delete in order * to demonstrate the optimistic update. */ function RealEstatePropertyDetailView() { const { data: realEstateProperty, isLoading, isSuccess, isError: isErrorQuery, } = useQuery({ queryKey: ["realEstateProperties", currentRealEstatePropertyId], queryFn: async () => { if (!currentRealEstatePropertyId) { return } const response = await client.graphql({ query: queries.getRealEstateProperty, variables: { id: currentRealEstatePropertyId }, }); return response.data?.getRealEstateProperty; }, }); // TanStack update mutation with optimistic updates const updateMutation = useMutation({ mutationFn: async ( realEstatePropertyDetails: UpdateRealEstatePropertyInput ) => { const response = await client.graphql({ query: mutations.updateRealEstateProperty, variables: { input: realEstatePropertyDetails }, }); return response?.data?.updateRealEstateProperty; }, // When mutate is called: onMutate: async (newRealEstateProperty) => { // Cancel any outgoing refetches // (so they don't overwrite our optimistic update) await queryClient.cancelQueries({ queryKey: ["realEstateProperties", newRealEstateProperty.id], }); await queryClient.cancelQueries({ queryKey: ["realEstateProperties"], }); // Snapshot the previous value const previousRealEstateProperty = queryClient.getQueryData([ "realEstateProperties", newRealEstateProperty.id, ]); // Optimistically update to the new value if (previousRealEstateProperty) { queryClient.setQueryData( ["realEstateProperties", newRealEstateProperty.id], /** * `newRealEstateProperty` will at first only include updated values for * the record. To avoid only rendering optimistic values for updated * fields on the UI, include the previous values for all fields: */ { ...previousRealEstateProperty, ...newRealEstateProperty } ); } // Return a context with the previous and new realEstateProperty return { previousRealEstateProperty, newRealEstateProperty }; }, // If the mutation fails, use the context we returned above onError: (err, newRealEstateProperty, context) => { console.error("Error updating record:", err, newRealEstateProperty); if (context?.previousRealEstateProperty) { queryClient.setQueryData( ["realEstateProperties", context.newRealEstateProperty.id], context.previousRealEstateProperty ); } }, // Always refetch after error or success: onSettled: (newRealEstateProperty) => { if (newRealEstateProperty) { queryClient.invalidateQueries({ queryKey: ["realEstateProperties", newRealEstateProperty.id], }); queryClient.invalidateQueries({ queryKey: ["realEstateProperties"], }); } }, }); // TanStack delete mutation with optimistic updates const deleteMutation = useMutation({ mutationFn: async ( realEstatePropertyDetails: DeleteRealEstatePropertyInput ) => { const response = await client.graphql({ query: mutations.deleteRealEstateProperty, variables: { input: realEstatePropertyDetails }, }); return response?.data?.deleteRealEstateProperty; }, // When mutate is called: onMutate: async (newRealEstateProperty) => { // Cancel any outgoing refetches // (so they don't overwrite our optimistic update) await queryClient.cancelQueries({ queryKey: ["realEstateProperties", newRealEstateProperty.id], }); await queryClient.cancelQueries({ queryKey: ["realEstateProperties"], }); // Snapshot the previous value const previousRealEstateProperty = queryClient.getQueryData([ "realEstateProperties", newRealEstateProperty.id, ]); // Optimistically update to the new value if (previousRealEstateProperty) { queryClient.setQueryData( ["realEstateProperties", newRealEstateProperty.id], newRealEstateProperty ); } // Return a context with the previous and new realEstateProperty return { previousRealEstateProperty, newRealEstateProperty }; }, // If the mutation fails, use the context we returned above onError: (err, newRealEstateProperty, context) => { console.error("Error deleting record:", err, newRealEstateProperty); if (context?.previousRealEstateProperty) { queryClient.setQueryData( ["realEstateProperties", context.newRealEstateProperty.id], context.previousRealEstateProperty ); } }, // Always refetch after error or success: onSettled: (newRealEstateProperty) => { if (newRealEstateProperty) { queryClient.invalidateQueries({ queryKey: ["realEstateProperties", newRealEstateProperty.id], }); queryClient.invalidateQueries({ queryKey: ["realEstateProperties"], }); } }, }); return ( <div style={styles.detailViewContainer}> <h2>Real Estate Property Detail View</h2> {isErrorQuery && <div>{"Problem loading Real Estate Property"}</div>} {isLoading && ( <div style={styles.loadingIndicator}> {"Loading Real Estate Property..."} </div> )} {isSuccess && ( <div> <p>{`Name: ${realEstateProperty?.name}`}</p> <p>{`Address: ${realEstateProperty?.address}`}</p> </div> )} {realEstateProperty && ( <div> <div> {updateMutation.isPending ? ( "Updating Real Estate Property..." ) : ( <> {updateMutation.isError && updateMutation.error instanceof Error ? ( <div>An error occurred: {updateMutation.error.message}</div> ) : null} {updateMutation.isSuccess ? ( <div>Real Estate Property updated!</div> ) : null} <button onClick={() => updateMutation.mutate({ id: realEstateProperty.id, name: `Updated Home ${Date.now()}`, }) } > Update Name </button> <button onClick={() => updateMutation.mutate({ id: realEstateProperty.id, address: `${Math.floor( 1000 + Math.random() * 9000 )} Main St`, }) } > Update Address </button> </> )} </div> <div> {deleteMutation.isPending ? ( "Deleting Real Estate Property..." ) : ( <> {deleteMutation.isError && deleteMutation.error instanceof Error ? ( <div>An error occurred: {deleteMutation.error.message}</div> ) : null} {deleteMutation.isSuccess ? ( <div>Real Estate Property deleted!</div> ) : null} <button onClick={() => deleteMutation.mutate({ id: realEstateProperty.id, }) } > Delete </button> </> )} </div> </div> )} <button onClick={() => setCurrentRealEstatePropertyId(null)}> Back </button> </div> ); } return ( <div> {!currentRealEstatePropertyId && ( <div style={styles.appContainer}> <h1>Real Estate Properties:</h1> <div> {createMutation.isPending ? ( "Adding Real Estate Property..." ) : ( <> {createMutation.isError && createMutation.error instanceof Error ? ( <div>An error occurred: {createMutation.error.message}</div> ) : null} {createMutation.isSuccess ? ( <div>Real Estate Property added!</div> ) : null} <button onClick={() => { createMutation.mutate({ name: `New Home ${Date.now()}`, address: `${Math.floor( 1000 + Math.random() * 9000 )} Main St`, }); }} > Add RealEstateProperty </button> </> )} </div> <ul style={styles.propertiesList}> {isLoading && ( <div style={styles.loadingIndicator}> {"Loading Real Estate Properties..."} </div> )} {isErrorQuery && ( <div>{"Problem loading Real Estate Properties"}</div> )} {isSuccess && realEstateProperties?.map((realEstateProperty, idx) => { if (!realEstateProperty) return null; return ( <li style={styles.listItem} key={`${idx}-${realEstateProperty.id}`} > <p>{realEstateProperty.name}</p> <button style={styles.detailViewButton} onClick={() => setCurrentRealEstatePropertyId(realEstateProperty.id) } > Detail View </button> </li> ); })} </ul> </div> )} {currentRealEstatePropertyId && <RealEstatePropertyDetailView />} <GlobalLoadingIndicator /> </div> ); } export default App; const styles = { appContainer: { display: "flex", flexDirection: "column", alignItems: "center", }, detailViewButton: { marginLeft: "1rem" }, detailViewContainer: { border: "1px solid black", padding: "3rem" }, globalLoadingIndicator: { position: "fixed", top: 0, left: 0, width: "100%", height: "100%", border: "4px solid blue", pointerEvents: "none", }, listItem: { display: "flex", justifyContent: "space-between", border: "1px dotted grey", padding: ".5rem", margin: ".1rem", }, loadingIndicator: { border: "1px solid black", padding: "1rem", margin: "1rem", }, propertiesList: { display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "start", width: "50%", border: "1px solid black", padding: "1rem", listStyleType: "none", }, } as const;

1// App.tsx:
2import { useState } from "react";
3import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
4import { useIsFetching } from "@tanstack/react-query";
5import { generateClient } from 'aws-amplify/api'
6import * as mutations from "./graphql/mutations";
7import * as queries from "./graphql/queries";
8import { CreateRealEstatePropertyInput, DeleteRealEstatePropertyInput, RealEstateProperty, UpdateRealEstatePropertyInput } from "./API";
9
10/**
11 * https://www.tanstack.com/query/v4/docs/react/guides/background-fetching-indicators#displaying-global-background-fetching-loading-state
12 * For the purposes of this demo, we show a global loading indicator when *any*
13 * queries are fetching (including in the background) in order to help visualize
14 * what TanStack is doing in the background. This example also displays
15 * indicators for individual query and mutation loading states.
16 */
17function GlobalLoadingIndicator() {
18  const isFetching = useIsFetching();
19
20  return isFetching ? <div style={styles.globalLoadingIndicator}></div> : null;
21}
22
23const client = generateClient()
24
25function App() {
26  const [currentRealEstatePropertyId, setCurrentRealEstatePropertyId] =
27    useState<string | null>(null);
28
29  // Access the client
30  const queryClient = useQueryClient();
31
32  // TanStack Query for listing all real estate properties:
33  const {
34    data: realEstateProperties,
35    isLoading,
36    isSuccess,
37    isError: isErrorQuery,
38  } = useQuery({
39    queryKey: ["realEstateProperties"],
40    queryFn: async () => {
41      const response = await client.graphql({
42        query: queries.listRealEstateProperties,
43      });
44
45      const allRealEstateProperties =
46        response?.data?.listRealEstateProperties?.items;
47
48      if (!allRealEstateProperties) return null;
49
50      return allRealEstateProperties;
51    },
52  });
53
54  // TanStack create mutation with optimistic updates
55  const createMutation = useMutation({
56    mutationFn: async (realEstatePropertyDetails: CreateRealEstatePropertyInput) => {
57      const response = await client.graphql({
58        query: mutations.createRealEstateProperty,
59        variables: { input: realEstatePropertyDetails },
60      });
61
62      const newRealEstateProperty = response?.data?.createRealEstateProperty;
63      return newRealEstateProperty;
64    },
65    // When mutate is called:
66    onMutate: async (newRealEstateProperty) => {
67      // Cancel any outgoing refetches
68      // (so they don't overwrite our optimistic update)
69      await queryClient.cancelQueries({ queryKey: ["realEstateProperties"] });
70
71      // Snapshot the previous value
72      const previousRealEstateProperties = queryClient.getQueryData([
73        "realEstateProperties",
74      ]);
75
76      // Optimistically update to the new value
77      if (previousRealEstateProperties) {
78        queryClient.setQueryData(["realEstateProperties"], (old: RealEstateProperty[]) => [
79          ...old,
80          newRealEstateProperty,
81        ]);
82      }
83
84      // Return a context object with the snapshotted value
85      return { previousRealEstateProperties };
86    },
87    // If the mutation fails,
88    // use the context returned from onMutate to rollback
89    onError: (err, newRealEstateProperty, context) => {
90      console.error("Error saving record:", err, newRealEstateProperty);
91      if (context?.previousRealEstateProperties) {
92        queryClient.setQueryData(
93          ["realEstateProperties"],
94          context.previousRealEstateProperties
95        );
96      }
97    },
98    // Always refetch after error or success:
99    onSettled: () => {
100      queryClient.invalidateQueries({ queryKey: ["realEstateProperties"] });
101    },
102  });
103
104  /**
105   * Note: this example does not return to the list view on delete in order
106   * to demonstrate the optimistic update.
107   */
108  function RealEstatePropertyDetailView() {
109    const {
110      data: realEstateProperty,
111      isLoading,
112      isSuccess,
113      isError: isErrorQuery,
114    } = useQuery({
115      queryKey: ["realEstateProperties", currentRealEstatePropertyId],
116      queryFn: async () => {
117        if (!currentRealEstatePropertyId) { return }
118
119        const response = await client.graphql({
120          query: queries.getRealEstateProperty,
121          variables: { id: currentRealEstatePropertyId },
122        });
123
124        return response.data?.getRealEstateProperty;
125      },
126    });
127
128    // TanStack update mutation with optimistic updates
129    const updateMutation = useMutation({
130      mutationFn: async (
131        realEstatePropertyDetails: UpdateRealEstatePropertyInput
132      ) => {
133        const response = await client.graphql({
134          query: mutations.updateRealEstateProperty,
135          variables: { input: realEstatePropertyDetails },
136        });
137
138        return response?.data?.updateRealEstateProperty;
139      },
140      // When mutate is called:
141      onMutate: async (newRealEstateProperty) => {
142        // Cancel any outgoing refetches
143        // (so they don't overwrite our optimistic update)
144        await queryClient.cancelQueries({
145          queryKey: ["realEstateProperties", newRealEstateProperty.id],
146        });
147
148        await queryClient.cancelQueries({
149          queryKey: ["realEstateProperties"],
150        });
151
152        // Snapshot the previous value
153        const previousRealEstateProperty = queryClient.getQueryData([
154          "realEstateProperties",
155          newRealEstateProperty.id,
156        ]);
157
158        // Optimistically update to the new value
159        if (previousRealEstateProperty) {
160          queryClient.setQueryData(
161            ["realEstateProperties", newRealEstateProperty.id],
162            /**
163             * `newRealEstateProperty` will at first only include updated values for
164             * the record. To avoid only rendering optimistic values for updated
165             * fields on the UI, include the previous values for all fields:
166             */
167            { ...previousRealEstateProperty, ...newRealEstateProperty }
168          );
169        }
170
171        // Return a context with the previous and new realEstateProperty
172        return { previousRealEstateProperty, newRealEstateProperty };
173      },
174      // If the mutation fails, use the context we returned above
175      onError: (err, newRealEstateProperty, context) => {
176        console.error("Error updating record:", err, newRealEstateProperty);
177        if (context?.previousRealEstateProperty) {
178          queryClient.setQueryData(
179            ["realEstateProperties", context.newRealEstateProperty.id],
180            context.previousRealEstateProperty
181          );
182        }
183      },
184      // Always refetch after error or success:
185      onSettled: (newRealEstateProperty) => {
186        if (newRealEstateProperty) {
187          queryClient.invalidateQueries({
188            queryKey: ["realEstateProperties", newRealEstateProperty.id],
189          });
190          queryClient.invalidateQueries({
191            queryKey: ["realEstateProperties"],
192          });
193        }
194      },
195    });
196
197    // TanStack delete mutation with optimistic updates
198    const deleteMutation = useMutation({
199      mutationFn: async (
200        realEstatePropertyDetails: DeleteRealEstatePropertyInput
201      ) => {
202        const response = await client.graphql({
203          query: mutations.deleteRealEstateProperty,
204          variables: { input: realEstatePropertyDetails },
205        });
206
207        return response?.data?.deleteRealEstateProperty;
208      },
209      // When mutate is called:
210      onMutate: async (newRealEstateProperty) => {
211        // Cancel any outgoing refetches
212        // (so they don't overwrite our optimistic update)
213        await queryClient.cancelQueries({
214          queryKey: ["realEstateProperties", newRealEstateProperty.id],
215        });
216
217        await queryClient.cancelQueries({
218          queryKey: ["realEstateProperties"],
219        });
220
221        // Snapshot the previous value
222        const previousRealEstateProperty = queryClient.getQueryData([
223          "realEstateProperties",
224          newRealEstateProperty.id,
225        ]);
226
227        // Optimistically update to the new value
228        if (previousRealEstateProperty) {
229          queryClient.setQueryData(
230            ["realEstateProperties", newRealEstateProperty.id],
231            newRealEstateProperty
232          );
233        }
234
235        // Return a context with the previous and new realEstateProperty
236        return { previousRealEstateProperty, newRealEstateProperty };
237      },
238      // If the mutation fails, use the context we returned above
239      onError: (err, newRealEstateProperty, context) => {
240        console.error("Error deleting record:", err, newRealEstateProperty);
241        if (context?.previousRealEstateProperty) {
242          queryClient.setQueryData(
243            ["realEstateProperties", context.newRealEstateProperty.id],
244            context.previousRealEstateProperty
245          );
246        }
247      },
248      // Always refetch after error or success:
249      onSettled: (newRealEstateProperty) => {
250        if (newRealEstateProperty) {
251          queryClient.invalidateQueries({
252            queryKey: ["realEstateProperties", newRealEstateProperty.id],
253          });
254          queryClient.invalidateQueries({
255            queryKey: ["realEstateProperties"],
256          });
257        }
258      },
259    });
260
261    return (
262      <div style={styles.detailViewContainer}>
263        <h2>Real Estate Property Detail View</h2>
264        {isErrorQuery && <div>{"Problem loading Real Estate Property"}</div>}
265        {isLoading && (
266          <div style={styles.loadingIndicator}>
267            {"Loading Real Estate Property..."}
268          </div>
269        )}
270        {isSuccess && (
271          <div>
272            <p>{`Name: ${realEstateProperty?.name}`}</p>
273            <p>{`Address: ${realEstateProperty?.address}`}</p>
274          </div>
275        )}
276        {realEstateProperty && (
277          <div>
278            <div>
279              {updateMutation.isPending ? (
280                "Updating Real Estate Property..."
281              ) : (
282                <>
283                  {updateMutation.isError &&
284                  updateMutation.error instanceof Error ? (
285                    <div>An error occurred: {updateMutation.error.message}</div>
286                  ) : null}
287
288                  {updateMutation.isSuccess ? (
289                    <div>Real Estate Property updated!</div>
290                  ) : null}
291
292                  <button
293                    onClick={() =>
294                      updateMutation.mutate({
295                        id: realEstateProperty.id,
296                        name: `Updated Home ${Date.now()}`,
297                      })
298                    }
299                  >
300                    Update Name
301                  </button>
302                  <button
303                    onClick={() =>
304                      updateMutation.mutate({
305                        id: realEstateProperty.id,
306                        address: `${Math.floor(
307                          1000 + Math.random() * 9000
308                        )} Main St`,
309                      })
310                    }
311                  >
312                    Update Address
313                  </button>
314                </>
315              )}
316            </div>
317
318            <div>
319              {deleteMutation.isPending ? (
320                "Deleting Real Estate Property..."
321              ) : (
322                <>
323                  {deleteMutation.isError &&
324                  deleteMutation.error instanceof Error ? (
325                    <div>An error occurred: {deleteMutation.error.message}</div>
326                  ) : null}
327
328                  {deleteMutation.isSuccess ? (
329                    <div>Real Estate Property deleted!</div>
330                  ) : null}
331
332                  <button
333                    onClick={() =>
334                      deleteMutation.mutate({
335                        id: realEstateProperty.id,
336                      })
337                    }
338                  >
339                    Delete
340                  </button>
341                </>
342              )}
343            </div>
344          </div>
345        )}
346        <button onClick={() => setCurrentRealEstatePropertyId(null)}>
347          Back
348        </button>
349      </div>
350    );
351  }
352
353  return (
354    <div>
355      {!currentRealEstatePropertyId && (
356        <div style={styles.appContainer}>
357          <h1>Real Estate Properties:</h1>
358          <div>
359            {createMutation.isPending ? (
360              "Adding Real Estate Property..."
361            ) : (
362              <>
363                {createMutation.isError &&
364                createMutation.error instanceof Error ? (
365                  <div>An error occurred: {createMutation.error.message}</div>
366                ) : null}
367
368                {createMutation.isSuccess ? (
369                  <div>Real Estate Property added!</div>
370                ) : null}
371
372                <button
373                  onClick={() => {
374                    createMutation.mutate({
375                      name: `New Home ${Date.now()}`,
376                      address: `${Math.floor(
377                        1000 + Math.random() * 9000
378                      )} Main St`,
379                    });
380                  }}
381                >
382                  Add RealEstateProperty
383                </button>
384              </>
385            )}
386          </div>
387          <ul style={styles.propertiesList}>
388            {isLoading && (
389              <div style={styles.loadingIndicator}>
390                {"Loading Real Estate Properties..."}
391              </div>
392            )}
393            {isErrorQuery && (
394              <div>{"Problem loading Real Estate Properties"}</div>
395            )}
396            {isSuccess &&
397              realEstateProperties?.map((realEstateProperty, idx) => {
398                if (!realEstateProperty) return null;
399                return (
400                  <li
401                    style={styles.listItem}
402                    key={`${idx}-${realEstateProperty.id}`}
403                  >
404                    <p>{realEstateProperty.name}</p>
405                    <button
406                      style={styles.detailViewButton}
407                      onClick={() =>
408                        setCurrentRealEstatePropertyId(realEstateProperty.id)
409                      }
410                    >
411                      Detail View
412                    </button>
413                  </li>
414                );
415              })}
416          </ul>
417        </div>
418      )}
419      {currentRealEstatePropertyId && <RealEstatePropertyDetailView />}
420      <GlobalLoadingIndicator />
421    </div>
422  );
423}
424
425export default App;
426
427const styles = {
428  appContainer: {
429    display: "flex",
430    flexDirection: "column",
431    alignItems: "center",
432  },
433  detailViewButton: { marginLeft: "1rem" },
434  detailViewContainer: { border: "1px solid black", padding: "3rem" },
435  globalLoadingIndicator: {
436    position: "fixed",
437    top: 0,
438    left: 0,
439    width: "100%",
440    height: "100%",
441    border: "4px solid blue",
442    pointerEvents: "none",
443  },
444  listItem: {
445    display: "flex",
446    justifyContent: "space-between",
447    border: "1px dotted grey",
448    padding: ".5rem",
449    margin: ".1rem",
450  },
451  loadingIndicator: {
452    border: "1px solid black",
453    padding: "1rem",
454    margin: "1rem",
455  },
456  propertiesList: {
457    display: "flex",
458    flexDirection: "column",
459    alignItems: "center",
460    justifyContent: "start",
461    width: "50%",
462    border: "1px solid black",
463    padding: "1rem",
464    listStyleType: "none",
465  },
466} as const;

Working with files / attachments

Connect to data from server-side runtimes