TypeScript version support window
TanStack Query follows DefinitelyTyped's support window and supports TypeScript versions released within the last 2 years. As of the current documentation, that means TypeScript 5.6 and newer.
TanStack Query · React · all subjects
typescript integration
18 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Type changes are non-breaking patch releases
Changes to types in the TanStack Query repository are considered non-breaking and are usually released as patch semver changes. This means type enhancements can occur between any release without a major version bump.
Lock package version for type safety
It is highly recommended that you lock your react-query package version to a specific patch release and upgrade with the expectation that types may be fixed or upgraded between any release.
Type inference in useQuery
Types in React Query generally flow through very well so that you don't have to provide type annotations. The data type is inferred from the return type of the queryFn. For example, if queryFn returns Promise<number>, data will be typed as number | undefined.
Type inference with select function
When using a select function in useQuery, the data type is inferred from the return type of the select function. For example, if queryFn returns a number and select transforms it to a string, data will be typed as string | undefined.
Type inference requires well-defined queryFn return type
Type inference works best if your queryFn has a well-defined returned type. Most data fetching libraries return any per default, so it is recommended to extract the fetch logic to a properly typed function that returns a specific type like Promise<Group[]>.
Type narrowing with status flags
React Query uses a discriminated union type for the query result, discriminated by the status field and derived status boolean flags. You can check for success status to narrow the data type. For example, checking if (isSuccess) will narrow data from number | undefined to number.
Default error type is Error
The type for the error field in useQuery defaults to Error, because that is what most users expect. The type is Error | null.
Custom error type with generic parameter
You can specify a custom error type by using a generic parameter on useQuery. For example, useQuery<Group[], string> will type the error field as string | null. However, this approach has the drawback that type inference for all other generics of useQuery will not work anymore.
Type narrowing for custom errors
Instead of specifying a custom error type as a generic parameter, it is recommended to use type narrowing to make the error field more specific. For example, you can check if (axios.isAxiosError(error)) to narrow the error type to AxiosError while preserving type inference for other query properties.
Register global error type
TanStack Query v5 allows setting a global Error type for everything by amending the Register interface in a module declaration. This makes sure inference still works while the error field is of the specified type. You can set defaultError to unknown to enforce that call sites must do explicit type-narrowing.
Register global Meta type
You can register a global Meta type similarly to registering a global error type by adding queryMeta and mutationMeta to the Register interface. The registered type must extend Record<string, unknown> so that meta remains an object. This ensures the optional meta field on queries and mutations stays consistent and is type-safe.
Register global QueryKey and MutationKey types
You can register global QueryKey and MutationKey types by adding them to the Register interface. The registered types must extend the Array type so that keys remain an array. This allows you to provide more structure to your keys that matches your application's hierarchy and have them be typed across all of the library's surface area.
queryOptions helper for type inference
The queryOptions helper preserves type inference when extracting query options into a separate function to share between useQuery and prefetchQuery. This helper allows you to use the query options in multiple places while maintaining type safety, unlike inlining options directly.
queryOptions with queryClient.getQueryData
When using queryOptions, the queryKey returned knows about the associated queryFn, which allows queryClient.getQueryData to infer types. For example, queryClient.getQueryData(groupOptions().queryKey) will type data as Group[] | undefined without needing to pass a generic type parameter.
Type inference limitations with getQueriesData
Type inference via queryOptions does not work for queryClient.getQueriesData because it returns an array of tuples with heterogeneous, unknown data. If you are sure of the type of data that your query will return, you must specify it explicitly as a generic parameter.
mutationOptions helper for type inference
Similar to queryOptions, you can use mutationOptions to extract mutation options into a separate function for type-safe reuse. This works with useMutation, useIsMutating, and queryClient.isMutating.
skipToken for typesafe query disabling
In TypeScript, you can use skipToken to disable a query based on a condition while keeping the query type-safe. This is the recommended approach for conditionally disabling queries.