Skip to content
On this page

useAxios

Category
Export Size
1.4 kB
Package
@vueuse/integrations
Last Changed
last month

Wrapper for axios.

Demo

Loading: true
Finished: false
Available in the @vueuse/integrations add-on.

Install

bash
npm i axios
npm i axios

Usage

ts
import { useAxios } from '@vueuse/integrations/useAxios'

const { data, isFinished } = useAxios('/api/posts')
import { useAxios } from '@vueuse/integrations/useAxios'

const { data, isFinished } = useAxios('/api/posts')

or use an instance of axios

ts
import axios from 'axios'
import { useAxios } from '@vueuse/integrations/useAxios'

const instance = axios.create({
  baseURL: '/api',
})

const { data, isFinished } = useAxios('/posts', instance)
import axios from 'axios'
import { useAxios } from '@vueuse/integrations/useAxios'

const instance = axios.create({
  baseURL: '/api',
})

const { data, isFinished } = useAxios('/posts', instance)

use an instance of axios with config options

ts
import axios from 'axios'
import { useAxios } from '@vueuse/integrations/useAxios'

const instance = axios.create({
  baseURL: '/api',
})

const { data, isFinished } = useAxios('/posts', { method: 'POST' }, instance)
import axios from 'axios'
import { useAxios } from '@vueuse/integrations/useAxios'

const instance = axios.create({
  baseURL: '/api',
})

const { data, isFinished } = useAxios('/posts', { method: 'POST' }, instance)

When you don't pass the url. The default value is {immediate: false}

ts
import { useAxios } from '@vueuse/integrations/useAxios'

const { execute } = useAxios()
execute(url)
import { useAxios } from '@vueuse/integrations/useAxios'

const { execute } = useAxios()
execute(url)

The execute function url here is optional, and url2 will replace the url1.

ts
import { useAxios } from '@vueuse/integrations/useAxios'

const { execute } = useAxios(url1, {}, { immediate: false })
execute(url2)
import { useAxios } from '@vueuse/integrations/useAxios'

const { execute } = useAxios(url1, {}, { immediate: false })
execute(url2)

The execute function can accept config only.

ts
import { useAxios } from '@vueuse/integrations/useAxios'

const { execute } = useAxios(url1, { method: 'GET' }, { immediate: false })
execute({ params: { key: 1 } })
execute({ params: { key: 2 } })
import { useAxios } from '@vueuse/integrations/useAxios'

const { execute } = useAxios(url1, { method: 'GET' }, { immediate: false })
execute({ params: { key: 1 } })
execute({ params: { key: 2 } })

The execute function resolves with a result of network request.

ts
import { useAxios } from '@vueuse/integrations/useAxios'

const { execute } = useAxios()
const result = await execute(url)
import { useAxios } from '@vueuse/integrations/useAxios'

const { execute } = useAxios()
const result = await execute(url)

use an instance of axios with immediate options

ts
import axios from 'axios'
import { useAxios } from '@vueuse/integrations/useAxios'

const instance = axios.create({
  baseURL: '/api',
})

const { data, isFinished } = useAxios('/posts', { method: 'POST' }, instance, {
  immediate: false,
})
import axios from 'axios'
import { useAxios } from '@vueuse/integrations/useAxios'

const instance = axios.create({
  baseURL: '/api',
})

const { data, isFinished } = useAxios('/posts', { method: 'POST' }, instance, {
  immediate: false,
})

Type Declarations

