TanStack Query

https://tanstack.com/query/latest/docs/
Admin
TanStack Query is a powerful data synchronization library for managing server state, caching, and...
Tokens:756,146
Snippets:4,937
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Nuxt 3 Minimal Starter README

Source: https://tanstack.com/query/latest/docs/framework/vue/examples/nuxt3

README setup instructions detailing dependency installation, development server startup, and production build commands for the Nuxt 3 example.

```markdown
# Nuxt 3 Minimal Starter

We recommend looking at the [documentation](https://nuxt.com/docs/3.x/getting-started/introduction).

## Setup

Make sure to install the dependencies

```bash
pnpm install
```

## Development

Start the development server on http://localhost:3000

```bash
pnpm dev
```

## Production

Build the application for production:

```bash
pnpm build
```

Check out the [deployment documentation](https://nuxt.com/docs/3.x/getting-started/deployment).
```

--------------------------------

### Run the Svelte Star Wars example

Source: https://tanstack.com/query/latest/docs/framework/svelte/examples/star-wars

README setup instructions detailing how to install dependencies and run the development server for the Svelte Star Wars example.

```markdown
# Example

This example is a rewrite of the React Query star-wars example.

To run this example:

- `npm install`
- `npm run dev`
```

--------------------------------

### Basic Solid Query setup and query example

Source: https://tanstack.com/query/latest/docs/framework/solid/quick-start.md

Sets up a QueryClient and wraps the application in QueryClientProvider. Uses useQuery with an accessor returning query options to handle loading, error, and success states in SolidJS.

```tsx
import {
  QueryClient,
  QueryClientProvider,
  useQuery,
} from '@tanstack/solid-query'
import { Switch, Match, For } from 'solid-js'

const queryClient = new QueryClient()

function Example() {
  const query = useQuery(() => ({
    queryKey: ['todos'],
    queryFn: fetchTodos,
  }))

  return (
    <div>
      <Switch>
        <Match when={query.isPending}>
          <p>Loading...</p>
        </Match>
        <Match when={query.isError}>
          <p>Error: {query.error.message}</p>
        </Match>
        <Match when={query.isSuccess}>
          <For each={query.data}>{(todo) => <p>{todo.title}</p>}</For>
        </Match>
      </Switch>
    </div>
  )
}

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Example />
    </QueryClientProvider>
  )
}
```

--------------------------------

### Quick Start Example with Queries, Mutations, and Invalidation

Source: https://tanstack.com/query/latest/docs/framework/react/quick-start.md

Illustrates how to initialize QueryClient, wrap components in QueryClientProvider, fetch todos using useQuery, perform mutations with useMutation, and invalidate queries on success.

```tsx
import {
  useQuery,
  useMutation,
  useQueryClient,
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'
import { getTodos, postTodo } from '../my-api'

// Create a client
const queryClient = new QueryClient()

function App() {
  return (
    // Provide the client to your App
    <QueryClientProvider client={queryClient}>
      <Todos />
    </QueryClientProvider>
  )
}

function Todos() {
  // Access the client
  const queryClient = useQueryClient()

  // Queries
  const query = useQuery({ queryKey: ['todos'], queryFn: getTodos })

  // Mutations
  const mutation = useMutation({
    mutationFn: postTodo,
    onSuccess: () => {
      // Invalidate and refetch
      queryClient.invalidateQueries({ queryKey: ['todos'] })
    },
  })

  return (
    <div>
      <ul>
        {query.data?.map((todo) => (
          <li key={todo.id}>{todo.title}</li>
        ))}
      </ul>

      <button
        onClick={() => {
          mutation.mutate({
            id: Date.now(),
            title: 'Do Laundry',
          })
        }}
      >
        Add Todo
      </button>
    </div>
  )
}

render(<App />, document.getElementById('root'))
```

--------------------------------

### Install with bun

Source: https://tanstack.com/query/latest/docs/framework/preact/plugins/createAsyncStoragePersister.md

Install query-async-storage-persister and preact-query-persist-client packages via bun.

```bash
bun add @tanstack/query-async-storage-persister @tanstack/preact-query-persist-client
```

--------------------------------

### Install with pnpm

Source: https://tanstack.com/query/latest/docs/framework/preact/plugins/createAsyncStoragePersister.md

