Reactive side effects
Run analytics, persistence, or other side effects after selected actions.
Redux Toolkit · Function
createListenerMiddleware
Creates Redux middleware for running effect callbacks in response to matching actions or state changes. It also provides APIs for registering listeners statically or dynamically and for building async workflows.
How it works
Call createListenerMiddleware to obtain a middleware instance and listener-management methods. Register listeners with startListening using one matching strategy and an effect callback; install the instance's middleware in configureStore, preferably first so add/remove actions precede serializability checks.
Syntax
createListenerMiddleware(options?: CreateListenerMiddlewareOptions<ExtraArgument>): ListenerMiddlewareInstanceParameters
| Name | Type | Description |
|---|---|---|
options | CreateListenerMiddlewareOptions<ExtraArgument> | Optional configuration object for the middleware instance; the API reference documents an optional extra argument used by listener effects. |
Returns
A listener middleware instance containing middleware, startListening, stopListening, clearListeners, and action creators for adding and removing listeners.
Key points
- The API creates middleware entries whose effect callbacks run additional logic when their trigger matches.
- Effects can dispatch actions and inspect current state without placing side-effect code in reducers.
- The listener API supports coordinated asynchronous workflows, including waiting, pausing, child tasks, and unsubscribing.
- Use startListening during application setup for statically registered listeners.
- Runtime registration is possible wherever dispatch is available, including React components.
- The returned instance is not automatically active; configureStore must receive its middleware member.
Common mistakes
- Each listener entry must choose exactly one trigger: type, actionCreator, matcher, or predicate.
- Because listener-management actions carry functions, place the middleware before the serializability-check middleware.
Example: Register an action listener
import { configureStore, createListenerMiddleware, createAction } from '@reduxjs/toolkit'
const todoAdded = createAction<{ text: string }>('todos/added')
const listenerMiddleware = createListenerMiddleware()
listenerMiddleware.startListening({
actionCreator: todoAdded,
effect: async (action, listenerApi) => {
console.log(action.payload.text)
listenerApi.cancelActiveListeners()
},
})
const store = configureStore({
reducer: (state = {}, action) => state,
middleware: (getDefaultMiddleware) =>
getDefaultMiddleware().prepend(listenerMiddleware.middleware),
})
store.dispatch(todoAdded({ text: 'Learn listeners' }))Creates a listener, registers it for a specific action, and installs its middleware before the default middleware.
When to use it
Async workflows
Wait for actions or state transitions and coordinate cancellable child work.
Dynamic listener management
Register or remove behavior from code that only has access to dispatch.
Interview questions
QWhat does createListenerMiddleware return, and how is it installed?
createListenerMiddleware returns an instance containing the middleware plus methods for registering and managing listeners. The middleware must be added to the store through configureStore's middleware option.
Follow-up: How would you ensure listener-management actions avoid serializability warnings? Add the listener middleware first, before the serializability check middleware.
QWhat can a listener effect access?
A listener effect receives the matched action and a listenerApi object. The effect can use dispatch and getState, and listenerApi provides workflow helpers such as take, condition, pause, fork, and unsubscribe.
Follow-up: What enables long-running workflows? Combine helpers such as condition, pause, fork, and cancellation-related methods inside the effect.
QHow does a listener decide when to run?
Listeners can match by type, actionCreator, matcher, or predicate, and exactly one of those matching options must be supplied. The effect runs when the selected condition matches dispatched actions or state changes, depending on the option used.
Follow-up: How can listeners be changed after startup? Dispatch addListener or removeListener actions to add or remove entries dynamically.
Related
listenerMiddleware.middlewarelistenerMiddleware.startListeninglistenerMiddleware.addListeneraddListenerremoveListenerclearAllListenersListenerEffectAPI