Open History to see the last commit
1---
2id: overview
3title: Overview
4---
5β
6TanStack Query (formerly known as React Query) is often described as the missing data-fetching library for web applications, but in more technical terms, it makes **fetching, caching, synchronizing and updating server state** in your web applications a breeze.
7β
8## Motivation
9β
10Most core web frameworks **do not** come with an opinionated way of fetching or updating data in a holistic way. Because of this developers end up building either meta-frameworks which encapsulate strict opinions about data-fetching, or they invent their own ways of fetching data. This usually means cobbling together component-based state and side-effects, or using more general purpose state management libraries to store and provide asynchronous data throughout their apps.
11β
12While most traditional state management libraries are great for working with client state, they are **not so great at working with async or server state**. This is because **server state is totally different**. For starters, server state:
13β
14- Is persisted remotely in a location you may not control or own
15- Requires asynchronous APIs for fetching and updating
16- Implies shared ownership and can be changed by other people without your knowledge
17- Can potentially become "out of date" in your applications if you're not careful
18β
19Once you grasp the nature of server state in your application, **even more challenges will arise** as you go, for example:
20β
21- Caching... (possibly the hardest thing to do in programming)
22- Deduping multiple requests for the same data into a single request
23- Updating "out of date" data in the background
24- Knowing when data is "out of date"
25- Reflecting updates to data as quickly as possible
26- Performance optimizations like pagination and lazy loading data
27- Managing memory and garbage collection of server state
28- Memoizing query results with structural sharing
29β
30If you're not overwhelmed by that list, then that must mean that you've probably solved all of your server state problems already and deserve an award. However, if you are like a vast majority of people, you either have yet to tackle all or most of these challenges and we're only scratching the surface!
31β
32TanStack Query is hands down one of the _best_ libraries for managing server state. It works amazingly well **out-of-the-box, with zero-config, and can be customized** to your liking as your application grows.
33β
34TanStack Query allows you to defeat and overcome the tricky challenges and hurdles of _server state_ and control your app data before it starts to control you.
35β
36On a more technical note, TanStack Query will likely:
37β
38- Help you remove **many** lines of complicated and misunderstood code from your application and replace with just a handful of lines of TanStack Query logic
39- Make your application more maintainable and easier to build new features without worrying about wiring up new server state data sources
40- Have a direct impact on your end-users by making your application feel faster and more responsive than ever before
41- Potentially help you save on bandwidth and increase memory performance
42β
43[//]: # 'Example'
44β
45## Enough talk, show me some code already!
46β
47In the example below, you can see TanStack Query in its most basic and simple form being used to fetch the GitHub stats for the TanStack Query GitHub project itself:
48β
49[Open in StackBlitz](https://stackblitz.com/github/TanStack/query/tree/main/examples/react/simple)
50β
51```tsx
52import {
53 QueryClient,
54 QueryClientProvider,
55 useQuery,
56} from '@tanstack/react-query'
57β
58const queryClient = new QueryClient()
59β
60export default function App() {
61 return (
62 <QueryClientProvider client={queryClient}>
63 <Example />
64 </QueryClientProvider>
65 )
66}
67β
68function Example() {
69 const { isPending, error, data } = useQuery({
70 queryKey: ['repoData'],
71 queryFn: () =>
72 fetch('https://api.github.com/repos/TanStack/query').then((res) =>
73 res.json(),
74 ),
75 })
76β
77 if (isPending) return 'Loading...'
78β
79 if (error) return 'An error has occurred: ' + error.message
80β
81 return (
82 <div>
83 <h1>{data.name}</h1>
84 <p>{data.description}</p>
85 <strong>π {data.subscribers_count}</strong>{' '}
86 <strong>β¨ {data.stargazers_count}</strong>{' '}
87 <strong>π΄ {data.forks_count}</strong>
88 </div>
89 )
90}
91```
92β
93[//]: # 'Example'
94[//]: # 'Materials'
95β
96## You talked me into it, so what now?
97β
98- Consider taking the official [TanStack Query Course](https://query.gg?s=tanstack) (or buying it for your whole team!)
99- Learn TanStack Query at your own pace with our amazingly thorough [Walkthrough Guide](./installation.md) and [API Reference](./reference/useQuery.md)
100- See the Article [Why You Want React Query](https://tkdodo.eu/blog/why-you-want-react-query).
101β
102[//]: # 'Materials'