Install query-async-storage-persister and preact-query-persist-client packages via pnpm.

```bash
pnpm add @tanstack/query-async-storage-persister @tanstack/preact-query-persist-client
```

--------------------------------

### Install with npm

Source: https://tanstack.com/query/latest/docs/framework/preact/plugins/createAsyncStoragePersister.md

Install query-async-storage-persister and preact-query-persist-client packages via npm.

```bash
npm install @tanstack/query-async-storage-persister @tanstack/preact-query-persist-client
```

--------------------------------

### Install with yarn

Source: https://tanstack.com/query/latest/docs/framework/preact/plugins/createAsyncStoragePersister.md

Install query-async-storage-persister and preact-query-persist-client packages via yarn.

```bash
yarn add @tanstack/query-async-storage-persister @tanstack/preact-query-persist-client
```

--------------------------------

### Install Lit Query with bun

Source: https://tanstack.com/query/latest/docs/framework/lit/installation.md

Install `@tanstack/lit-query`, `@tanstack/query-core`, and `lit` using bun. Explicitly install `@tanstack/query-core` as it is a peer dependency.

```bash
bun add @tanstack/lit-query @tanstack/query-core lit
```

--------------------------------

### Install with Bun

Source: https://tanstack.com/query/latest/docs/framework/svelte/installation.md

Install the @tanstack/svelte-query package using Bun.

```bash
bun add @tanstack/svelte-query
```

--------------------------------

### Install Lit Query with pnpm

Source: https://tanstack.com/query/latest/docs/framework/lit/installation.md

Install `@tanstack/lit-query`, `@tanstack/query-core`, and `lit` using pnpm. Explicitly install `@tanstack/query-core` as it is a peer dependency.

```bash
pnpm add @tanstack/lit-query @tanstack/query-core lit
```

--------------------------------

### Install @tanstack/query-persist-client-core with bun

Source: https://tanstack.com/query/latest/docs/framework/preact/plugins/createPersister.md

Install the query persister core package using bun.

```bash
bun add @tanstack/query-persist-client-core
```

--------------------------------

### Install with Yarn

Source: https://tanstack.com/query/latest/docs/framework/svelte/installation.md

Install the @tanstack/svelte-query package using Yarn.

```bash
yarn add @tanstack/svelte-query
```

--------------------------------

### Install with npm

Source: https://tanstack.com/query/latest/docs/framework/svelte/installation.md

Install the @tanstack/svelte-query package using npm.

```bash
npm i @tanstack/svelte-query
```

--------------------------------

### Install Vue Query with bun

Source: https://tanstack.com/query/latest/docs/framework/vue/installation

Install the @tanstack/vue-query package using bun.

```bash
bun add @tanstack/vue-query
```

--------------------------------

### Install @tanstack/query-persist-client-core

Source: https://tanstack.com/query/latest/docs/framework/vue/plugins/createPersister.md

Install the @tanstack/query-persist-client-core package using your preferred package manager.

```bash
npm install @tanstack/query-persist-client-core
```

```bash
pnpm add @tanstack/query-persist-client-core
```

```bash
yarn add @tanstack/query-persist-client-core
```

```bash
bun add @tanstack/query-persist-client-core
```

--------------------------------

### Install @tanstack/preact-query with deno

Source: https://tanstack.com/query/latest/docs/framework/preact/installation.md

Installs the Preact Query package using Deno.

```bash
deno add @tanstack/preact-query
```

--------------------------------

### Install @tanstack/query-persist-client-core with yarn

Source: https://tanstack.com/query/latest/docs/framework/preact/plugins/createPersister.md

Install the query persister core package using yarn.

```bash
yarn add @tanstack/query-persist-client-core
```

--------------------------------

### Install @tanstack/preact-query-devtools with Bun

Source: https://tanstack.com/query/latest/docs/framework/preact/devtools.md

Installs the Preact Query devtools package using Bun.

```bash
bun add @tanstack/preact-query-devtools
```

--------------------------------

### Install @tanstack/query-persist-client-core with pnpm

Source: https://tanstack.com/query/latest/docs/framework/preact/plugins/createPersister.md

Install the query persister core package using pnpm.

```bash
pnpm add @tanstack/query-persist-client-core
```

