1---
2category: '@Integrations'
3---
4 
5# useAxios
6 
7Wrapper for [`axios`](https://github.com/axios/axios).
8 
9## Install
10 
11```bash
12npm i axios@^1
13```
14 
15## Usage
16 
17```ts
18import { useAxios } from '@vueuse/integrations/useAxios'
19 
20const { data, isFinished } = useAxios('/api/posts')
21```
22 
23### Return Values
24 
25| Property           | Type                         | Description                              |
26| ------------------ | ---------------------------- | ---------------------------------------- |
27| `data`             | `Ref<T>`                     | Response data                            |
28| `response`         | `Ref<AxiosResponse>`         | Full axios response                      |
29| `error`            | `Ref<unknown>`               | Error if request failed                  |
30| `isFinished`       | `Ref<boolean>`               | Request has completed (success or error) |
31| `isLoading`        | `Ref<boolean>`               | Request is in progress                   |
32| `isAborted`        | `Ref<boolean>`               | Request was aborted                      |
33| `abort` / `cancel` | `() => void`                 | Abort the current request                |
34| `execute`          | `(url?, config?) => Promise` | Execute/re-execute the request           |
35 
36### With Axios Instance
37 
38```ts
39import { useAxios } from '@vueuse/integrations/useAxios'
40import axios from 'axios'
41 
42const instance = axios.create({
43  baseURL: '/api',
44})
45 
46const { data, isFinished } = useAxios('/posts', instance)
47```
48 
49### With Config Options
50 
51```ts
52import { useAxios } from '@vueuse/integrations/useAxios'
53import axios from 'axios'
54 
55const instance = axios.create({
56  baseURL: '/api',
57})
58 
59const { data, isFinished } = useAxios('/posts', { method: 'POST' }, instance)
60```
61 
62### Manual Execution
63 
64When you don't pass a `url`, the request won't fire immediately:
65 
66```ts
67import { useAxios } from '@vueuse/integrations/useAxios'
68 
69const { execute } = useAxios()
70execute(url)
71```
72 
73The `execute` function `url` is optional - `url2` will replace `url1`:
74 
75```ts
76import { useAxios } from '@vueuse/integrations/useAxios'
77 
78const { execute } = useAxios(url1, {}, { immediate: false })
79execute(url2)
80```
81 
82The `execute` function can accept config only:
83 
84```ts
85import { useAxios } from '@vueuse/integrations/useAxios'
86 
87const { execute } = useAxios(url1, { method: 'GET' }, { immediate: false })
88execute({ params: { key: 1 } })
89execute({ params: { key: 2 } })
90```
91 
92### Awaiting Results
93 
94The return value is thenable, so you can await it:
95 
96```ts
97import { useAxios } from '@vueuse/integrations/useAxios'
98 
99const { data, isFinished, error } = await useAxios('/api/posts')
100// data is now populated
101```
102 
103Or await the execute function:
104 
105```ts
106import { useAxios } from '@vueuse/integrations/useAxios'
107 
108const { execute } = useAxios()
109const result = await execute(url)
110```
111 
112### Options
113 
114```ts
115const { data } = useAxios('/api/posts', config, instance, {
116  // Execute immediately (default: true if url provided)
117  immediate: true,
118  // Use shallowRef for data (default: true)
119  shallow: true,
120  // Abort previous request on new execute (default: true)
121  abortPrevious: true,
122  // Reset data before executing (default: false)
123  resetOnExecute: false,
124  // Initial data value
125  initialData: [],
126  // Callbacks
127  onSuccess: data => console.log('Success:', data),
128  onError: error => console.error('Error:', error),
129  onFinish: () => console.log('Finished'),
130})
131```
132 
133## Type Declarations
134 
135```ts
136export interface UseAxiosReturn<
137  T,
138  R = AxiosResponse<T>,
139  _D = any,
140  O extends UseAxiosOptions = UseAxiosOptions<T>,
141> {
142  /**
143   * Axios Response
144   */
145  response: ShallowRef<R | undefined>
146  /**
147   * Axios response data
148   */
149  data: O extends UseAxiosOptionsWithInitialData<T>
150    ? Ref<T>
151    : Ref<T | undefined>
152  /**
153   * Indicates if the request has finished
154   */
155  isFinished: Ref<boolean>
156  /**
157   * Indicates if the request is currently loading
158   */
159  isLoading: Ref<boolean>
160  /**
161   * Indicates if the request was canceled
162   */
163  isAborted: Ref<boolean>
164  /**
165   * Any errors that may have occurred
166   */
167  error: ShallowRef<unknown | undefined>
168  /**
169   * Aborts the current request
170   */
171  abort: (message?: string | undefined) => void
172  /**
173   * Alias to `abort`
174   */
175  cancel: (message?: string | undefined) => void
176  /**
177   * Alias to `isAborted`
178   */
179  isCanceled: Ref<boolean>
180}
181export interface StrictUseAxiosReturn<
182  T,
183  R,
184  D,
185  O extends UseAxiosOptions = UseAxiosOptions<T>,
186> extends UseAxiosReturn<T, R, D, O> {
187  /**
188   * Manually call the axios request
189   */
190  execute: (
191    url?: string | AxiosRequestConfig<D>,
192    config?: AxiosRequestConfig<D>,
193  ) => Promise<StrictUseAxiosReturn<T, R, D, O>>
194}
195export interface EasyUseAxiosReturn<T, R, D> extends UseAxiosReturn<T, R, D> {
196  /**
197   * Manually call the axios request
198   */
199  execute: (
200    url: string,
201    config?: AxiosRequestConfig<D>,
202  ) => Promise<EasyUseAxiosReturn<T, R, D>>
203}
204export interface UseAxiosOptionsBase<T = any> {
205  /**
206   * Will automatically run axios request when `useAxios` is used
207   *
208   */
209  immediate?: boolean
210  /**
211   * Use shallowRef.
212   *
213   * @default true
214   */
215  shallow?: boolean
216  /**
217   * Abort previous request when a new request is made.
218   *
219   * @default true
220   */
221  abortPrevious?: boolean
222  /**
223   * Callback when error is caught.
224   */
225  onError?: (e: unknown) => void
226  /**
227   * Callback when success is caught.
228   */
229  onSuccess?: (data: T) => void
230  /**
231   * Sets the state to initialState before executing the promise.
232   */
233  resetOnExecute?: boolean
234  /**
235   * Callback when request is finished.
236   */
237  onFinish?: () => void
238}
239export interface UseAxiosOptionsWithInitialData<
240  T,
241> extends UseAxiosOptionsBase<T> {
242  /**
243   * Initial data
244   */
245  initialData: T
246}
247export type UseAxiosOptions<T = any> =
248  | UseAxiosOptionsBase<T>
249  | UseAxiosOptionsWithInitialData<T>
250export declare function useAxios<
251  T = any,
252  R = AxiosResponse<T>,
253  D = any,
254  O extends UseAxiosOptionsWithInitialData<T> =
255    UseAxiosOptionsWithInitialData<T>,
256>(
257  url: string,
258  config?: AxiosRequestConfig<D>,
259  options?: O,
260): StrictUseAxiosReturn<T, R, D, O> & Promise<StrictUseAxiosReturn<T, R, D, O>>
261export declare function useAxios<
262  T = any,
263  R = AxiosResponse<T>,
264  D = any,
265  O extends UseAxiosOptionsWithInitialData<T> =
266    UseAxiosOptionsWithInitialData<T>,
267>(
268  url: string,
269  instance?: AxiosInstance,
270  options?: O,
271): StrictUseAxiosReturn<T, R, D, O> & Promise<StrictUseAxiosReturn<T, R, D, O>>
272export declare function useAxios<
273  T = any,
274  R = AxiosResponse<T>,
275  D = any,
276  O extends UseAxiosOptionsWithInitialData<T> =
277    UseAxiosOptionsWithInitialData<T>,
278>(
279  url: string,
280  config: AxiosRequestConfig<D>,
281  instance: AxiosInstance,
282  options?: O,
283): StrictUseAxiosReturn<T, R, D, O> & Promise<StrictUseAxiosReturn<T, R, D, O>>
284export declare function useAxios<
285  T = any,
286  R = AxiosResponse<T>,
287  D = any,
288  O extends UseAxiosOptionsBase<T> = UseAxiosOptionsBase<T>,
289>(
290  url: string,
291  config?: AxiosRequestConfig<D>,
292  options?: O,
293): StrictUseAxiosReturn<T, R, D, O> & Promise<StrictUseAxiosReturn<T, R, D, O>>
294export declare function useAxios<
295  T = any,
296  R = AxiosResponse<T>,
297  D = any,
298  O extends UseAxiosOptionsBase<T> = UseAxiosOptionsBase<T>,
299>(
300  url: string,
301  instance?: AxiosInstance,
302  options?: O,
303): StrictUseAxiosReturn<T, R, D, O> & Promise<StrictUseAxiosReturn<T, R, D, O>>
304export declare function useAxios<
305  T = any,
306  R = AxiosResponse<T>,
307  D = any,
308  O extends UseAxiosOptionsBase<T> = UseAxiosOptionsBase<T>,
309>(
310  url: string,
311  config: AxiosRequestConfig<D>,
312  instance: AxiosInstance,
313  options?: O,
314): StrictUseAxiosReturn<T, R, D, O> & Promise<StrictUseAxiosReturn<T, R, D, O>>
315export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
316  config?: AxiosRequestConfig<D>,
317): EasyUseAxiosReturn<T, R, D> & Promise<EasyUseAxiosReturn<T, R, D>>
318export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
319  instance?: AxiosInstance,
320): EasyUseAxiosReturn<T, R, D> & Promise<EasyUseAxiosReturn<T, R, D>>
321export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
322  config?: AxiosRequestConfig<D>,
323  instance?: AxiosInstance,
324): EasyUseAxiosReturn<T, R, D> & Promise<EasyUseAxiosReturn<T, R, D>>
325```
326