1---
2category: Network
3---
4 
5# useFetch
6 
7Reactive [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) provides the ability to abort requests, intercept requests before
8they are fired, automatically refetch requests when the url changes, and create your own `useFetch` with predefined options.
9 
10<CourseLink href="https://vueschool.io/lessons/vueuse-utilities-usefetch-and-reactify?friend=vueuse">Learn useFetch with this FREE video lesson from Vue School!</CourseLink>
11 
12::: tip
13When using with Nuxt 3, this function will **NOT** be auto imported in favor of Nuxt's built-in [`useFetch()`](https://v3.nuxtjs.org/api/composables/use-fetch). Use explicit import if you want to use the function from VueUse.
14:::
15 
16## Usage
17 
18### Basic Usage
19 
20The `useFetch` function can be used by simply providing a url. The url can be either a string or a `ref`. The `data` object will contain the result of the request, the `error` object will contain any errors, and the `isFetching` object will indicate if the request is loading.
21 
22```ts
23import { useFetch } from '@vueuse/core'
24 
25const { isFetching, error, data } = useFetch(url)
26```
27 
28### Asynchronous Usage
29 
30`useFetch` can also be awaited just like a normal fetch. Note that whenever a component is asynchronous, whatever component that uses
31it must wrap the component in a `<Suspense>` tag. You can read more about the suspense api in the [Official Vue 3 Docs](https://vuejs.org/guide/built-ins/suspense.html)
32 
33```ts
34import { useFetch } from '@vueuse/core'
35// ---cut---
36const { isFetching, error, data } = await useFetch(url)
37```
38 
39### Refetching on URL change
40 
41Using a `ref` for the url parameter will allow the `useFetch` function to automatically trigger another request when the url is changed.
42 
43```ts
44import { useFetch } from '@vueuse/core'
45// ---cut---
46const url = ref('https://my-api.com/user/1')
47 
48const { data } = useFetch(url, { refetch: true })
49 
50url.value = 'https://my-api.com/user/2' // Will trigger another request
51```
52 
53### Prevent request from firing immediately
54 
55Setting the `immediate` option to false will prevent the request from firing until the `execute` function is called.
56 
57```ts
58import { useFetch } from '@vueuse/core'
59// ---cut---
60const { execute } = useFetch(url, { immediate: false })
61 
62execute()
63```
64 
65### Aborting a request
66 
67A request can be aborted by using the `abort` function from the `useFetch` function. The `canAbort` property indicates if the request can be aborted.
68 
69```ts
70import { useFetch } from '@vueuse/core'
71// ---cut---
72const { abort, canAbort } = useFetch(url)
73 
74setTimeout(() => {
75  if (canAbort.value)
76    abort()
77}, 100)
78```
79 
80A request can also be aborted automatically by using `timeout` property. It will call `abort` function when the given timeout is reached.
81 
82```ts
83import { useFetch } from '@vueuse/core'
84// ---cut---
85const { data } = useFetch(url, { timeout: 100 })
86```
87 
88### Intercepting a request
89 
90The `beforeFetch` option can intercept a request before it is sent and modify the request options and url.
91 
92```ts
93import { useFetch } from '@vueuse/core'
94// ---cut---
95const { data } = useFetch(url, {
96  async beforeFetch({ url, options, cancel }) {
97    const myToken = await getMyToken()
98 
99    if (!myToken)
100      cancel()
101 
102    options.headers = {
103      ...options.headers,
104      Authorization: `Bearer ${myToken}`,
105    }
106 
107    return {
108      options,
109    }
110  },
111})
112```
113 
114The `afterFetch` option can intercept the response data before it is updated.
115 
116```ts
117import { useFetch } from '@vueuse/core'
118// ---cut---
119const { data } = useFetch(url, {
120  afterFetch(ctx) {
121    if (ctx.data.title === 'HxH')
122      ctx.data.title = 'Hunter x Hunter' // Modifies the response data
123 
124    return ctx
125  },
126})
127```
128 
129The `onFetchError` option can intercept the response data and error before it is updated when `updateDataOnError` is set to `true`.
130 
131```ts
132import { useFetch } from '@vueuse/core'
133// ---cut---
134const { data } = useFetch(url, {
135  updateDataOnError: true,
136  onFetchError(ctx) {
137    // ctx.data can be null when 5xx response
138    if (ctx.data === null)
139      ctx.data = { title: 'Hunter x Hunter' } // Modifies the response data
140 
141    ctx.error = new Error('Custom Error') // Modifies the error
142    return ctx
143  },
144})
145 
146console.log(data.value) // { title: 'Hunter x Hunter' }
147```
148 
149### Setting the request method and return type
150 
151The request method and return type can be set by adding the appropriate methods to the end of `useFetch`
152 
153```ts
154import { useFetch } from '@vueuse/core'
155// ---cut---
156// Request will be sent with GET method and data will be parsed as JSON
157const { data } = useFetch(url).get().json()
158 
159// Request will be sent with POST method and data will be parsed as text
160const { data } = useFetch(url).post().text()
161 
162// Or set the method using the options
163 
164// Request will be sent with GET method and data will be parsed as blob
165const { data } = useFetch(url, { method: 'GET' }, { refetch: true }).blob()
166```
167 
168### Creating a Custom Instance
169 
170The `createFetch` function will return a useFetch function with whatever pre-configured options that are provided to it. This is useful for interacting with API's throughout an application that uses the same base URL or needs Authorization headers.
171 
172```ts
173import { createFetch } from '@vueuse/core'
174// ---cut---
175const useMyFetch = createFetch({
176  baseUrl: 'https://my-api.com',
177  options: {
178    async beforeFetch({ options }) {
179      const myToken = await getMyToken()
180      options.headers.Authorization = `Bearer ${myToken}`
181 
182      return { options }
183    },
184  },
185  fetchOptions: {
186    mode: 'cors',
187  },
188})
189 
190const { isFetching, error, data } = useMyFetch('users')
191```
192 
193If you want to control the behavior of `beforeFetch`, `afterFetch`, `onFetchError` between the pre-configured instance and newly spawned instance. You can provide a `combination` option to toggle between `overwrite` or `chaining`.
194 
195```ts
196import { createFetch } from '@vueuse/core'
197// ---cut---
198const useMyFetch = createFetch({
199  baseUrl: 'https://my-api.com',
200  combination: 'overwrite',
201  options: {
202    // beforeFetch in pre-configured instance will only run when the newly spawned instance do not pass beforeFetch
203    async beforeFetch({ options }) {
204      const myToken = await getMyToken()
205      options.headers.Authorization = `Bearer ${myToken}`
206 
207      return { options }
208    },
209  },
210})
211 
212// use useMyFetch beforeFetch
213const { isFetching, error, data } = useMyFetch('users')
214 
215// use custom beforeFetch
216const { isFetching, error, data } = useMyFetch('users', {
217  async beforeFetch({ url, options, cancel }) {
218    const myToken = await getMyToken()
219 
220    if (!myToken)
221      cancel()
222 
223    options.headers = {
224      ...options.headers,
225      Authorization: `Bearer ${myToken}`,
226    }
227 
228    return {
229      options,
230    }
231  },
232})
233```
234 
235You can re-execute the request by calling the `execute` method in `afterFetch` or `onFetchError`. Here is a simple example of refreshing a token:
236 
237```ts
238import { createFetch } from '@vueuse/core'
239// ---cut---
240let isRefreshing = false
241const refreshSubscribers: Array<() => void> = []
242 
243const useMyFetch = createFetch({
244  baseUrl: 'https://my-api.com',
245  options: {
246    async beforeFetch({ options }) {
247      const myToken = await getMyToken()
248      options.headers.Authorization = `Bearer ${myToken}`
249 
250      return { options }
251    },
252    afterFetch({ data, response, context, execute }) {
253      if (needRefreshToken) {
254        if (!isRefreshing) {
255          isRefreshing = true
256          refreshToken().then((newToken) => {
257            if (newToken.value) {
258              isRefreshing = false
259              setMyToken(newToken.value)
260              onRefreshed()
261            }
262            else {
263              refreshSubscribers.length = 0
264              // handle refresh token error
265            }
266          })
267        }
268 
269        return new Promise((resolve) => {
270          addRefreshSubscriber(() => {
271            execute().then((response) => {
272              resolve({ data, response })
273            })
274          })
275        })
276      }
277 
278      return { data, response }
279    },
280    // or use onFetchError with updateDataOnError
281    updateDataOnError: true,
282    onFetchError({ error, data, response, context, execute }) {
283      // same as afterFetch
284      return { error, data }
285    },
286  },
287  fetchOptions: {
288    mode: 'cors',
289  },
290})
291 
292async function refreshToken() {
293  const { data, execute } = useFetch<string>('refresh-token', {
294    immediate: false,
295  })
296 
297  await execute()
298  return data
299}
300 
301function onRefreshed() {
302  refreshSubscribers.forEach(callback => callback())
303  refreshSubscribers.length = 0
304}
305 
306function addRefreshSubscriber(callback: () => void) {
307  refreshSubscribers.push(callback)
308}
309 
310const { isFetching, error, data } = useMyFetch('users')
311```
312 
313### Events
314 
315The `onFetchResponse` and `onFetchError` will fire on fetch request responses and errors respectively.
316 
317```ts
318import { useFetch } from '@vueuse/core'
319// ---cut---
320const { onFetchResponse, onFetchError } = useFetch(url)
321 
322onFetchResponse((response) => {
323  console.log(response.status)
324})
325 
326onFetchError((error) => {
327  console.error(error.message)
328})
329```
330 
331## Type Declarations
332 
333```ts
334export interface UseFetchReturn<T> {
335  /**
336   * Indicates if the fetch request has finished
337   */
338  isFinished: Readonly<ShallowRef<boolean>>
339  /**
340   * The statusCode of the HTTP fetch response
341   */
342  statusCode: ShallowRef<number | null>
343  /**
344   * The raw response of the fetch response
345   */
346  response: ShallowRef<Response | null>
347  /**
348   * Any fetch errors that may have occurred
349   */
350  error: ShallowRef<any>
351  /**
352   * The fetch response body on success, may either be JSON or text
353   */
354  data: ShallowRef<T | null>
355  /**
356   * Indicates if the request is currently being fetched.
357   */
358  isFetching: Readonly<ShallowRef<boolean>>
359  /**
360   * Indicates if the fetch request is able to be aborted
361   */
362  canAbort: ComputedRef<boolean>
363  /**
364   * Indicates if the fetch request was aborted
365   */
366  aborted: ShallowRef<boolean>
367  /**
368   * Abort the fetch request
369   */
370  abort: (reason?: any) => void
371  /**
372   * Manually call the fetch
373   * (default not throwing error)
374   */
375  execute: (throwOnFailed?: boolean) => Promise<any>
376  /**
377   * Fires after the fetch request has finished
378   */
379  onFetchResponse: EventHookOn<Response>
380  /**
381   * Fires after a fetch request error
382   */
383  onFetchError: EventHookOn
384  /**
385   * Fires after a fetch has completed
386   */
387  onFetchFinally: EventHookOn
388  get: () => UseFetchReturn<T> & PromiseLike<UseFetchReturn<T>>
389  post: (
390    payload?: MaybeRefOrGetter<unknown>,
391    type?: string,
392  ) => UseFetchReturn<T> & PromiseLike<UseFetchReturn<T>>
393  put: (
394    payload?: MaybeRefOrGetter<unknown>,
395    type?: string,
396  ) => UseFetchReturn<T> & PromiseLike<UseFetchReturn<T>>
397  delete: (
398    payload?: MaybeRefOrGetter<unknown>,
399    type?: string,
400  ) => UseFetchReturn<T> & PromiseLike<UseFetchReturn<T>>
401  patch: (
402    payload?: MaybeRefOrGetter<unknown>,
403    type?: string,
404  ) => UseFetchReturn<T> & PromiseLike<UseFetchReturn<T>>
405  head: (
406    payload?: MaybeRefOrGetter<unknown>,
407    type?: string,
408  ) => UseFetchReturn<T> & PromiseLike<UseFetchReturn<T>>
409  options: (
410    payload?: MaybeRefOrGetter<unknown>,
411    type?: string,
412  ) => UseFetchReturn<T> & PromiseLike<UseFetchReturn<T>>
413  json: <JSON = any>() => UseFetchReturn<JSON> &
414    PromiseLike<UseFetchReturn<JSON>>
415  text: () => UseFetchReturn<string> & PromiseLike<UseFetchReturn<string>>
416  blob: () => UseFetchReturn<Blob> & PromiseLike<UseFetchReturn<Blob>>
417  arrayBuffer: () => UseFetchReturn<ArrayBuffer> &
418    PromiseLike<UseFetchReturn<ArrayBuffer>>
419  formData: () => UseFetchReturn<FormData> &
420    PromiseLike<UseFetchReturn<FormData>>
421}
422type Combination = "overwrite" | "chain"
423export interface BeforeFetchContext {
424  /**
425   * The computed url of the current request
426   */
427  url: string
428  /**
429   * The request options of the current request
430   */
431  options: RequestInit
432  /**
433   * Cancels the current request
434   */
435  cancel: Fn
436}
437export interface AfterFetchContext<T = any> {
438  response: Response
439  data: T | null
440  context: BeforeFetchContext
441  execute: (throwOnFailed?: boolean) => Promise<any>
442}
443export interface OnFetchErrorContext<T = any, E = any> {
444  error: E
445  data: T | null
446  response: Response | null
447  context: BeforeFetchContext
448  execute: (throwOnFailed?: boolean) => Promise<any>
449}
450export interface UseFetchOptions {
451  /**
452   * Fetch function
453   */
454  fetch?: typeof window.fetch
455  /**
456   * Will automatically run fetch when `useFetch` is used
457   *
458   * @default true
459   */
460  immediate?: boolean
461  /**
462   * Will automatically refetch when:
463   * - the URL is changed if the URL is a ref
464   * - the payload is changed if the payload is a ref
465   *
466   * @default false
467   */
468  refetch?: MaybeRefOrGetter<boolean>
469  /**
470   * Initial data before the request finished
471   *
472   * @default null
473   */
474  initialData?: any
475  /**
476   * Timeout for abort request after number of millisecond
477   * `0` means use browser default
478   *
479   * @default 0
480   */
481  timeout?: number
482  /**
483   * Allow update the `data` ref when fetch error whenever provided, or mutated in the `onFetchError` callback
484   *
485   * @default false
486   */
487  updateDataOnError?: boolean
488  /**
489   * Will run immediately before the fetch request is dispatched
490   */
491  beforeFetch?: (
492    ctx: BeforeFetchContext,
493  ) =>
494    | Promise<Partial<BeforeFetchContext> | void>
495    | Partial<BeforeFetchContext>
496    | void
497  /**
498   * Will run immediately after the fetch request is returned.
499   * Runs after any 2xx response
500   */
501  afterFetch?: (
502    ctx: AfterFetchContext,
503  ) => Promise<Partial<AfterFetchContext>> | Partial<AfterFetchContext>
504  /**
505   * Will run immediately after the fetch request is returned.
506   * Runs after any 4xx and 5xx response
507   */
508  onFetchError?: (
509    ctx: OnFetchErrorContext,
510  ) => Promise<Partial<OnFetchErrorContext>> | Partial<OnFetchErrorContext>
511}
512export interface CreateFetchOptions {
513  /**
514   * The base URL that will be prefixed to all urls unless urls are absolute
515   */
516  baseUrl?: MaybeRefOrGetter<string>
517  /**
518   * Determine the inherit behavior for beforeFetch, afterFetch, onFetchError
519   * @default 'chain'
520   */
521  combination?: Combination
522  /**
523   * Default Options for the useFetch function
524   */
525  options?: UseFetchOptions
526  /**
527   * Options for the fetch request
528   */
529  fetchOptions?: RequestInit
530}
531export declare function createFetch(
532  config?: CreateFetchOptions,
533): typeof useFetch
534export declare function useFetch<T>(
535  url: MaybeRefOrGetter<string>,
536): UseFetchReturn<T> & PromiseLike<UseFetchReturn<T>>
537export declare function useFetch<T>(
538  url: MaybeRefOrGetter<string>,
539  useFetchOptions: UseFetchOptions,
540): UseFetchReturn<T> & PromiseLike<UseFetchReturn<T>>
541export declare function useFetch<T>(
542  url: MaybeRefOrGetter<string>,
543  options: RequestInit,
544  useFetchOptions?: UseFetchOptions,
545): UseFetchReturn<T> & PromiseLike<UseFetchReturn<T>>
546```
547