Group actions with a predicate
Several related action types need the same state transition.
Redux Toolkit · Module
builder.addMatcher
Registers a reducer for actions selected by a custom matcher function. Matching reducers run in declaration order, after exact cases and before a default case.
How it works
builder.addMatcher registers a matcher function and a case reducer. Whenever the matcher returns true for a dispatched action, the case reducer runs; multiple matching reducers can run in definition order. Register it after exact cases and before a default case.
Syntax
builder.addMatcher(matcher, reducer)Parameters
| Name | Type | Description |
|---|---|---|
matcher | Matcher function | A matcher function; in TypeScript, it should be a type predicate function. |
reducer | CaseReducer | The case reducer to execute when the matcher returns true. |
Returns
A builder object, allowing further reducer registrations to be chained.
Key points
- Use a custom predicate to match actions by arbitrary conditions rather than only by their type string.
- The second argument is the case reducer that updates state for matching actions.
- Matching predicates execute sequentially in the order they were added.
- An exact action-type case takes precedence in execution order over matcher reducers.
Common mistakes
- Register matchers only after exact cases and async-thunk cases.
- A single action can trigger several matcher reducers, so overlapping predicates may update state multiple times.
Example: Handle actions with a custom matcher
import { createReducer } from '@reduxjs/toolkit'
const initialState = { loading: false, completed: 0 }
const isCompletionAction = (action) => action.type.endsWith('/completed')
const reducer = createReducer(initialState, (builder) => {
builder
.addMatcher(isCompletionAction, (state) => {
state.completed += 1
})
.addDefaultCase((state) => {
state.loading = false
})
})This reducer increments a counter for every action whose type ends with /completed.
When to use it
Match custom action conditions
A reducer should react to a property or pattern beyond action.type equality.
Compose cross-cutting handlers
Several independently registered matchers should contribute to one action.
Interview questions
QWhat does builder.addMatcher do?
It accepts a matcher function and a case reducer. The matcher examines each incoming action, and the reducer runs when the matcher returns true.
Follow-up: What happens when an exact case and several matchers match? The exact case runs first, followed by every matching matcher in declaration order.
QHow should the matcher be typed in TypeScript?
A matcher can be used instead of matching only the action.type property. In TypeScript, the matcher should be a type predicate so the reducer's action parameter can be inferred more precisely.
Follow-up: Why use a type predicate? It narrows the action type inside the reducer, enabling type-safe access to matcher-specific fields.
QWhere can addMatcher appear in a builder chain?
The call must follow addCase and addAsyncThunk calls, and it must precede addDefaultCase. This ordering is enforced by the builder API.
Follow-up: What occurs if no case or matcher handles the action? A default case runs when configured; otherwise the existing state is returned unchanged.
Related
createReducercreateSlicebuilder.addCasebuilder.addAsyncThunkbuilder.addDefaultCaseisAnyOfisAllOf