0
# HTTP Client
1

2
HTTP request management using Axios with reactive state, automatic cleanup, and comprehensive error handling.
3

4
## Capabilities
5

6
### useAxios
7

8
Creates reactive HTTP requests with automatic state management and cleanup.
9

10
```typescript { .api }
11
/**
12
 * Creates reactive HTTP requests with automatic state management
13
 * @param url - Request URL string or config object
14
 * @param config - Axios request configuration
15
 * @param options - VueUse specific options
16
 * @returns Reactive HTTP request state and control methods
17
 */
18
function useAxios<T = any, R = AxiosResponse<T>, D = any>(
19
  url: string,
20
  config?: AxiosRequestConfig<D>,
21
  options?: UseAxiosOptions
22
): UseAxiosReturn<T, R, D> & Promise<UseAxiosReturn<T, R, D>>;
23

24
function useAxios<T = any, R = AxiosResponse<T>, D = any>(
25
  url: string,
26
  instance?: AxiosInstance,
27
  options?: UseAxiosOptions
28
): UseAxiosReturn<T, R, D> & Promise<UseAxiosReturn<T, R, D>>;
29

30
function useAxios<T = any, R = AxiosResponse<T>, D = any>(
31
  url: string,
32
  config: AxiosRequestConfig<D>,
33
  instance: AxiosInstance,
34
  options?: UseAxiosOptions
35
): UseAxiosReturn<T, R, D> & Promise<UseAxiosReturn<T, R, D>>;
36

37
function useAxios<T = any, R = AxiosResponse<T>, D = any>(
38
  config?: AxiosRequestConfig<D>
39
): EasyUseAxiosReturn<T, R, D> & Promise<EasyUseAxiosReturn<T, R, D>>;
40

41
function useAxios<T = any, R = AxiosResponse<T>, D = any>(
42
  instance?: AxiosInstance
43
): EasyUseAxiosReturn<T, R, D> & Promise<EasyUseAxiosReturn<T, R, D>>;
44

45
interface UseAxiosReturn<T, R = AxiosResponse<T>, _D = any, O extends UseAxiosOptions = UseAxiosOptions<T>> {
46
  /** The response object from Axios */
47
  response: ShallowRef<R | undefined>;
48
  /** The response data, typed based on initial data option */
49
  data: O extends UseAxiosOptionsWithInitialData<T> ? Ref<T> : Ref<T | undefined>;
50
  /** Whether the request has completed */
51
  isFinished: Ref<boolean>;
52
  /** Whether the request is currently loading */
53
  isLoading: Ref<boolean>;
54
  /** Whether the request was aborted */
55
  isAborted: Ref<boolean>;
56
  /** Any error that occurred during the request */
57
  error: ShallowRef<unknown | undefined>;
58
  /** Abort the current request */
59
  abort: (message?: string | undefined) => void;
60
  /** Cancel the current request (alias to abort) */
61
  cancel: (message?: string | undefined) => void;
62
  /** Whether the request was canceled (alias to isAborted) */
63
  isCanceled: Ref<boolean>;
64
}
65

66
interface StrictUseAxiosReturn<T, R, D, O> extends UseAxiosReturn<T, R, D, O> {
67
  /** Execute the request with optional URL and config override */
68
  execute: (url?: string | AxiosRequestConfig<D>, config?: AxiosRequestConfig<D>) => Promise<StrictUseAxiosReturn<T, R, D, O>>;
69
}
70

71
interface EasyUseAxiosReturn<T, R, D> extends UseAxiosReturn<T, R, D> {
72
  /** Execute the request with URL and optional config */
73
  execute: (url: string, config?: AxiosRequestConfig<D>) => Promise<EasyUseAxiosReturn<T, R, D>>;
74
}
75

76
interface UseAxiosOptionsBase<T = any> {
77
  /** Execute request immediately on creation */
78
  immediate?: boolean;
79
  /** Use shallow ref for response data */
80
  shallow?: boolean; // default: true
81
  /** Abort previous request when new one starts */
82
  abortPrevious?: boolean; // default: true
83
  /** Error callback function */
84
  onError?: (e: unknown) => void;
85
  /** Success callback function */
86
  onSuccess?: (data: T) => void;
87
  /** Reset data when execute is called */
88
  resetOnExecute?: boolean;
89
  /** Callback when request finishes */
90
  onFinish?: () => void;
91
}
92

93
interface UseAxiosOptionsWithInitialData<T> extends UseAxiosOptionsBase<T> {
94
  /** Initial data value to ensure data ref is never undefined */
95
  initialData: T;
96
}
97

98
type UseAxiosOptions<T = any> = UseAxiosOptionsBase<T> | UseAxiosOptionsWithInitialData<T>;
99
```
100

101
**Usage Examples:**
102

103
```typescript
104
import { useAxios } from "@vueuse/integrations/useAxios";
105

106
// Basic GET request
107
const { data, isLoading, error } = useAxios('https://api.example.com/users');
108

109
// POST request with data
110
const { data, execute } = useAxios({
111
  url: 'https://api.example.com/users',
112
  method: 'POST'
113
}, { immediate: false });
114

115
// Execute manually
116
await execute({ data: { name: 'John' } });
117

118
// With custom axios instance
119
import axios from 'axios';
120
const api = axios.create({ baseURL: 'https://api.example.com' });
121
const { data } = useAxios('/users', api);
122

123
// With initial data to prevent undefined
124
const { data } = useAxios('/users', {
125
  initialData: []
126
});
127

128
// With callbacks and options
129
const { data, isLoading } = useAxios('/users', {
130
  immediate: true,
131
  abortPrevious: true,
132
  onSuccess: (data) => console.log('Success:', data),
133
  onError: (error) => console.error('Error:', error),
134
  onFinish: () => console.log('Request finished')
135
});
136
```