> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/TanStack/query/llms.txt > Use this file to discover all available pages before exploring further. # useQuery > React hook for fetching and caching data # useQuery The `useQuery` hook is the primary way to fetch and cache data in TanStack Query. It subscribes to a query and returns the current state of the query. ## Import ```tsx theme={null} import { useQuery } from '@tanstack/react-query' ``` ## Signature ```tsx theme={null} function useQuery< TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, >( options: UseQueryOptions, queryClient?: QueryClient, ): UseQueryResult ``` ## Type Parameters The type of data returned by the query function The type of error that can be thrown by the query function The type of data returned by the select function (if provided), otherwise same as TQueryFnData The type of the query key ## Parameters Configuration options for the query A unique key for the query. Must be an array. The function that will be called to fetch data. Receives a `QueryFunctionContext` object. Set to `false` to disable automatic query execution Time in milliseconds after data is considered stale. Set to `Infinity` to disable automatic refetching. Time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. If set to a number, the query will continuously refetch at this frequency in milliseconds If set to `true`, the query will continue to refetch while the window is in the background If set to `true`, the query will refetch on window focus if the data is stale If set to `true`, the query will refetch on mount if the data is stale If set to `true`, the query will refetch on reconnect if the data is stale Number of retry attempts or function to determine if a request should be retried Function that receives a retry attempt number and returns the delay to apply before the next attempt Function to transform or select a part of the data returned by the query function If set, this value will be used as the initial data for the query (as long as the query hasn't been created or cached yet) If set, this value will be used as the time (in milliseconds) of when the initialData itself was last updated If set, this value will be used as the placeholder data for this particular query observer while the query is still in the pending state Set this to `false` to disable structural sharing between query results Set this to `true` if you want errors to be thrown in the render phase and propagate to the nearest error boundary Controls when the query function is allowed to execute If set, the component will only re-render when one of the listed properties change Optional metadata that can be used by query client plugins Set this to `false` to unsubscribe this observer from updates to the query cache Optional QueryClient instance to use. If not provided, the client from the nearest `QueryClientProvider` will be used. ## Returns The data returned by the query function (or `undefined` if the query hasn't successfully fetched yet) The error object for the query, if an error occurred The status of the query: * `pending`: The query has no data yet * `error`: The query encountered an error * `success`: The query was successful and data is available The fetch status of the query: * `fetching`: The query is currently fetching * `paused`: The query wanted to fetch, but it is paused * `idle`: The query is not fetching Derived from `status`. Will be `true` if the query is in `pending` status Derived from `status`. Will be `true` if the query is in `success` status Derived from `status`. Will be `true` if the query is in `error` status Derived from `fetchStatus`. Will be `true` whenever the query is fetching (including background refetching) Shorthand for `isPending && isFetching` - useful for showing a loading spinner on initial load Will be `true` if the query failed while fetching for the first time Will be `true` if the query failed while refetching Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime` Will be `true` if the data shown is placeholder data Function to manually refetch the query Timestamp of when the data was last updated Timestamp of when the error was last updated The failure count for the query The failure reason for the query retry ## Examples ### Basic Usage ```tsx theme={null} import { useQuery } from '@tanstack/react-query' function TodoList() { const { data, isPending, isError, error } = useQuery({ queryKey: ['todos'], queryFn: async () => { const response = await fetch('/api/todos') if (!response.ok) { throw new Error('Network response was not ok') } return response.json() }, }) if (isPending) return

if (isError) return

Error: {error.message}

return (

{todo.title}

) } ``` ### With Type Safety ```tsx theme={null} interface Todo { id: number title: string completed: boolean } function TodoList() { const { data } = useQuery({ queryKey: ['todos'], queryFn: async () => { const response = await fetch('/api/todos') return response.json() }, }) // data is typed as Todo[] | undefined } ``` ### With Data Transformation ```tsx theme={null} function TodoList() { const { data } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos, select: (data) => data.filter((todo) => !todo.completed), }) // Only incomplete todos are returned } ``` ### Conditional Queries ```tsx theme={null} function User({ userId }: { userId?: string }) { const { data } = useQuery({ queryKey: ['user', userId], queryFn: () => fetchUser(userId!), enabled: !!userId, // Only run query if userId is truthy }) } ``` ### With Stale Time ```tsx theme={null} function TodoList() { const { data } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos, staleTime: 1000 * 60 * 5, // Data stays fresh for 5 minutes }) } ``` ## Source Implementation: [useQuery.ts:50](~/workspace/source/packages/react-query/src/useQuery.ts)