--------------------------------

### Use useQuery with <script setup>

Source: https://tanstack.com/query/latest/docs/framework/vue/installation

Example of using useQuery inside a <script setup> block, returning reactive properties for the template.

```vue
<script setup>
import { useQuery } from '@tanstack/vue-query'

const { isPending, isFetching, isError, data, error } = useQuery({
  queryKey: ['todos'],
  queryFn: getTodos,
})
</script>

<template>...</template>
```

--------------------------------

### useQueryClient(id?)

Source: https://tanstack.com/query/latest/docs/framework/vue/reference/functions/useQueryClient.md

Retrieves the QueryClient installed by VueQueryPlugin via Vue's inject. Must be called inside setup() or another function that supports an injection context.

```APIDOC
## useQueryClient(id?)

### Description
Retrieves the `QueryClient` installed by `VueQueryPlugin`, via Vue's `inject`. Must be called inside `setup()` or another function that supports an injection context.

### Signature
```ts
function useQueryClient(id?: string): QueryClient;
```

### Parameters
- **id** (`string`, optional, default: `''`) - The `queryClientKey` passed to `VueQueryPlugin` — only needed when multiple `QueryClient`s are installed in the same app.

### Returns
- **QueryClient** - The installed `QueryClient`.

### Throws
- Throws an error if called outside an injection context, or if no `QueryClient` was installed via `VueQueryPlugin`.

### Example
```vue
<script setup lang="ts">
import { useQueryClient } from '@tanstack/vue-query'

const queryClient = useQueryClient()

function invalidate() {
  queryClient.invalidateQueries({ queryKey: ['todos'] })
}
</script>
```
```

--------------------------------

### Install with bun

Source: https://tanstack.com/query/latest/docs/framework/react/plugins/createSyncStoragePersister.md

Install the sync storage persister and React Query persist client plugins via Bun.

```bash
bun add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client
```

--------------------------------

### Basic TanStack Query setup and query handling in SolidJS

Source: https://tanstack.com/query/latest/docs/framework/solid/examples/basic

Demonstrates setting up QueryClient, fetching post lists and post details with useQuery, and rendering query status with Solid's Switch and Match components. Caches query data with a custom gcTime and shows how to inspect cache state with queryClient.getQueryData.

```tsx
/* @refresh reload */
import {
  QueryClient,
  QueryClientProvider,
  useQuery,
} from '@tanstack/solid-query'
import { SolidQueryDevtools } from '@tanstack/solid-query-devtools'
import { For, Match, Switch, createSignal } from 'solid-js'
import { render } from 'solid-js/web'
import type { Component, Setter } from 'solid-js'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 60 * 24, // 24 hours
    },
  },
})

type Post = {
  id: number
  title: string
  body: string
}

function createPosts() {
  return useQuery(() => ({
    queryKey: ['posts'],
    queryFn: async (): Promise<Array<Post>> => {
      const response = await fetch('https://jsonplaceholder.typicode.com/posts')
      return await response.json()
    },
  }))
}

function Posts(props: { setPostId: Setter<number> }) {
  const state = createPosts()

  return (
    <div>
      <h1>Posts</h1>
      <div>
        <Switch>
          <Match when={state.status === 'pending'}>Loading...</Match>
          <Match when={state.status === 'error'}>
            <span>Error: {(state.error as Error).message}</span>
          </Match>
          <Match when={state.data !== undefined}>
            <>
              <div>
                <For each={state.data}>
                  {(post) => (
                    <p>
                      <a
                        onClick={() => props.setPostId(post.id)}
                        href="#"
                        style={
                          // We can access the query data here to show bold links for
                          // ones that are cached
                          queryClient.getQueryData(['post', post.id])
                            ? {
                                'font-weight': 'bold',
                                color: 'green',
                              }
                            : {}
                        }
                      >
                        {post.title}
                      </a>
                    </p>
                  )}
                </For>
              </div>
              <div>{state.isFetching ? 'Background Updating...' : ' '}</div>
            </>
          </Match>
        </Switch>
      </div>
    </div>
  )
}

const getPostById = async (id: number): Promise<Post> => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/posts/${id}`,
  )
  return await response.json()
}

