1---
2name: data-fetching
3description: useFetch, useAsyncData, and $fetch for SSR-friendly data fetching
4---
5 
6# Data Fetching
7 
8Nuxt provides composables for SSR-friendly data fetching that prevent double-fetching and handle hydration.
9 
10## Overview
11 
12- `$fetch` - Basic fetch utility (use for client-side events)
13- `useFetch` - SSR-safe wrapper around $fetch (use for component data)
14- `useAsyncData` - SSR-safe wrapper for any async function
15 
16## useFetch
17 
18Primary composable for fetching data in components:
19 
20```vue
21<script setup lang="ts">
22const { data, status, error, refresh, clear } = await useFetch('/api/posts')
23</script>
24 
25<template>
26  <div v-if="status === 'pending'">Loading...</div>
27  <div v-else-if="error">Error: {{ error.message }}</div>
28  <div v-else>
29    <article v-for="post in data" :key="post.id">
30      {{ post.title }}
31    </article>
32  </div>
33</template>
34```
35 
36### With Options
37 
38```ts
39const { data } = await useFetch('/api/posts', {
40  // Query parameters
41  query: { page: 1, limit: 10 },
42  // Request body (for POST/PUT)
43  body: { title: 'New Post' },
44  // HTTP method
45  method: 'POST',
46  // Only pick specific fields
47  pick: ['id', 'title'],
48  // Transform response
49  transform: (posts) => posts.map(p => ({ ...p, slug: slugify(p.title) })),
50  // Custom key for caching
51  key: 'posts-list',
52  // Don't fetch on server
53  server: false,
54  // Don't block navigation
55  lazy: true,
56  // Don't fetch immediately
57  immediate: false,
58  // Default value
59  default: () => [],
60})
61```
62 
63### Reactive Parameters
64 
65```vue
66<script setup lang="ts">
67const page = ref(1)
68const { data } = await useFetch('/api/posts', {
69  query: { page }, // Automatically refetches when page changes
70})
71</script>
72```
73 
74### Computed URL
75 
76```vue
77<script setup lang="ts">
78const id = ref(1)
79const { data } = await useFetch(() => `/api/posts/${id.value}`)
80// Refetches when id changes
81</script>
82```
83 
84## useAsyncData
85 
86For wrapping any async function:
87 
88```vue
89<script setup lang="ts">
90const { data, error } = await useAsyncData('user', () => {
91  return myCustomFetch('/user/profile')
92})
93</script>
94```
95 
96### Multiple Requests
97 
98```vue
99<script setup lang="ts">
100const { data } = await useAsyncData('cart', async () => {
101  const [coupons, offers] = await Promise.all([
102    $fetch('/api/coupons'),
103    $fetch('/api/offers'),
104  ])
105  return { coupons, offers }
106})
107</script>
108```
109 
110## $fetch
111 
112For client-side events (form submissions, button clicks):
113 
114```vue
115<script setup lang="ts">
116async function submitForm() {
117  const result = await $fetch('/api/submit', {
118    method: 'POST',
119    body: { name: 'John' },
120  })
121}
122</script>
123```
124 
125**Important**: Don't use `$fetch` alone in setup for initial data - it will fetch twice (server + client). Use `useFetch` or `useAsyncData` instead.
126 
127## Return Values
128 
129All composables return:
130 
131| Property | Type | Description |
132|----------|------|-------------|
133| `data` | `Ref<T>` | Fetched data |
134| `error` | `Ref<Error>` | Error if request failed |
135| `status` | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>` | Request status |
136| `refresh` | `() => Promise` | Refetch data |
137| `execute` | `() => Promise` | Alias for refresh |
138| `clear` | `() => void` | Reset data and error |
139 
140## Lazy Fetching
141 
142Don't block navigation:
143 
144```vue
145<script setup lang="ts">
146// Using lazy option
147const { data, status } = await useFetch('/api/posts', { lazy: true })
148 
149// Or use lazy variants
150const { data, status } = await useLazyFetch('/api/posts')
151const { data, status } = await useLazyAsyncData('key', fetchFn)
152</script>
153```
154 
155## Refresh & Watch
156 
157```vue
158<script setup lang="ts">
159const category = ref('tech')
160 
161const { data, refresh } = await useFetch('/api/posts', {
162  query: { category },
163  // Auto-refresh when category changes
164  watch: [category],
165})
166 
167// Manual refresh
168const refreshData = () => refresh()
169</script>
170```
171 
172## Caching
173 
174Data is cached by key. Share data across components:
175 
176```vue
177<script setup lang="ts">
178// In component A
179const { data } = await useFetch('/api/user', { key: 'current-user' })
180 
181// In component B - uses cached data
182const { data } = useNuxtData('current-user')
183</script>
184```
185 
186Refresh cached data globally:
187 
188```ts
189// Refresh specific key
190await refreshNuxtData('current-user')
191 
192// Refresh all data
193await refreshNuxtData()
194 
195// Clear cached data
196clearNuxtData('current-user')
197```
198 
199## Interceptors
200 
201```ts
202const { data } = await useFetch('/api/auth', {
203  onRequest({ options }) {
204    options.headers.set('Authorization', `Bearer ${token}`)
205  },
206  onRequestError({ error }) {
207    console.error('Request failed:', error)
208  },
209  onResponse({ response }) {
210    // Process response
211  },
212  onResponseError({ response }) {
213    if (response.status === 401) {
214      navigateTo('/login')
215    }
216  },
217})
218```
219 
220## Passing Headers (SSR)
221 
222`useFetch` automatically proxies cookies/headers from client to server. For `$fetch`:
223 
224```vue
225<script setup lang="ts">
226const headers = useRequestHeaders(['cookie'])
227const data = await $fetch('/api/user', { headers })
228</script>
229```
230 
231<!-- 
232Source references:
233- https://nuxt.com/docs/getting-started/data-fetching
234- https://nuxt.com/docs/api/composables/use-fetch
235- https://nuxt.com/docs/api/composables/use-async-data
236-->
237