{"id":15871,"date":"2026-09-08T10:10:21","date_gmt":"2026-09-08T07:10:21","guid":{"rendered":"https:\/\/dhtmlx.com\/blog\/?p=15871"},"modified":"2026-09-08T10:59:41","modified_gmt":"2026-09-08T07:59:41","slug":"managing-server-state-in-react-gantt-chart-with-tanstack-query-and-zustand","status":"publish","type":"post","link":"https:\/\/dhtmlx.com\/blog\/managing-server-state-in-react-gantt-chart-with-tanstack-query-and-zustand\/","title":{"rendered":"Managing Server State in React Gantt Chart with TanStack Query and Zustand"},"content":{"rendered":"

In one of our previous tutorials, we covered the basics of state management in DHTMLX React Gantt with Zustand<\/a>. There, we focused on managing Gantt data on the client side. However, real project planning apps, in most cases, need to load tasks and dependency links from the server and save user edits there, which calls for a dedicated server-state layer. This is where TanStack Query comes into play.<\/p>\n

In this post, we’ll explain how TanStack Query complements Zustand in the DHTMLX React Gantt component<\/a> and highlight the key integration steps. As reference sources of information, we’ll use the GitHub repository of the starter project<\/a> and the official TanStack Query integration guide<\/a>.<\/p>\n

Introduction to TanStack Query and Its Approach to Handling Server State in React<\/h2>\n

Before the TanStack Query release in late 2019, developers used various approaches for managing server state: built-in React hooks (useEffect, useState), client-side state managers (Redux, MobX, Zustand, etc.), or custom caching abstractions. These techniques can be effective to some extent, but they require considerable manual effort from developers and may lead to additional boilerplate and complexity. Another serious difficulty related to server state is that it can quickly become out of date, as server data may change independently of the client. TanStack Query is designed to address these well-known pain points<\/a> in state management. It provides a clear mental model for fetching, caching, mutating, and synchronizing server data in React apps. <\/p>\n

In our starter demo, TanStack Query and Zustand form a two-layer architecture with a clear split of responsibilities:<\/p>\n\n\n\n\n\n
Layer<\/strong><\/td>\nResponsible for the state of<\/strong><\/td>\nRole in the DHTMLX starter demo<\/strong><\/td>\n<\/tr>\n
TanStack Query<\/td>\nTasks, links<\/td>\nManages server data fetched from and synchronized with the server <\/td>\n<\/tr>\n
Zustand<\/td>\nZoom config, undo\/redo history<\/td>\nManages local UI state that does not require server synchronization<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Before we move to integration details, let us elaborate on the main TanStack Query mechanisms required for server state workflow:<\/p>\n\n\n\n\n\n\n
TanStack API item<\/strong><\/td>\nMain function<\/strong><\/td>\nRole in the DHTMLX starter demo<\/strong><\/td>\n<\/tr>\n
useQuery<\/strong><\/td>\nReading server data<\/td>\nFetching and caching Gantt data (tasks+links)<\/td>\n<\/tr>\n
useMutation<\/strong><\/td>\nModifying server data<\/td>\nPerforming CRUD operations with tasks and links via API<\/td>\n<\/tr>\n
queryClient<\/strong><\/td>\nWorking with the query cache<\/td>\nproviding access to cached Gantt data and query operations<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Together, these API items organize the core data flow: useQuery<\/strong> loads tasks and links into the cache, useMutation<\/strong> sends user changes to the backend, and queryClient<\/strong> invalidates or updates the cache as needed.<\/p>\n

Now, it is high time to take a closer look at how these pieces come together in the React Gantt + TanStack Query starter.<\/p>\n

Bringing TanStack Query and Zustand Together in DHTMLX React Gantt<\/h2>\n

With the responsibilities of each layer clear, let’s see how they come together in code. We\u2019ll put aside some general configurations already encountered in the Zustand-only approach, and dwell only on what is specific to TanStack Query.<\/p>\n

Before we start, it is worth mentioning that our starter uses a minimal Express backend with JSON file storage to keep things simple and focus on the client-side integration. Swapping it out in a production application is straightforward, since the mutations work the same way regardless of what sits behind the API.<\/p>\n

Setting Up the Query Client<\/h3>\n

Every hook from the library needs access to a QueryClient<\/strong> instance. You create it once at the application root, outside the render function, and pass it to a QueryClientProvider<\/strong> that wraps the app. In this case, the client is reachable from anywhere in the tree.<\/p>\n

import<\/span> {<\/span> QueryClient,<\/span> QueryClientProvider }<\/span> from '@tanstack\/react-query'<\/span>;<\/span>
\n
\nconst<\/span> client =<\/span> new<\/span> QueryClient(<\/span>)<\/span>;<\/span>
\n
\ncreateRoot(<\/span>document.getElementById<\/span>(<\/span>'root'<\/span>)<\/span>!<\/span>)<\/span>.render<\/span>(<\/span>
\n  <<\/span>StrictMode><\/span>
\n    <<\/span>QueryClientProvider client=<\/span>{<\/span>client}<\/span>><\/span>
\n      <<\/span>App \/><\/span>
\n    <\/<\/span>QueryClientProvider><\/span>
\n  <\/<\/span>StrictMode>,<\/span>
\n)<\/span>;<\/span><\/div><\/div>\n

The client sits at module scope rather than inside App for a reason: creating a new QueryClient on every render would discard the existing cache. Every component inside the provider then shares the same instance.<\/p>\n

Fetching Gantt Data with useQuery<\/h3>\n

In the starter’s environment, the useQuery<\/strong> hook serves as the single source of truth for the chart’s data layer. One call of this hook pulls the whole dataset on mount:<\/p>\n

const<\/span> {<\/span>
\n  data:<\/span> fetchedData,<\/span>
\n  isLoading,<\/span>
\n  isError,<\/span>
\n  error,<\/span>
\n}<\/span> =<\/span> useQuery<<\/span>{<\/span> tasks:<\/span> SerializedTask[<\/span>]<\/span>;<\/span> links:<\/span> Link[<\/span>]<\/span> }<\/span>><\/span>(<\/span>{<\/span> queryKey:<\/span> [<\/span>'data'<\/span>]<\/span>,<\/span> queryFn:<\/span> fetchData }<\/span>)<\/span>;<\/span>
\n
\nconst<\/span> {<\/span> tasks,<\/span> links }<\/span> =<\/span> fetchedData ||<\/span> {<\/span> tasks:<\/span> [<\/span>]<\/span>,<\/span> links:<\/span> [<\/span>]<\/span> }<\/span>;<\/span><\/div><\/div>\n

The isLoading<\/strong> and isError<\/strong> values allow you to show a loading indicator or an error message before the chart is rendered. Returning early on either one keeps ReactGantt<\/strong> from ever seeing undefined data, and it prevents an empty Gantt from flashing while the request is in flight. The fallback to empty arrays keeps the destructuring safe while fetchedData<\/strong> is still undefined. It gives makeSnapshot()<\/strong> (the undo\/redo helper covered below) real arrays to clone before the first response arrives. <\/p>\n

Keeping two data collections (tasks and links) under one [‘data’]<\/strong> key is a deliberate simplification. One request brings both, and links never outrun their tasks. In this case, invalidating the key reloads everything. <\/p>\n

Passing Dates Between the Server and Gantt<\/h3>\n

JSON has no date type, so Date<\/strong> objects arrive from the server as plain strings. Anyone connecting the chart to a backend hits this. Starting from v9.1.3, React Gantt parses ISO strings automatically, but the starter spells the conversion out through templates. You still need them on earlier versions, or when your API does not use ISO 8601:<\/p>\n

const<\/span> templates:<\/span> ReactGanttProps[<\/span>'templates'<\/span>]<\/span> =<\/span> useMemo(<\/span>
\n  (<\/span>)<\/span> =><\/span> (<\/span>{<\/span>
\n    format_date:<\/span> (<\/span>d)<\/span> =><\/span> d.toISOString<\/span>(<\/span>)<\/span>,<\/span>
\n    parse_date:<\/span> (<\/span>s)<\/span> =><\/span> new<\/span> Date<\/span>(<\/span>s)<\/span>,<\/span>
\n  }<\/span>)<\/span>,<\/span>
\n  [<\/span>]<\/span>,<\/span>
\n)<\/span>;<\/span><\/div><\/div>\n

The parse_date<\/strong> defines how Gantt reads incoming dates, the format_date<\/strong> – how it writes them back. Gantt detects ISO strings automatically, so both overrides are optional. The starter keeps them to make the conversion visible. Delete them in your own project unless you are on an earlier version or your API does not use ISO 8601.<\/p>\n

Transferring Gantt UI Changes to the Server<\/h3>\n

Every user interaction (dragging a bar, drawing a dependency, deleting a task) is tracked via the data.save<\/strong> callback with the following signature:<\/p>\n

(<\/span>entity,<\/span> action,<\/span> payload,<\/span> id)<\/span> =><\/span> void<\/span><\/div><\/div>\n

Here, the entity is “task” or “link”, and the action is “create”, “update”, or “delete”. In the Zustand-only setup from the previous tutorial, this callback wrote to the store directly. Now it dispatches updates to one of six mutations, one per entity and action combination:<\/p>\n

const<\/span> data:<\/span> ReactGanttProps[<\/span>'data'<\/span>]<\/span> =<\/span> useMemo(<\/span>
\n  (<\/span>)<\/span> =><\/span> (<\/span>{<\/span>
\n    save:<\/span> (<\/span>entity,<\/span> action,<\/span> payload,<\/span> id)<\/span> =><\/span> {<\/span>
\n      if<\/span> (<\/span>entity ===<\/span> 'task'<\/span>)<\/span> {<\/span>
\n        const<\/span> task =<\/span> payload as SerializedTask;<\/span>
\n        if<\/span> (<\/span>action ===<\/span> 'create'<\/span>)<\/span> return<\/span> createTaskMutation.mutate<\/span>(<\/span>task)<\/span>;<\/span>
\n        else<\/span> if<\/span> (<\/span>action ===<\/span> 'update'<\/span>)<\/span> updateTaskMutation.mutate<\/span>(<\/span>task)<\/span>;<\/span>
\n        else<\/span> if<\/span> (<\/span>action ===<\/span> 'delete'<\/span>)<\/span> deleteTaskMutation.mutate<\/span>(<\/span>id)<\/span>;<\/span>
\n      }<\/span> else<\/span> if<\/span> (<\/span>entity ===<\/span> 'link'<\/span>)<\/span> {<\/span>
\n        const<\/span> link =<\/span> payload as Link;<\/span>
\n        if<\/span> (<\/span>action ===<\/span> 'create'<\/span>)<\/span> return<\/span> createLinkMutation.mutate<\/span>(<\/span>link)<\/span>;<\/span>
\n        else<\/span> if<\/span> (<\/span>action ===<\/span> 'update'<\/span>)<\/span> updateLinkMutation.mutate<\/span>(<\/span>link)<\/span>;<\/span>
\n        else<\/span> if<\/span> (<\/span>action ===<\/span> 'delete'<\/span>)<\/span> deleteLinkMutation.mutate<\/span>(<\/span>id)<\/span>;<\/span>
\n      }<\/span>
\n    }<\/span>,<\/span>
\n}<\/span>)<\/span>,<\/span> [<\/span>\/* mutation references *\/<\/span>]<\/span>)<\/span>;<\/span><\/div><\/div>\n

All six mutations share the same shape:<\/p>\n

const<\/span> createTaskMutation =<\/span> useMutation(<\/span>{<\/span>
\n  mutationFn:<\/span> createTask,<\/span>
\n  onMutate:<\/span> (<\/span>)<\/span> =><\/span> {<\/span>
\n    recordHistory(<\/span>makeSnapshot(<\/span>)<\/span>)<\/span>;<\/span>
\n  }<\/span>,<\/span>
\n  onSuccess:<\/span> (<\/span>)<\/span> =><\/span> queryClient.invalidateQueries<\/span>(<\/span>{<\/span> queryKey:<\/span> [<\/span>'data'<\/span>]<\/span> }<\/span>)<\/span>,<\/span>
\n  onError,<\/span>
\n}<\/span>)<\/span>;<\/span><\/div><\/div>\n

The useMutation<\/strong> hook allows you to run extra logic at different stages of a mutation through its lifecycle callbacks. The starter uses three of them. The onMutate<\/strong> callback fires first, pushing a copy of the current data onto the undo stack. After a successful request, the onSuccess<\/strong> callback refreshes cached data. If the request fails, the onError<\/strong> callback handles an error.<\/p>\n

For a detailed explanation of how data.save<\/strong> works, refer to the Data Binding & State Management basics<\/a> guide.<\/p>\n

Cache Invalidation vs Optimistic Updates in React Gantt<\/h3>\n

Optimistic updates are among the headline features of TanStack Query, and this is the one the starter leaves untouched. The demo backend shows why:<\/p>\n

app.post<\/span>(<\/span>'\/tasks'<\/span>,<\/span> (<\/span>req,<\/span> res)<\/span> =><\/span> {<\/span>
\n  const<\/span> db =<\/span> readDB(<\/span>)<\/span>;<\/span>
\n  const<\/span> task =<\/span> req.body<\/span> as Task;<\/span>
\n  const<\/span> newTask =<\/span> {<\/span> ...task<\/span>,<\/span> id:<\/span> `DB_ID:<\/span>${<\/span>task.id<\/span>}<\/span>` }<\/span>;<\/span>
\n  db.tasks<\/span>.push<\/span>(<\/span>newTask)<\/span>;<\/span>
\n  writeDB(<\/span>db)<\/span>;<\/span>
\n  res.json<\/span>(<\/span>newTask)<\/span>;<\/span>
\n}<\/span>)<\/span>;<\/span><\/div><\/div>\n

The server does not accept client IDs. The backend generates a new ID with a DB_ID:<\/strong> prefix, the way most backends with auto-increment or UUID keys do.<\/p>\n

When a user creates a task, the Gantt generates a temporary client-side ID and draws the row. The real ID only exists after the server responds. Every link referencing that task has to point at the new value. Writing an optimistic row into the cache would mean writing a row with an ID you already know is wrong. So the starter refetches after the response and treats the server’s answer as authoritative.<\/p>\n

The notable exception is an API that accepts client-generated UUIDs. If yours does, the ID is known before the request, and optimistic creates become a real option.<\/p>\n

React Gantt has a first-class mechanism for this case, and the starter skips it. If save<\/strong> returns a promise that resolves to { id: newId }<\/strong>, the chart swaps the temporary ID for the permanent one itself and repoints the links that referenced it. No refetch involved. With TanStack Query, it means reaching for mutateAsync<\/strong> instead of mutate<\/strong>:<\/p>\n

if<\/span> (<\/span>action ===<\/span> 'create'<\/span>)<\/span> {<\/span>
\n  return<\/span> createTaskMutation.mutateAsync<\/span>(<\/span>payload as SerializedTask)<\/span>
\n    .then<\/span>(<\/span>(<\/span>saved)<\/span> =><\/span> (<\/span>{<\/span> id:<\/span> saved.id<\/span> }<\/span>)<\/span>)<\/span>;<\/span>
\n}<\/span><\/div><\/div>\n

The api.ts<\/strong> helpers already return the parsed response body from the create calls, so the ID is right there. The starter discards it. What you buy by ignoring it is uniformity: all six mutations end up with the same shape, and there is one reconciliation strategy to reason about instead of two. That trade works for a demo. On a chart with thousands of rows it stops working, because a full refetch per creation is the cost you were trying to avoid in the first place.<\/p>\n

Updates and deletes do not have this problem, since their IDs are already stable. You can apply them optimistically to make the app more responsive. A reasonable middle ground is to keep creation authoritative (via the returned ID or a refetch) and make updates optimistic, rather than committing to a single strategy for all six mutations.<\/p>\n

Complementing React Gantt with Undo\/Redo Functionality<\/h3>\n

The undo operation involves both layers, because data and its history live in different places. Zustand holds stacks and stores plain snapshots:<\/p>\n

export<\/span> type Snapshot =<\/span> {<\/span>
\n  tasks:<\/span> SerializedTask[<\/span>]<\/span>;<\/span>
\n  links:<\/span> Link[<\/span>]<\/span>;<\/span>
\n  config:<\/span> GanttConfig;<\/span>
\n}<\/span>;<\/span><\/div><\/div>\n

Keeping config next to the data means a zoom change is undone along with the edit. Users notice immediately when that is missing. The makeSnapshot<\/strong> helper clones all three with structuredClone<\/strong>, since the chart edits its task objects in place. The stacks are capped at 50 entries, and pushing a snapshot clears the redo branch, as users expect.<\/p>\n

Undo and redo actions in the store take the current snapshot and return the target one. They never import queryClient<\/strong> and have no idea where the data they are shuffling lives. The component is the only place the two layers meet:<\/p>\n

const<\/span> handleUndo =<\/span> (<\/span>)<\/span> =><\/span> {<\/span>
\n  const<\/span> snapshot =<\/span> undo(<\/span>makeSnapshot(<\/span>)<\/span>)<\/span>;<\/span>
\n  if<\/span> (<\/span>snapshot)<\/span> {<\/span>
\n    queryClient.setQueryData<\/span>(<\/span>[<\/span>'data'<\/span>]<\/span>,<\/span> snapshot)<\/span>;<\/span>
\n  }<\/span>
\n}<\/span>;<\/span><\/div><\/div>\n

Because setQueryData<\/strong> bypasses the network, the chart redraws instantly. Tasks and links come back through the cache. The zoom level travels a different route: undo updates config in the store, and the chart receives it through the config prop.<\/p>\n

One boundary is worth stating plainly: undo restores the cache and tells the server nothing. With the library defaults, data goes stale immediately and is refetched on window focus or remount, so the undone change comes back. Raising staleTime<\/strong> and disabling refetchOnWindowFocus<\/strong> narrows that window. If undo has to be durable, route it through a mutation like any other change. Send the restored snapshot to a batch endpoint and let onSuccess invalidate. Only handleUndo<\/strong> changes. The Zustand store stays as it is.<\/p>\n

For more information on integrating DHTMLX React Gantt with TanStack Query and Zustand, check out the official guide<\/a> available in our documentation.<\/p>\n

Wrapping Up<\/h2>\n

The combination of TanStack Query is a practical solution for handling both server and local state in React Gantt apps. With TanStack Query, you don’t have to worry about fetching, caching, and synchronizing Gantt data with the backend, while Zustand deals with the local UI state (undo\/redo, zooming). This clear separation of responsibilities gives a flexible React state management setup and simplifies the overall maintainability of the application architecture. Our starter demo and the official integration guide can help you apply this approach in real projects built around DHTMLX React Gantt.<\/p>\n

Related Materials<\/h2>\n