Show Type Declarations
typescript
export interface UseAxiosReturn<T, R = AxiosResponse<T>, D = any> {
  /**
   * Axios Response
   */
  response: ShallowRef<R | undefined>
  /**
   * Axios response data
   */
  data: Ref<T | undefined>
  /**
   * Indicates if the request has finished
   */
  isFinished: Ref<boolean>
  /**
   * Indicates if the request is currently loading
   */
  isLoading: Ref<boolean>
  /**
   * Indicates if the request was canceled
   */
  isAborted: Ref<boolean>
  /**
   * Any errors that may have occurred
   */
  error: ShallowRef<AxiosError<T, D> | undefined>
  /**
   * Aborts the current request
   */
  abort: (message?: string | undefined) => void
  /**
   * isFinished alias
   * @deprecated use `isFinished` instead
   */
  finished: Ref<boolean>
  /**
   * isLoading alias
   * @deprecated use `isLoading` instead
   */
  loading: Ref<boolean>
  /**
   * isAborted alias
   * @deprecated use `isAborted` instead
   */
  aborted: Ref<boolean>
  /**
   * abort alias
   */
  cancel: (message?: string | undefined) => void
  /**
   * isAborted alias
   * @deprecated use `isCanceled` instead
   */
  canceled: Ref<boolean>
  /**
   * isAborted alias
   */
  isCanceled: Ref<boolean>
}
export interface StrictUseAxiosReturn<T, R, D> extends UseAxiosReturn<T, R, D> {
  /**
   * Manually call the axios request
   */
  execute: (
    url?: string | AxiosRequestConfig<D>,
    config?: AxiosRequestConfig<D>
  ) => PromiseLike<StrictUseAxiosReturn<T, R, D>>
}
export interface EasyUseAxiosReturn<T, R, D> extends UseAxiosReturn<T, R, D> {
  /**
   * Manually call the axios request
   */
  execute: (
    url: string,
    config?: AxiosRequestConfig<D>
  ) => PromiseLike<EasyUseAxiosReturn<T, R, D>>
}
export interface UseAxiosOptions {
  /**
   * Will automatically run axios request when `useAxios` is used
   *
   */
  immediate?: boolean
  /**
   * Use shallowRef.
   *
   * @default true
   */
  shallow?: boolean
}
export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  url: string,
  config?: AxiosRequestConfig<D>,
  options?: UseAxiosOptions
): StrictUseAxiosReturn<T, R, D> & PromiseLike<StrictUseAxiosReturn<T, R, D>>
export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  url: string,
  instance?: AxiosInstance,
  options?: UseAxiosOptions
): StrictUseAxiosReturn<T, R, D> & PromiseLike<StrictUseAxiosReturn<T, R, D>>
export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  url: string,
  config: AxiosRequestConfig<D>,
  instance: AxiosInstance,
  options?: UseAxiosOptions
): StrictUseAxiosReturn<T, R, D> & PromiseLike<StrictUseAxiosReturn<T, R, D>>
export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  config?: AxiosRequestConfig<D>
): EasyUseAxiosReturn<T, R, D> & PromiseLike<EasyUseAxiosReturn<T, R, D>>
export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  instance?: AxiosInstance
): EasyUseAxiosReturn<T, R, D> & PromiseLike<EasyUseAxiosReturn<T, R, D>>
export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  config?: AxiosRequestConfig<D>,
  instance?: AxiosInstance
): EasyUseAxiosReturn<T, R, D> & PromiseLike<EasyUseAxiosReturn<T, R, D>>
export interface UseAxiosReturn<T, R = AxiosResponse<T>, D = any> {
  /**
   * Axios Response
   */
  response: ShallowRef<R | undefined>
  /**
   * Axios response data
   */
  data: Ref<T | undefined>
  /**
   * Indicates if the request has finished
   */
  isFinished: Ref<boolean>
  /**
   * Indicates if the request is currently loading
   */
  isLoading: Ref<boolean>
  /**
   * Indicates if the request was canceled
   */
  isAborted: Ref<boolean>
  /**
   * Any errors that may have occurred
   */
  error: ShallowRef<AxiosError<T, D> | undefined>
  /**
   * Aborts the current request
   */
  abort: (message?: string | undefined) => void
  /**
   * isFinished alias
   * @deprecated use `isFinished` instead
   */
  finished: Ref<boolean>
  /**
   * isLoading alias
   * @deprecated use `isLoading` instead
   */
  loading: Ref<boolean>
  /**
   * isAborted alias
   * @deprecated use `isAborted` instead
   */
  aborted: Ref<boolean>
  /**
   * abort alias
   */
  cancel: (message?: string | undefined) => void
  /**
   * isAborted alias
   * @deprecated use `isCanceled` instead
   */
  canceled: Ref<boolean>
  /**
   * isAborted alias
   */
  isCanceled: Ref<boolean>
}
export interface StrictUseAxiosReturn<T, R, D> extends UseAxiosReturn<T, R, D> {
  /**
   * Manually call the axios request
   */
  execute: (
    url?: string | AxiosRequestConfig<D>,
    config?: AxiosRequestConfig<D>
  ) => PromiseLike<StrictUseAxiosReturn<T, R, D>>
}
export interface EasyUseAxiosReturn<T, R, D> extends UseAxiosReturn<T, R, D> {
  /**
   * Manually call the axios request
   */
  execute: (
    url: string,
    config?: AxiosRequestConfig<D>
  ) => PromiseLike<EasyUseAxiosReturn<T, R, D>>
}
export interface UseAxiosOptions {
  /**
   * Will automatically run axios request when `useAxios` is used
   *
   */
  immediate?: boolean
  /**
   * Use shallowRef.
   *
   * @default true
   */
  shallow?: boolean
}
export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  url: string,
  config?: AxiosRequestConfig<D>,
  options?: UseAxiosOptions
): StrictUseAxiosReturn<T, R, D> & PromiseLike<StrictUseAxiosReturn<T, R, D>>
export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  url: string,
  instance?: AxiosInstance,
  options?: UseAxiosOptions
): StrictUseAxiosReturn<T, R, D> & PromiseLike<StrictUseAxiosReturn<T, R, D>>
export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  url: string,
  config: AxiosRequestConfig<D>,
  instance: AxiosInstance,
  options?: UseAxiosOptions
): StrictUseAxiosReturn<T, R, D> & PromiseLike<StrictUseAxiosReturn<T, R, D>>
export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  config?: AxiosRequestConfig<D>
): EasyUseAxiosReturn<T, R, D> & PromiseLike<EasyUseAxiosReturn<T, R, D>>
export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  instance?: AxiosInstance
): EasyUseAxiosReturn<T, R, D> & PromiseLike<EasyUseAxiosReturn<T, R, D>>
export declare function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  config?: AxiosRequestConfig<D>,
  instance?: AxiosInstance
): EasyUseAxiosReturn<T, R, D> & PromiseLike<EasyUseAxiosReturn<T, R, D>>