function createPost(postId: number) {
  return useQuery(() => ({
    queryKey: ['post', postId],
    queryFn: () => getPostById(postId),
    enabled: !!postId,
  }))
}

function Post(props: { postId: number; setPostId: Setter<number> }) {
  const state = createPost(props.postId)

  return (
    <div>
      <div>
        <a onClick={() => props.setPostId(-1)} href="#">
          Back
        </a>
      </div>
      <Switch>
        <Match when={!props.postId || state.status === 'pending'}>
          Loading...
        </Match>
        <Match when={state.status === 'error'}>
          <span>Error: {(state.error as Error).message}</span>
        </Match>
        <Match when={state.data !== undefined}>
          <>
            <h1>{state.data?.title}</h1>
            <div>
              <p>{state.data?.body}</p>
            </div>
            <div>{state.isFetching ? 'Background Updating...' : ' '}</div>
          </>
        </Match>
      </Switch>
    </div>
  )
}

const App: Component = () => {
  const [postId, setPostId] = createSignal(-1)

  return (
    <QueryClientProvider client={queryClient}>
      <SolidQueryDevtools />
      <p>
        As you visit the posts below, you will notice them in a loading state
        the first time you load them. However, after you return to this list and
        click on any posts you have already visited again, you will see them
        load instantly and background refresh right before your eyes!{' '}
        <strong>
          (You may need to throttle your network speed to simulate longer
          loading sequences)
        </strong>
      </p>
      {postId() > -1 ? (
        <Post postId={postId()} setPostId={setPostId} />
      ) : (
        <Posts setPostId={setPostId} />
      )}
    </QueryClientProvider>
  )
}

const root = document.getElementById('root')
if (!root) throw new Error('Missing #root element')

render(() => <App />, root)
```

--------------------------------

### Invalidating queries using key prefix matching in Angular

Source: https://tanstack.com/query/latest/docs/framework/angular/guides/query-invalidation.md

Demonstrates invalidating all queries whose keys start with a given prefix. In this example, both the basic todos query and the paginated todos query are invalidated.

```ts
import { injectQuery, QueryClient } from '@tanstack/angular-query-experimental'

class QueryInvalidationExample {
  readonly queryClient = inject(QueryClient)

  invalidateQueries() {
    this.queryClient.invalidateQueries({ queryKey: ['todos'] })
  }

  // Both queries below will be invalidated
  todoListQuery = injectQuery(() => ({
    queryKey: ['todos'],
    queryFn: fetchTodoList,
  }))
  todoListQuery = injectQuery(() => ({
    queryKey: ['todos', { page: 1 }],
    queryFn: fetchTodoList,
  }))
}
```

--------------------------------

### README.md create-svelte project setup

Source: https://tanstack.com/query/latest/docs/framework/svelte/examples/auto-refetching

Standard README documentation outlining project creation, development server execution, and production build commands for Svelte.

```markdown
# create-svelte

Everything you need to build a Svelte project, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/master/packages/create-svelte).

## Creating a project

If you're seeing this, you've probably already done this step. Congrats!

```bash
# create a new project in the current directory
npm create svelte@latest

# create a new project in my-app
npm create svelte@latest my-app
```

## Developing

Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn` or `bun install`), start a development server:

```bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open
```

## Building

To create a production version of your app:

```bash
npm run build
```

You can preview the production build with `npm run preview`.

> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment.
```

--------------------------------

### Install Lit Query with yarn

Source: https://tanstack.com/query/latest/docs/framework/lit/installation.md

Install `@tanstack/lit-query`, `@tanstack/query-core`, and `lit` using yarn. Explicitly install `@tanstack/query-core` as it is a peer dependency.

```bash
yarn add @tanstack/lit-query @tanstack/query-core lit
```

--------------------------------

### Install Lit Query with npm

Source: https://tanstack.com/query/latest/docs/framework/lit/installation.md

Install `@tanstack/lit-query`, `@tanstack/query-core`, and `lit` using npm. Explicitly install `@tanstack/query-core` as it is a peer dependency.

```bash
npm i @tanstack/lit-query @tanstack/query-core lit
```

--------------------------------

### Install packages using bun

Source: https://tanstack.com/query/latest/docs/framework/react/plugins/createAsyncStoragePersister.md

Installs the async storage persister and the React Query persist client plugin using bun.

