\n )\n}\n```\n\n## Documentation\n\n### API\n\n- [useAxios](#useaxiosurlconfig-options)\n- [configure](#configure-cache-axios-defaultoptions-)\n- [serializeCache](#serializeCache)\n- [loadCache](#loadcachecache)\n- [makeUseAxios](#makeuseaxios-cache-axios-defaultoptions-)\n\n### Examples\n\n- [Quick start](https://codesandbox.io/s/2oxrlq8rjr)\n- [Manual request](https://codesandbox.io/s/axioshooks-manual-request-bq9w4)\n- [Error handling](https://codesandbox.io/s/axios-hooks-error-handling-gvi41)\n- [Authentication and token refresh](https://codesandbox.io/s/axios-hooks-authentication-zyeyh)\n- [Caching](https://codesandbox.io/s/axios-hooks-caching-nm62v)\n- [Using makeUseAxios](https://codesandbox.io/s/axios-hooks-makeuseaxios-kfuym)\n- [Configuration](https://codesandbox.io/s/oqvxw6mpyq)\n- [Pagination](https://codesandbox.io/s/axios-hooks-pagination-1wk3u)\n- [Infinite scrolling](https://codesandbox.io/s/axios-hooks-infinite-scrolling-42nw6)\n- [Request chaining](https://codesandbox.io/s/axios-hooks-request-chaining-wn12l)\n- [Options change detection](https://codesandbox.io/s/axios-hooks-options-change-v23tl)\n- [react-native](https://snack.expo.io/@simoneb/axios-hooks-react-native)\n- [With react-sortable-hoc](https://codesandbox.io/s/axios-hooks-react-sortable-hoc-eo3oy)\n- [With react-router](https://codesandbox.io/s/axios-hooks-react-router-26iwm)\n\n### Guides\n\n- [Refresh Behavior](#refresh-behavior)\n- [Configuration](#configuration)\n- [Manual Requests](#manual-requests)\n- [Manual Cancellation](#manual-cancellation)\n- [Server Side Rendering](#server-side-rendering)\n- [Multiple Hook Instances](#multiple-hook-instances)\n\n## API\n\nThe package exports one default export and named exports:\n\n```js\nimport useAxios, {\n configure,\n loadCache,\n serializeCache,\n makeUseAxios\n} from 'axios-hooks'\n```\n\n### useAxios(url|config, options)\n\nThe main React hook to execute HTTP requests.\n\n- `url|config` - The request URL or [config](https://github.com/axios/axios#request-config) object, the same argument accepted by `axios`.\n- `options` - An options object.\n - `manual` ( `false` ) - If true, the request is not executed immediately. Useful for non-GET requests that should not be executed when the component renders. Use the `execute` function returned when invoking the hook to execute the request manually.\n - `useCache` ( `true` ) - Allows caching to be enabled/disabled for the hook. It doesn't affect the `execute` function returned by the hook.\n - `ssr` ( `true` ) - Enables or disables SSR support\n - `autoCancel` ( `true` ) - Enables or disables automatic cancellation of pending requests whether it be\n from the automatic hook request or from the `manual` execute method\n\n> [!IMPORTANT] \n> Default caching behavior can interfere with test isolation. Read the [testing](#testing) section for more information.\n\n**Returns**\n\n`[{ data, loading, error, response }, execute, manualCancel]`\n\n- `data` - The [success response](https://github.com/axios/axios#response-schema) data property (for convenient access).\n- `loading` - True if the request is in progress, otherwise False.\n- `error` - The [error](https://github.com/axios/axios#handling-errors) value\n- `response` - The whole [success response](https://github.com/axios/axios#response-schema) object.\n\n- `execute([config[, options]])` - A function to execute the request manually, bypassing the cache by default.\n\n - `config` - Same `config` object as `axios`, which is _shallow-merged_ with the config object provided when invoking the hook. Useful to provide arguments to non-GET requests.\n - `options` - An options object.\n - `useCache` ( `false` ) - Allows caching to be enabled/disabled for this \"execute\" function.\n\n **Returns**\n\n A promise containing the response. If the request is unsuccessful, the promise rejects and the rejection must be handled manually.\n\n- `manualCancel()` - A function to cancel outstanding requests manually.\n\n### configure({ cache, axios, defaultOptions })\n\nAllows to provide custom instances of cache and axios and to override the default options.\n\n- `cache` An instance of [lru-cache](https://github.com/isaacs/node-lru-cache), or `false` to disable the cache\n- `axios` An instance of [axios](https://github.com/axios/axios#creating-an-instance)\n- `defaultOptions` An object overriding the default Hook options. It will be merged with the default options.\n\n### serializeCache()\n\nDumps the request-response cache, to use in server side rendering scenarios.\n\n**Returns**\n\n`Promise` A serializable representation of the request-response cache ready to be used by `loadCache`\n\n### loadCache(cache)\n\nPopulates the cache with serialized data generated by `serializeCache`.\n\n- `cache` The serializable representation of the request-response cache generated by `serializeCache`\n\n### makeUseAxios({ cache, axios, defaultOptions })\n\nCreates an instance of the `useAxios` hook configured with the supplied cache, axios instance and default options.\n\n- `cache` An instance of [lru-cache](https://github.com/isaacs/node-lru-cache), or `false` to disable the cache\n- `axios` An instance of [axios](https://github.com/axios/axios#creating-an-instance)\n- `defaultOptions` An object overriding the default Hook options. It will be merged with the default options.\n\n**Returns**\n\nAn instance of `useAxios` React Hook which will always use the provided cache and axios instance.\n\nThe returned value, besides being a function that can be used as a React Hook, also contains the properties:\n\n- `resetConfigure`\n- `configure`\n- `loadCache`\n- `serializeCache`\n\nwhich are the same as the package's named exports but limited to the `useAxios` instance returned by `makeUseAxios`.\n\n## Refresh Behavior\n\nThe arguments provided to `useAxios(config[,options])` are watched for changes and compared using deep object comparison.\n\nWhen they change, if the configuration allows a request to be fired (e.g. `manual:false`), any pending request is canceled and a new request is triggered, to avoid automatic cancellation you should use `autoCancel:false` option\n\nBecause of this, it's important to make sure that the arguments to `useAxios` preserve deep equality across component renders. This is often the case unless functions (e.g. axios transformers) are provided to a configuration object. In that case, those functions need to be memoized or they will trigger a request execution at each render, leading to an infinite loop.\n\n## Configuration\n\nUnless provided via the `configure` function, `axios-hooks` uses as defaults:\n\n- `axios` - the default `axios` package export\n- `cache` - a new instance of the default `lru-cache` package export, with no arguments\n- `defaultOptions` - `{ manual: false, useCache: true, ssr: true, autoCancel: true }`\n\nThese defaults may not suit your needs, for example:\n\n- you may want a common base url for axios requests\n- the default (Infinite) cache size may not be a sensible default\n- you want to disable caching altogether\n\nIn such cases you can use the `configure` function to provide your custom implementation of both.\n\n> When `configure` is used, it should be invoked once before any usages of the `useAxios` hook\n\n### Example\n\n[](https://codesandbox.io/s/oqvxw6mpyq)\n\n```js\nimport { configure } from 'axios-hooks'\nimport LRU from 'lru-cache'\nimport Axios from 'axios'\n\nconst axios = Axios.create({\n baseURL: 'https://reqres.in/api'\n})\n\nconst cache = new LRU({ max: 10 })\n\nconfigure({ axios, cache })\n```\n\n## Manual Requests\n\nOn the client, requests are executed when the component renders using a React `useEffect` hook.\n\nThis may be undesirable, as in the case of non-GET requests. By using the `manual` option you can skip the automatic execution of requests and use the return value of the hook to execute them manually, optionally providing configuration overrides to `axios`.\n\n### Example\n\nIn the example below we use the `useAxios` hook twice. Once to load the data when the component renders, and once to submit data updates via a `PUT` request configured via the `manual` option.\n\n[](https://codesandbox.io/s/axioshooks-manual-request-bq9w4?fontsize=14)\n\n```js\nimport useAxios from 'axios-hooks'\n\nfunction App() {\n const [{ data: getData, loading: getLoading, error: getError }] = useAxios(\n 'https://reqres.in/api/users/1'\n )\n\n const [{ data: putData, loading: putLoading, error: putError }, executePut] =\n useAxios(\n {\n url: 'https://reqres.in/api/users/1',\n method: 'PUT'\n },\n { manual: true }\n )\n\n function updateData() {\n executePut({\n data: {\n ...getData,\n updatedAt: new Date().toISOString()\n }\n })\n }\n\n if (getLoading || putLoading) return
Loading...
\n if (getError || putError) return
Error!
\n\n return (\n
\n \n
{JSON.stringify(putData || getData, null, 2)}
\n
\n )\n}\n```\n\n## Manual Cancellation\n\nThe cancellation method can be used to cancel an outstanding request whether it be\nfrom the automatic hook request or from the `manual` execute method.\n\n### Example\n\nIn the example below we use the `useAxios` hook with its automatic and manual requests.\nWe can call the cancellation programmatically or via controls.\n\n```js\nfunction App() {\n const [pagination, setPagination] = useState({})\n const [{ data, loading }, refetch, cancelRequest] = useAxios({\n url: '/users?delay=5',\n params: { ...pagination }\n })\n\n const handleFetch = () => {\n setPagination({ per_page: 2, page: 2 })\n }\n\n const externalRefetch = async () => {\n try {\n await refetch()\n } catch (e) {\n // Handle cancellation\n }\n }\n\n return (\n
\n \n \n \n {loading &&
...loading
}\n
{JSON.stringify(data, null, 2)}
\n
\n )\n}\n```\n\n## Server Side Rendering\n\n`axios-hooks` seamlessly supports server side rendering scenarios, by preloading data on the server and providing the data to the client, so that the client doesn't need to reload it.\n\n### How it works\n\n1. the React component tree is rendered on the server\n2. `useAxios` HTTP requests are executed on the server\n3. the server code awaits `serializeCache()` in order to obtain a serializable representation of the request-response cache\n4. the server injects a JSON-serialized version of the cache in a `window` global variable\n5. the client hydrates the cache from the global variable before rendering the application using `loadCache`\n\n### Example\n\n[](https://codesandbox.io/s/v83l3mjq57)\n\n```html\n\n\n\n```\n\n```js\n// server code for the server side rendering handler\n\nimport { serializeCache } from 'axios-hooks'\n\nrouter.use(async (req, res) => {\n const index = fs.readFileSync(`${publicFolder}/index.html`, 'utf8')\n const html = ReactDOM.renderToString()\n\n // wait for axios-hooks HTTP requests to complete\n const cache = await serializeCache()\n\n res.send(\n index\n .replace('{{{html}}}', html)\n .replace('{{{cache}}}', JSON.stringify(cache).replace(/, document.getElementById('root'))\n```\n\n## Multiple Hook Instances\n\nSometimes it is necessary to communicate with different APIs or use different caching strategies for different HTTP interactions.\n\n[`makeUseAxios`](#makeuseaxios-cache-axios) allows to create multiple instances of the `useAxios` React Hook which can be configured and managed independently.\n\nIn other words, `makeUseAxios` is a factory of `useAxios`, which returns a React Hook configured against the provided `axios` or `cache` instances.\n\n> This feature can also be used to create a single pre configured React Hook instance as an alternative to the global `configure` feature\n\n### Example\n\n[](https://codesandbox.io/s/axios-hooks-quick-start-kfuym)\n\n```js\nimport axios from 'axios'\nimport { makeUseAxios } from 'axios-hooks'\n\nconst useAxios = makeUseAxios({\n axios: axios.create({ baseURL: 'https://reqres.in/api' })\n})\n\nfunction App() {\n const [{ data, loading, error }, refetch] = useAxios('/users?delay=1')\n\n if (loading) return
Loading...
\n if (error) return
Error!
\n\n return (\n
\n \n
{JSON.stringify(data, null, 2)}
\n
\n )\n}\n```\n\n## Testing\n\nTesting components that make use of the `useAxios` hook are susceptible to test isolation leakage because of default caching behavior. The following snippets can be used to disable caching while testing:\n\n### react-testing-library\n\n```js\nbeforeAll(() => {\n useAxios.configure({ cache: false })\n})\n```\n\n## Promises\n\naxios-hooks depends on a native ES6 Promise implementation to be [supported](http://caniuse.com/promises).\nIf your environment doesn't support ES6 Promises, you can [polyfill](https://github.com/jakearchibald/es6-promise).\n\n## Credits\n\n`axios-hooks` is heavily inspired by [graphql-hooks](https://github.com/nearform/graphql-hooks),\ndeveloped by the awesome people at [NearForm](https://github.com/nearform).\n\n## License\n\nMIT\n\n[axios]: https://github.com/axios/axios\n","readmeFilename":"README.md"}