Vue

TanStack Query for Vue - Composables for managing server state

TanStack Query for Vue provides composables for fetching, caching, and updating asynchronous data in your Vue applications. It supports both Vue 2 (with @vue/composition-api) and Vue 3.

Installation

npm install @tanstack/vue-query
# or
pnpm add @tanstack/vue-query
# or
yarn add @tanstack/vue-query

For Vue 2, you also need to install @vue/composition-api:

npm install @vue/composition-api

Setup

Install the Vue Query plugin in your app:

import { VueQueryPlugin } from '@tanstack/vue-query'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

app.use(VueQueryPlugin)
app.mount('#app')

Plugin Options

import { QueryClient } from '@tanstack/vue-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5 minutes
    },
  },
})

app.use(VueQueryPlugin, {
  queryClient,
  enableDevtoolsV6Plugin: true, // Enable Vue DevTools integration
})

Core Composables

useQuery

Fetch and cache data with the useQuery composable:

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

const { data, isLoading, error } = useQuery({
  queryKey: ['todos'],
  queryFn: async () => {
    const res = await fetch('/api/todos')
    return res.json()
  },
})
</script>

<template>
  <div>
    <div v-if="isLoading">Loading...</div>
    <div v-else-if="error">Error: {{ error.message }}</div>
    <ul v-else>
      <li v-for="todo in data" :key="todo.id">
        {{ todo.title }}
      </li>
    </ul>
  </div>
</template>

Reactive Query Keys

Vue Query fully supports Vue’s reactivity system. Use ref or computed for dynamic queries:

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

const todoId = ref(1)

const { data } = useQuery({
  queryKey: ['todo', todoId],
  queryFn: async () => {
    const res = await fetch(`/api/todos/${todoId.value}`)
    return res.json()
  },
})

// Or use computed
const queryKey = computed(() => ['todo', todoId.value])
</script>

<template>
  <div>
    <button @click="todoId++">Next Todo</button>
    <div v-if="data">{{ data.title }}</div>
  </div>
</template>

When using refs in query options, Vue Query automatically unwraps them. You can pass todoId directly instead of todoId.value.

useMutation

Perform side effects with mutations:

<script setup>
import { useMutation, useQueryClient } from '@tanstack/vue-query'

const queryClient = useQueryClient()

const { mutate, isPending } = useMutation({
  mutationFn: async (newTodo) => {
    const res = await fetch('/api/todos', {
      method: 'POST',
      body: JSON.stringify(newTodo),
    })
    return res.json()
  },
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ['todos'] })
  },
})

const addTodo = () => {
  mutate({ title: 'New Todo', completed: false })
}
</script>

<template>
  <button @click="addTudo" :disabled="isPending">
    {{ isPending ? 'Adding...' : 'Add Todo' }}
  </button>
</template>

useInfiniteQuery

Implement infinite scrolling:

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

const {
  data,
  fetchNextPage,
  hasNextPage,
  isFetchingNextPage,
} = useInfiniteQuery({
  queryKey: ['posts'],
  queryFn: async ({ pageParam = 0 }) => {
    const res = await fetch(`/api/posts?page=${pageParam}`)
    return res.json()
  },
  getNextPageParam: (lastPage) => lastPage.nextCursor,
  initialPageParam: 0,
})
</script>

<template>
  <div>
    <div v-for="page in data?.pages" :key="page.id">
      <div v-for="post in page.posts" :key="post.id">
        {{ post.title }}
      </div>
    </div>
    <button
      @click="fetchNextPage()"
      :disabled="!hasNextPage || isFetchingNextPage"
    >
      {{ isFetchingNextPage ? 'Loading...' : 'Load More' }}
    </button>
  </div>
</template>

Reactivity Patterns

MaybeRef and MaybeRefDeep

Vue Query accepts reactive values throughout the options:

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

const enabled = ref(false)
const staleTime = ref(5000)
const userId = ref(1)