```bash
bun add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client
```

--------------------------------

### Install with pnpm

Source: https://tanstack.com/query/latest/docs/framework/react/plugins/createSyncStoragePersister.md

Install the sync storage persister and React Query persist client plugins via pnpm.

```bash
pnpm add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client
```

--------------------------------

### Install with npm

Source: https://tanstack.com/query/latest/docs/framework/react/plugins/createSyncStoragePersister.md

Install the sync storage persister and React Query persist client plugins via npm.

```bash
npm install @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client
```

--------------------------------

### Install with pnpm

Source: https://tanstack.com/query/latest/docs/framework/svelte/installation.md

Install the @tanstack/svelte-query package using pnpm.

```bash
pnpm add @tanstack/svelte-query
```

--------------------------------

### Install with yarn

Source: https://tanstack.com/query/latest/docs/framework/react/plugins/createSyncStoragePersister.md

Install the sync storage persister and React Query persist client plugins via Yarn.

```bash
yarn add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client
```

--------------------------------

### Install packages using npm

Source: https://tanstack.com/query/latest/docs/framework/react/plugins/createAsyncStoragePersister.md

Installs the async storage persister and the React Query persist client plugin using npm.

```bash
npm install @tanstack/query-async-storage-persister @tanstack/react-query-persist-client
```

--------------------------------

### Basic TanStack Solid Query setup with useQuery and QueryClientProvider

Source: https://tanstack.com/query/latest/docs/framework/solid/examples/simple

Sets up a TanStack QueryClientProvider, attaches the devtools, and uses useQuery to fetch asynchronous data from an API. Solid's Switch and Match components handle isPending, error, and data rendering states.

```tsx
/* @refresh reload */
import {
  QueryClient,
  QueryClientProvider,
  useQuery,
} from '@tanstack/solid-query'
import { SolidQueryDevtools } from '@tanstack/solid-query-devtools'
import { Match, Switch } from 'solid-js'
import { render } from 'solid-js/web'

const queryClient = new QueryClient()

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <SolidQueryDevtools />
      <Example />
    </QueryClientProvider>
  )
}

function Example() {
  const state = useQuery(() => ({
    queryKey: ['repoData'],
    queryFn: async () => {
      const response = await fetch(
        'https://api.github.com/repos/TanStack/query',
      )
      return await response.json()
    },
  }))

  return (
    <Switch>
      <Match when={state.isPending}>Loading...</Match>
      <Match when={state.error}>
        {'An error has occurred: ' + (state.error as Error).message}
      </Match>
      <Match when={state.data !== undefined}>
        <div>
          <h1>{state.data.name}</h1>
          <p>{state.data.description}</p>
          <strong>👀 {state.data.subscribers_count}</strong>{' '}
          <strong>✨ {state.data.stargazers_count}</strong>{' '}
          <strong>🍴 {state.data.forks_count}</strong>
          <div>{state.isFetching ? 'Updating...' : ''}</div>
        </div>
      </Match>
    </Switch>
  )
}
const root = document.getElementById('root')
if (!root) throw new Error('Missing #root element')

render(() => <App />, root)
```

--------------------------------

### Configure Flat Config Recommended Setup

Source: https://tanstack.com/query/latest/docs/eslint/eslint-plugin-query.md

Enable all recommended rules for the plugin in eslint.config.js.

```js
import pluginQuery from '@tanstack/eslint-plugin-query'

export default [
  ...pluginQuery.configs['flat/recommended'],
  // Any other config...
]
```

--------------------------------

### Install packages using pnpm

Source: https://tanstack.com/query/latest/docs/framework/react/plugins/createAsyncStoragePersister.md

Installs the async storage persister and the React Query persist client plugin using pnpm.

```bash
pnpm add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client
```

--------------------------------

### Install Vue Query with yarn

Source: https://tanstack.com/query/latest/docs/framework/vue/installation

Install the @tanstack/vue-query package using yarn.

```bash
yarn add @tanstack/vue-query
```

--------------------------------

### Install @tanstack/solid-query-devtools with bun

Source: https://tanstack.com/query/latest/docs/framework/solid/devtools.md

Install the dedicated Solid Query devtools package using bun.

```bash
bun add @tanstack/solid-query-devtools
```
Tokens:
Raw