# `useRequest(cb, options?)`
> Finally, easy way to use async functions in React
[](https://www.npmjs.com/package/use-request)
Call, observe, and persist the result of your async functions with the ease!
See how it works:
```tsx
const RandomNumberGenerator = () => {
const request = useRequest(() => api('/random-number'))
return (
{request.value &&
Here is your random number: {request.value}
}
{request.error &&
Request failed due to: {request.error}
}
)
}
```
Now, step-by-step:
## Install
```bash
npm install --save use-request
```
## Usage
```tsx
import useRequest, { UseRequestStatus } from 'use-request'
const Example = () => {
const request = useRequest(
callback, // Async function (can be sync if needed)
[] // Optional arguments list. The callback will be called immediately if this is set
)
// Results
request.value // Last result of the callback
request.error // Last error thrown from the callback
// Methods
request.execute(...callbackArgs) // Proxy to trigger the callback()
request.reset() // Drop the state and cancel ongoing requests
// Lifecycle
request.idle // True, when request is not initialized or was reset, use for initial screen
request.pending // True, when the request is ongoing, use to show spinners, disabled forms, etc.
request.completed // True, when the request is successfully resolved
request.failed // True, when the request is rejected
request.status // Value of UseRequestStatus enum, helpful for tracking request status
// ...
}
```
### The simplest usage sample
```tsx
function SaveButton() {
const request = useRequest(() => api('/save'))
return
}
```
### Make it run instantly
```tsx
function useUserData() {
const request = useRequest(() => api('/user'), [])
return request.value
}
```
### Configure it
```tsx
function useUserData(userId) {
const request = useRequest((id) => api(`/user/${id}`), [userId])
return request.value
}
```
### Use arguments with `execute()`
```tsx
const RemoveButton = (id) => {
const request = useRequest((itemId) => api.delete(`/items/${itemId}`))
return
}
```
### Observe the state
```tsx
const Button = ({ label, callback }) => {
const request = useRequest(callback)
return (
)
}
```
## Options Object Syntax
Instead of passing an array as the second argument, you can pass an options object:
```tsx
const request = useRequest(callback, {
deps: [userId], // Dependencies array (triggers immediate execution)
optimisticPatch: (args) => expectedValue, // Optimistic update value
})
```
This is backwards compatible - arrays still work as before.
## Patching State
You can manually update the request state using `patch()` and `patchValue()`:
### `patchValue(value)`
Update just the value:
```tsx
const request = useRequest(fetchItems, [])
// Add an item optimistically
const addItem = (newItem) => {
request.patchValue((items) => [...items, newItem])
api.addItem(newItem).catch(() => request.resetPatch())
}
```
### `patch({ value?, error? })`
Update the entire state (replaces, does not merge):
```tsx
// Set both value and error
request.patch({ value: newValue, error: undefined })
// Clear value, set error
request.patch({ error: 'Something went wrong' })
// Use function form to derive from current state
request.patch((current) => ({ value: transform(current.value) }))
```
### `resetPatch()`
Restore the last real state from the server:
```tsx
const request = useRequest(fetchItems, [])
request.patchValue([...items, optimisticItem])
// If something goes wrong:
request.resetPatch() // Restores to last server response
```
### `patched` property
Track whether the current state is from a patch:
```tsx
request.patched // false | 'manual' | 'auto'
// false - real data from request
// 'manual' - set via patch() or patchValue()
// 'auto' - set via optimisticPatch option
```
Example usage:
```tsx
{request.patched && Saving...}
```
## Optimistic Updates with `optimisticPatch`
Set a value immediately when `execute()` is called, before the request completes:
```tsx
const useLike = (postId) => {
const request = useRequest(
(id, liked) => api.setLike(id, liked),
{
optimisticPatch: (args) => ({ liked: args[1] }) // args = [postId, liked]
}
)
return request
}
// Usage
const { value, execute, patched } = useLike(postId)
```
### Behavior on failure
When a request fails with `optimisticPatch`:
- The patched value is **kept** (not rolled back)
- The error is set
- `patched` remains `'auto'`
Use `resetPatch()` to manually revert if needed:
```tsx
if (request.failed && request.patched) {
// Show error with option to revert
}
```
## More Examples
### Using it for a single async function
[Source code](https://github.com/termosa/use-request/blob/master/example/src/SingleFunctionExample.js)
```tsx
const generateNumber = (max) =>
new Promise((resolve, reject) => {
if (max > 0) setTimeout(resolve, 2e3, Math.round(Math.random() * max))
else setTimeout(reject, 2e3, 'Max value must be greater than zero')
})
const defaultMax = 100
const SingleFunctionExample = () => {
const [max, setMax] = React.useState('')
const { value, error, pending } = useRequest(
generateNumber, // Async function that returns promise
[max ? +max : defaultMax] // Initial arguments
)
return (