Source

SourceDemoDocs

Contributors

Anthony Fu
azaleta
wheat
jahnli
Jean-Baptiste AUBRÉE
Jelf
马灿
lstoeferle
Marcos Dantas
sun0day
vaakian X
flyingTodream
Curt Grimes
Jakub Freisler
Kasper Seweryn
webfansplz
WuLianN
unknown_
Manaus
Alex Kozack
Victor
Antério Vieira

Changelog

v9.3.1 on 10/17/2022
650fd - feat: add R genericity type for custom response data (#2304)
v9.3.0 on 9/26/2022
d065d - feat: add option for choosing shallowRef or ref (#2251)
c8c38 - feat: add second generic type to error (#2248)
f3ae7 - feat: improve type (#2208)
v9.2.0 on 9/5/2022
92630 - feat: support RequestConfig for execute (#2152)
23d18 - fix: reset error on execute (#2095)
v8.9.1 on 7/8/2022
a9ccc - feat(all): use MaybeComputedRef (#1768)
v8.8.0 on 7/6/2022
00d73 - feat: awaitable execute method (#1723)
v8.5.0 on 5/16/2022
b8339 - fix: normalize isCanceled flag (#1585)
v8.4.0 on 5/3/2022
81f35 - fix: exception when args incorrect (#1534)
e2a9a - fix: rename aborted to isAborted (#1519)
v8.2.1 on 3/30/2022
788a7 - fix: reuse url when only AxiosRequestConfig is passed to execute (#1438)
v8.0.0 on 3/11/2022
2a582 - feat: allow not passing url in constructor (#1388)
v8.0.0-beta.1 on 3/5/2022
8812e - feat: allow useAxios to be awaited (#1228)
42fc7 - fix: args param need limit (#1343)
v7.5.5 on 1/25/2022
46752 - feat: added option to control whether the request fires immediately (#1170)

Released under the MIT License.