English | 简体中文
A React hook plugin for Axios. Lightweight, cancelable and less change.
Usage
Quick Start
import { useResource } from "@axios-use/react";
function Profile({ userId }) {
const [{ data, error, isLoading }] = useResource((id) => ({ url: `/user/${id}` }), [userId]);
if (error) return <div>failed to load</div>;
if (isLoading) return <div>loading...</div>;
return <div>hello {data.name}!</div>;
}
import { useRequest, useResource } from "@axios-use/react";
RequestProvider
import axios from "axios";
import { RequestProvider } from "@axios-use/react";
const axiosInstance = axios.create({
baseURL: "https://example.com/",
});
ReactDOM.render(
<RequestProvider instance={axiosInstance}>
<App />
</RequestProvider>,
document.getElementById("root"),
);
RequestProvider config
config | type | default | explain |
---|
instance | object | axios | axios instance |
cache | object | false | _ttlcache | Customized cache collections. Or close. (Default on) |
cacheKey | function | defaultCacheKeyGenerator | Global custom formatted cache keys |
cacheFilter | function | - | Global callback function to decide whether to cache or not |
customCreateReqError | function | - | Custom format error data |
getResponseItem | function | (r) => r.data | custom data value. The default value is response['data']. |
useRequest
option | type | explain |
---|
fn | function | get AxiosRequestConfig function |
options.onCompleted | function | This function is passed the query's result data. |
options.onError | function | This function is passed an RequestError object |
options.instance | AxiosInstance | Customize the Axios instance of the current item |
const [createRequest, { hasPending, cancel }] = useRequest((id) => ({
url: `/user/${id}`,
method: "DELETE",
}));
const [createRequest, { hasPending, cancel }] = useRequest((id: string) =>
request<Result>({
url: `/user/${id}`,
method: "DELETE",
}),
);
interface CreateRequest {
ready: () => Promise<[Payload<TRequest>, AxiosResponse]>;
cancel: Canceler;
}
type HasPending = boolean;
type Cancel = Canceler;
useEffect(() => {
const { ready, cancel } = createRequest(id);
ready()
.then((res) => {
console.log(res);
})
.catch((err) => {
console.log(err);
});
return cancel;
}, [id]);
const [createRequest, { hasPending, cancel }] = useRequest(
(id) => ({
url: `/user/${id}`,
method: "DELETE",
}),
{
onCompleted: (data, response) => console.info(data, response),
onError: (err) => console.info(err),
},
);
useResource
option | type | explain |
---|
fn | function | get AxiosRequestConfig function |
parameters | array | false | fn function parameters. effect dependency list |
options.cache | object | false | Customized cache collections. Or close |
options.cacheKey | string| number | function | Custom cache key value |
options.cacheFilter | function | Callback function to decide whether to cache or not |
options.filter | function | Request filter. if return a falsy value, will not start the request |
options.defaultState | object | Initialize the state value. {data, response, error, isLoading} |
options.onCompleted | function | This function is passed the query's result data. |
options.onError | function | This function is passed an RequestError object |
options.instance | AxiosInstance | Customize the Axios instance of the current item |
const [{ data, error, isLoading }, fetch, refresh] = useResource((id) => ({
url: `/user/${id}`,
method: "GET",
}));
const [reqState, fetch, refresh] = useResource((id: string) =>
request<Result>({
url: `/user/${id}`,
method: "GET",
}),
);
interface ReqState {
data?: Payload<TRequest>;
response?: AxiosResponse;
error?: RequestError<Payload<TRequest>>;
isLoading: boolean;
cancel: Canceler;
}
type Fetch = (...args: Parameters<TRequest>) => Canceler;
type Refresh = () => Canceler | undefined;
The request can also be triggered passing its arguments as dependencies to the useResource hook.
const [userId, setUserId] = useState();
const [reqState] = useResource(
(id) => ({
url: `/user/${id}`,
method: "GET",
}),
[userId],
);
const [reqState] = useResource(
() => ({
url: "/users/",
method: "GET",
}),
[],
);
const [reqState, request] = useResource(
(id) => ({
url: `/user/${id}`,
method: "GET",
}),
[userId],
{
filter: (id) => id !== "12345",
},
);
request("12345");
const [reqState] = useResource(
() => ({
url: "/users/",
method: "GET",
}),
[],
{
onCompleted: (data, response) => console.info(data, response),
onError: (err) => console.info(err),
},
);
cache
https://codesandbox.io/s/react-request-hook-cache-9o2hz
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.
const api = {
getUsers: () => {
return request<Users>({
url: "/users",
method: "GET",
});
},
getUserInfo: (userId: string) => {
return request<UserInfo>({
url: `/users/${userId}`,
method: "GET",
});
},
};
You can also use these request
functions directly in axios
.
const usersRes = await axios(api.getUsers());
const userRes = await axios(api.getUserInfo("ID001"));
custom response type. (if you change the response's return value. like axios.interceptors.response)
import { request, _request } from "@axios-use/react";
const [reqState] = useResource(() => request<DataType>({ url: `/users` }), []);
reqState.response;
reqState.data;
const [reqState] = useResource(() => _request<MyWrapper<DataType>>({ url: `/users` }), []);
reqState.response;
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.
interface RequestError<T> {
data?: T;
message: string;
code?: string | number;
isCancel: boolean;
original: AxiosError<T>;
}
License
MIT