Action-driven side effects
Run analytics, persistence, notifications, or other side effects after a specific Redux action is dispatched.
Redux Toolkit · Module
listenerMiddleware.startListening
Registers a listener entry on Redux Toolkit listener middleware. The supplied effect runs when exactly one configured action or state predicate matches, and the returned function removes that listener.
How it works
Call startListening with an effect and exactly one matching rule. The middleware checks each dispatched action against that rule; when it matches, it invokes the effect with the action and a listener API. The call returns an unsubscribe function that can remove the registered listener.
Syntax
const startListening = (options: AddListenerOptions) => UnsubscribeListenerParameters
| Name | Type | Description |
|---|---|---|
options | AddListenerOptions | Configuration object containing exactly one trigger selector and the effect callback; the selector may be type, actionCreator, matcher, or predicate. |
Returns
UnsubscribeListener
Key points
- The method registers a listener directly on the middleware, typically during application setup.
- Define long-lived listeners while configuring the application rather than dispatching runtime registration actions.
- The effect callback contains the side-effect logic executed after the listener condition matches.
- Effects can return immediately or perform asynchronous work by returning a promise.
- Runtime registration is available separately when listeners must be added dynamically.
Common mistakes
- Supply exactly one of type, actionCreator, matcher, or predicate; combining matching options is invalid.
- A broad matcher or predicate can cause the effect to be evaluated for every dispatch, so keep matching logic deliberate.
Example: Listen for an action creator
import { createListenerMiddleware, createAction } from '@reduxjs/toolkit'
const listenerMiddleware = createListenerMiddleware()
const increment = createAction<number>('counter/increment')
listenerMiddleware.startListening({
actionCreator: increment,
effect: async (action, listenerApi) => {
console.log('Incremented by', action.payload)
listenerApi.cancelActiveListeners()
},
})This registers an effect that runs whenever the increment action creator matches a dispatched action.
When to use it
Reactive async workflows
Coordinate workflows that wait for later actions, delays, or state conditions inside an effect.
State-change reactions
Observe a state transition by comparing current and previous state in a predicate.
Interview questions
QWhat does startListening do?
It registers a listener entry on the middleware and returns an unsubscribe function. The entry contains an effect plus exactly one condition: type, actionCreator, matcher, or predicate.
Follow-up: How would you remove a statically registered listener? Call the returned unsubscribe function.
QWhat arguments does the effect receive?
The effect receives the matched action and listenerApi, and it may be synchronous or asynchronous. listenerApi provides middleware operations such as dispatching, reading state, delaying, and cancellation.
Follow-up: How can a listener react to state changes rather than a particular action type? Use predicate and compare the current and previous state.
QHow is the listener trigger selected?
Use actionCreator for an exact Redux Toolkit action-creator match, matcher for matching among multiple actions, type for an exact string type, or predicate for a custom action-and-state test. Exactly one of these four options is required.
Follow-up: When would matcher be preferable to actionCreator? Use matcher when several action creators share a condition, commonly through an RTK matcher helper.
Related
createListenerMiddlewareaddListenerremoveListenerListenerApiListenerPredicateMatcher