A Vue composition utilities for Axios. Lightweight, cancelable and less change.

npm i axios @axios-use/vue

• 🪽 Lightweight with 1.7kb bundle size
• 👼 Less change. Increment, doesn't affect current Axios usage
• ✨ Written in TypeScript
• 🚀 Cancelable. Auto / Manual cancellation of duplicate requests
• 🙆‍♂️ Works with both Vue 2.7 and Vue 3

Usage

Quick Start

1<script setup>
2import { defineProps, toRef } from "vue";
3import { useResource } from "@axios-use/vue";
4
5const props = defineProps(["userId"]);
6const userId = toRef(props, "userId");
7const [reqState] = useResource((id) => ({ url: `/user/${id}` }), [userId]);
8</script>
9
10<template>
11  <div v-if="reqState.error">{{ reqState.error?.message || "error" }}</div>
12  <div v-else-if="reqState.isLoading === false">{{ reqState.data?.name }}</div>
13  <div v-else>...</div>
14</template>

1import { useRequest, useResource } from "@axios-use/vue";

Options (optional)

1import axios from "axios";
2import AxiosUseVue from "@axios-use/vue";
3
4import App from "./App.vue";
5
6// custom Axios instance. https://github.com/axios/axios#creating-an-instance
7const axiosInstance = axios.create({
8  baseURL: "https://example.com/",
9});
10
11const app = createApp(App);
12// custom instance
13app.use(AxiosUseVue, { instance: axiosInstance });
14
15app.mount("#app");

1// Vue.js v2.7
2Vue.use(AxiosUseVue, { instance: axiosInstance });

useRequest

1// js
2const [createRequest, { hasPending, cancel }] = useRequest((id) => ({
3  url: `/user/${id}`,
4  method: "DELETE",
5}));
6
7// ts
8const [createRequest, { hasPending, cancel }] = useRequest((id: string) =>
9  // response.data: Result. AxiosResponse<Result>
10  request<Result>({
11    url: `/user/${id}`,
12    method: "DELETE",
13  }),
14);

1interface CreateRequest {
2  // Promise function
3  ready: () => Promise<[Payload<T>, AxiosResponse]>;
4  // Axios Canceler. clear current request.
5  cancel: Canceler;
6}
7
8type HasPending = ComputedRef<boolean>;
9// Axios Canceler. clear all pending requests(CancelTokenSource).
10type Cancel = Canceler;

1// options: onCompleted, onError
2const [createRequest, { hasPending, cancel }] = useRequest(
3  (id) => ({
4    url: `/user/${id}`,
5    method: "DELETE",
6  }),
7  {
8    onCompleted: (data, response) => console.info(data, response),
9    onError: (err) => console.info(err),
10  },
11);

useResource

1// js
2const [reqState, fetch, refresh, cancel] = useResource((id) => ({
3  url: `/user/${id}`,
4  method: "GET",
5}));
6
7// ts
8const [reqState, fetch, refresh] = useResource((id: string) =>
9  // response.data: Result. AxiosResponse<Result>
10  request<Result>({
11    url: `/user/${id}`,
12    method: "GET",
13  }),
14);

1type ReqState = ComputedRef<{
2  // Result
3  data?: Payload<T>;
4  // axios response
5  response?: AxiosResponse;
6  // normalized error
7  error?: RequestError;
8  isLoading: boolean;
9}>;
10
11// `options.filter` will not be called
12type Fetch = (...args: Parameters<T>) => Canceler;
13
14// 1. Same as `fetch`. But no parameters required. Inherit `useResource` parameters
15// 2. Will call `options.filter`
16type Refresh = () => Canceler | undefined;
17type Cancel = Canceler;

The request can also be triggered passing its arguments as dependencies to the useResource hook.

1const userId = ref("001");
2
3const [reqState] = useResource(
4  (id) => ({
5    url: `/user/${id}`,
6    method: "GET",
7  }),
8  [userId],
9);
10
11// no parameters
12const [reqState] = useResource(
13  () => ({
14    url: "/users/",
15    method: "GET",
16  }),
17  [],
18);
19
20// conditional
21const [reqState, request] = useResource(
22  (id) => ({
23    url: `/user/${id}`,
24    method: "GET",
25  }),
26  [userId],
27  {
28    filter: (id) => id !== "12345",
29  },
30);
31
32request("12345"); // custom request is still useful
33
34// ComputedRef parameter
35const params = computed(() => ({ id: unref(userId) }));
36const [reqState, request] = useResource(
37  ({ id }) => ({
38    url: `/user/${id}`,
39    method: "GET",
40  }),
41  [params],
42);
43
44// reactive parameter
45const params = reactive({ id: userId });
46const [reqState, request] = useResource(
47  ({ id }) => ({
48    url: `/user/${id}`,
49    method: "GET",
50  }),
51  [params],
52);
53
54// options: onCompleted, onError
55const [reqState] = useResource(
56  () => ({
57    url: "/users/",
58    method: "GET",
59  }),
60  [],
61  {
62    onCompleted: (data, response) => console.info(data, response),
63    onError: (err) => console.info(err),
64  },
65);

other

request

The request function allows you to define the response type coming from it. It also helps with creating a good pattern on defining your API calls and the expected results. It's just an identity function that accepts the request config and returns it. Both useRequest and useResource extract the expected and annotated type definition and resolve it on the response.data field.

1import { request } from "@axios-use/vue";
2
3const api = {
4  getUsers: () => {
5    return request<Users>({
6      url: "/users",
7      method: "GET",
8    });
9  },
10
11  getUserInfo: (userId: string) => {
12    return request<UserInfo>({
13      url: `/users/${userId}`,
14      method: "GET",
15    });
16  },
17};

You can also use these request functions directly in axios.

1const usersRes = await axios(api.getUsers());
2
3const userRes = await axios(api.getUserInfo("ID001"));

custom response type. (if you change the response's return value. like axios.interceptors.response)

1import { request, _request } from "@axios-use/vue";
2
3const [reqState] = useResource(() => request<DataType>({ url: `/users` }));
4// AxiosResponse<DataType>
5unref(reqState).response;
6// DataType
7unref(reqState).data;
8
9// custom response type
10const [reqState] = useResource(() => _request<MyWrapper<DataType>>({ url: `/users` }));
11// MyWrapper<DataType>
12unref(reqState).response;
13// MyWrapper<DataType>["data"]. maybe `undefined` type.
14// You can use `getResponseItem` to customize the value of `data`
15unref(reqState).data;

createRequestError

The createRequestError normalizes the error response. This function is used internally as well. The isCancel flag is returned, so you don't have to call axios.isCancel later on the promise catch block.

1interface RequestError<T> {
2  data?: T;
3  message: string;
4  code?: string | number;
5  isCancel: boolean;
6  original: AxiosError<T>;
7}

License

MIT