const { data } = useQuery({
  queryKey: ['user', userId], // ref is automatically unwrapped
  queryFn: () => fetchUser(userId.value),
  enabled, // ref
  staleTime, // ref
})
</script>

Watching Query Results

Query results are reactive refs that work with Vue’s watch:

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

const { data, isSuccess } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
})

watch(data, (newData) => {
  console.log('Todos updated:', newData)
})

watch(isSuccess, (success) => {
  if (success) {
    console.log('Query succeeded!')
  }
})
</script>

Vue 2 vs Vue 3

Vue 2 with Composition API

<script>
import { defineComponent, ref } from '@vue/composition-api'
import { useQuery } from '@tanstack/vue-query'

export default defineComponent({
  setup() {
    const { data, isLoading } = useQuery({
      queryKey: ['todos'],
      queryFn: fetchTodos,
    })

    return { data, isLoading }
  },
})
</script>

Vue 3 with Script Setup

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

const { data, isLoading } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
})
</script>

The API is identical between Vue 2 and Vue 3. The only difference is how you access the Composition API.

Advanced Features

useQueries

Execute multiple queries in parallel:

<script setup>
import { ref } from 'vue'
import { useQueries } from '@tanstack/vue-query'

const userIds = ref([1, 2, 3])

const results = useQueries({
  queries: userIds.value.map((id) => ({
    queryKey: ['user', id],
    queryFn: () => fetchUser(id),
  })),
})

// results is an array of reactive query results
</script>

Query Options Factory

import { queryOptions } from '@tanstack/vue-query'

export const todoQueries = {
  all: () => queryOptions({
    queryKey: ['todos'],
    queryFn: fetchTodos,
  }),
  detail: (id: number) => queryOptions({
    queryKey: ['todos', id],
    queryFn: () => fetchTodo(id),
  }),
}

// Usage
const { data } = useQuery(todoQueries.detail(1))

useMutationState

Track all mutations globally:

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

const pendingMutations = useMutationState({
  filters: { status: 'pending' },
})
</script>

<template>
  <div v-if="pendingMutations.length > 0">
    Saving {{ pendingMutations.length }} changes...
  </div>
</template>

useIsFetching

Show a global loading indicator:

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

const isFetching = useIsFetching()
</script>

<template>
  <div v-if="isFetching" class="loading-bar">
    Loading...
  </div>
</template>

Shallow Option

Control ref unwrapping with the shallow option:

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

const { data } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  shallow: true, // Prevents deep unwrapping of refs
})
</script>

TypeScript

Full TypeScript support with proper type inference:

<script setup lang="ts">
import { useQuery } from '@tanstack/vue-query'
import type { Ref } from 'vue'

interface Todo {
  id: number
  title: string
  completed: boolean
}

const { data } = useQuery({
  queryKey: ['todos'],
  queryFn: async (): Promise<Todo[]> => {
    const res = await fetch('/api/todos')
    return res.json()
  },
})

// data is typed as Ref<Todo[] | undefined>
</script>

DevTools Integration

Vue Query integrates with Vue DevTools:

import { VueQueryPlugin } from '@tanstack/vue-query'

app.use(VueQueryPlugin, {
  enableDevtoolsV6Plugin: true, // Enables Vue DevTools integration
})

SSR Support

For Nuxt or other SSR frameworks:

// plugins/vue-query.ts
import { VueQueryPlugin, QueryClient } from '@tanstack/vue-query'

export default defineNuxtPlugin((nuxtApp) => {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 5000,
      },
    },
  })

  nuxtApp.vueApp.use(VueQueryPlugin, { queryClient })
})

Vue-Specific Gotchas

Ref Unwrapping: Vue Query automatically unwraps refs in query options, but query results are returned as refs. Always access them with .value in script or directly in templates.

Reactive Options: You can pass entire options objects as refs or use individual refs for specific properties. Both approaches work seamlessly with Vue’s reactivity.

Related Resources

• Vue Query Devtools
• Nuxt Integration
• Vue Reactivity Guide