Model an async request lifecycle
A request needs standardized loading, success, and failure actions.
Redux Toolkit · Type Alias
AsyncThunk
AsyncThunk is the thunk action-creator type generated by createAsyncThunk. It coordinates a promise-returning payload creator with pending, fulfilled, and rejected lifecycle actions.
How it works
AsyncThunk is the generated thunk type associated with createAsyncThunk. The factory combines an action-type prefix with a payload callback, then produces a callable thunk action creator whose nested pending, fulfilled, and rejected creators describe the promise lifecycle; the payload callback also receives thunkAPI for store access and request controls.
Syntax
createAsyncThunk<Returned, ThunkArg, ThunkApiConfig>(typePrefix, payloadCreator, options?)Parameters
| Name | Type | Description |
|---|---|---|
type | string | String prefix used to construct the async lifecycle action types. |
payloadCreator | (arg, thunkAPI) => Promise | value | Callback that receives the thunk argument and thunkAPI and returns a promise or value. |
options | AsyncThunkOptions | Optional configuration for the generated thunk, including behavior such as error handling, cancellation, and conditional execution. |
Returns
A standard Redux thunk action creator with nested pending, fulfilled, and rejected action creators; dispatching it returns a promise containing the corresponding lifecycle action object.
Key points
- AsyncThunk is produced from an action-type prefix and a promise-returning payload creator.
- The prefix determines the generated pending, fulfilled, and rejected action-type names.
- The payload creator can use thunkAPI to access store operations and other request-related capabilities.
- Lifecycle ordering starts with pending, then ends in fulfilled or rejected based on the promise outcome.
Common mistakes
- Treat the lifecycle creators as nested properties of the returned thunk rather than as separate top-level exports.
- Dispatching the thunk does not normally produce a rejected promise; use the documented unwrapping approach when callers need rejection behavior.
- Bundle multiple input values into one object or another single value before dispatching.
Example: Creating and matching an async thunk
import { createAsyncThunk } from '@reduxjs/toolkit'
export const fetchUser = createAsyncThunk(
'users/fetchById',
async (userId: number, thunkAPI) => {
const response = await fetch(`/api/users/${userId}`)
if (!response.ok) throw new Error('Request failed')
return response.json() as Promise<{ id: number; name: string }>
}
)
fetchUser.pending.match({ type: 'users/fetchById/pending' })This creates an async thunk whose attached lifecycle creators can be matched independently.
When to use it
Run request logic with thunkAPI
A payload callback needs store state, dispatch, cancellation, or request metadata.
Handle an async result
A caller must react to a request result after dispatching it.
Interview questions
QWhat does an AsyncThunk provide?
AsyncThunk represents the thunk action creator produced by createAsyncThunk. It is callable for dispatch and exposes pending, fulfilled, and rejected action creators as nested fields.
Follow-up: How can lifecycle actions be recognized generically? Use matching utilities such as isAsyncThunkAction to type-guard actions created by createAsyncThunk.
QHow are the lifecycle actions generated?
The factory takes an action-type prefix and a payload creator, with an optional options object. The payload creator returns a promise, and the thunk dispatches pending before it runs, followed by fulfilled or rejected according to the result.
Follow-up: What context does the payload creator receive? Its second argument is thunkAPI, which includes dispatch, getState, extra, requestId, signal, and rejectWithValue.
QWhat does dispatching the thunk return?
Dispatching an AsyncThunk returns a promise that resolves with either the fulfilled action object or the rejected action object. This consistent resolution behavior lets callers inspect the result or use the documented unwrap mechanism.
Follow-up: Why use unwrap? Awaiting dispatch(thunk()).unwrap() makes the caller receive the fulfilled payload or handle a failure at the component level.
Related
createAsyncThunkisAsyncThunkActionpendingfulfilledrejectedunwrap