Guide · Open source

How to use redux-thunk: setup, examples and FAQs

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Redux Thunk is middleware for Redux, the state management library for JavaScript apps. It lets you write functions that read the store's state and dispatch actions, which is useful for delayed updates, conditional updates and simple async work such as API requests. This guide shows how to install it, enable it, write your first thunk and decide whether it fits your project.

Redux Thunkreduxjs/redux-thunk · ★ 17.7k · MIT Install options & downloads

Quick start

1Check your setup. If you use Redux Toolkit, skip installation because the thunk middleware is included. Otherwise, you need Node.js and npm or yarn.
2Install the package. Run npm install redux-thunk or yarn add redux-thunk in your project.
3Import the thunk middleware. Use import { thunk } from 'redux-thunk' in ES modules or the same named export with require in CommonJS.
4Apply it to the store. Pass thunk to applyMiddleware when creating a store with createStore.
5Write a thunk action creator. Return a function that receives dispatch and getState, then dispatch actions when your logic is ready.
6Add a custom argument if needed. Use extraArgument with configureStore or withExtraArgument() to inject a service such as an API layer.

Do you need to install redux-thunk?

If you use the official Redux Toolkit package, you do not need to install anything. Its configureStore API already adds the thunk middleware by default.

If you use the basic Redux createStore API, add the redux-thunk package yourself. The README lists both npm and yarn commands.

Prerequisites: Node.js and npm or yarn
Redux Toolkit: thunk middleware is included automatically
Manual setup: install redux-thunk and apply it with applyMiddleware

npm install redux-thunk

yarn add redux-thunk

Enable the thunk middleware in your store

With Redux Toolkit, configureStore already includes the thunk middleware, so you only define your reducers.

With plain Redux, import the thunk named export and pass it to applyMiddleware. In CommonJS environments, the same named export is available through require.

ES modules: import { thunk } from 'redux-thunk'
CommonJS: const { thunk } = require('redux-thunk')

import { createStore, applyMiddleware } from 'redux'
import { thunk } from 'redux-thunk'
import rootReducer from './reducers/index'

const store = createStore(rootReducer, applyMiddleware(thunk))

Write your first thunk action creator

A normal action creator returns an action object. A thunk action creator returns a function instead. Redux Thunk calls that function and passes it dispatch and getState, so it can wait, check state and then dispatch.

The README example delays an increment by one second using setTimeout. A conditional version reads the current state with getState and returns early when no dispatch is needed.

Delayed dispatch: wrap dispatch(increment()) in a timer or async callback
Conditional dispatch: read state with getState() and dispatch only when a condition is met
Return values: anything the inner function returns becomes the return value of dispatch

function incrementAsync() {
  return dispatch => {
    setTimeout(() => {
      dispatch(increment())
    }, 1000)
  }
}

function incrementIfOdd() {
  return (dispatch, getState) => {
    const { counter } = getState()

    if (counter % 2 === 0) {
      return
    }

    dispatch(increment())
  }
}

Pass a custom argument for testing or service layers

Since version 2.1.0, Redux Thunk can inject a custom argument into the thunk middleware. The README says this is useful for swapping an API service for a mock service in tests.

With Redux Toolkit, pass extraArgument through the thunk option of getDefaultMiddleware. To pass several values, combine them into one object. With hand-built stores, use the withExtraArgument() named export.

Redux Toolkit: getDefaultMiddleware({ thunk: { extraArgument } })
Multiple values: put them in a single object and destructure it in the thunk
Manual store: applyMiddleware(withExtraArgument(api))

const store = configureStore({
  reducer: rootReducer,
  middleware: getDefaultMiddleware =>
    getDefaultMiddleware({
      thunk: {
        extraArgument: myCustomApiService,
      },
    }),
})

function fetchUser(id) {
  return (dispatch, getState, api) => {
    // use api here
  }
}

Understand what a thunk is

A thunk is a function that wraps an expression to delay its evaluation. Calling the function later performs the work. In Redux, a thunk action creator returns such a function, and the middleware runs it.

The README notes that the term started as a humorous past-tense version of "think". For deeper patterns, the README points to the Redux docs page Writing Logic with Thunks.

Know the limits of redux-thunk

Redux Thunk only works as Redux middleware, so it is not useful if your app does not use Redux. The README is also clear that it targets basic side effects such as simple async logic and API requests.

For complex async flows, such as cancellation or event streams, the README points you to comparing other async middleware. The comparable projects it names are redux-saga, redux-observable and Redux Toolkit's createAsyncThunk.

Not for apps without Redux
Not a fit for cancellation or event-stream flows without comparing alternatives
Compare with redux-saga, redux-observable and createAsyncThunk

What people use it for

Delaying a dispatch with a timer, as in the README's incrementAsync example
Dispatching an action only when the current state meets a condition, as in incrementIfOdd
Making simple AJAX or API requests and dispatching the result to the store
Swapping a real API service for a mock during tests using extraArgument

Frequently asked questions

How do I install redux-thunk?

Run npm install redux-thunk or yarn add redux-thunk. If you use Redux Toolkit, you do not need to install it separately because configureStore already adds the thunk middleware.

Do I need redux-thunk with Redux Toolkit?

No. The README says RTK's configureStore API already adds the thunk middleware by default, so there is nothing to install or apply.

Is redux-thunk free to use?

redux-thunk is licensed under the MIT licence. Check the repository's licence file for the full terms.

What are the alternatives to redux-thunk?

The README names redux-saga, redux-observable and Redux Toolkit's createAsyncThunk as comparable projects. It suggests these for complex async flows such as cancellation or event streams.

Why is my thunk not running?

Check that the thunk middleware is applied to the store. With plain Redux, pass thunk to applyMiddleware. Also confirm that the action creator returns a function, because the middleware only handles functions.

Can redux-thunk be used without Redux?

No. The README describes it as Thunk middleware for Redux, so it only works inside a Redux store.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Redux Thunk suits teams that already use Redux and need delayed, conditional or simple async dispatches, especially with Redux Toolkit where it is included. If your app does not use Redux or needs cancellation or event streams, compare redux-saga, redux-observable or createAsyncThunk first.

Install options & downloads