createAction
createAction
createAction
A helper function for defining a Redux action type and creator.
The usual way to define an action in Redux is to separately declare an action type constant and an action creator function for constructing actions of that type.
The createAction
helper combines these two declarations into one. It takes an action type and returns an action creator for that type. The action creator can be called either without arguments or with a payload
to be attached to the action. Also, the action creator overrides toString() so that the action type becomes its string representation.
Using Prepare Callbacks to Customize Action Contents
By default, the generated action creators accept a single argument, which becomes action.payload
. This requires the caller to construct the entire payload correctly and pass it in.
In many cases, you may want to write additional logic to customize the creation of the payload
value, such as accepting multiple parameters for the action creator, generating a random ID, or getting the current timestamp. To do this, createAction
accepts an optional second argument: a "prepare callback" that will be used to construct the payload value.
If provided, all arguments from the action creator will be passed to the prepare callback, and it should return an object with the payload
field (otherwise the payload of created actions will be undefined
). Additionally, the object can have a meta
and/or an error
field that will also be added to created actions. meta
may contain extra information about the action, error
may contain details about the action failure. These three fields (payload
, meta
and error
) adhere to the specification of Flux Standard Actions.
Note: The type field will be added automatically.
Usage with createReducer()
Because of their toString()
override, action creators returned by createAction()
can be used directly as keys for the case reducers passed to createReducer().
Non-String Action Types
In principle, Redux lets you use any kind of value as an action type. Instead of strings, you could theoretically use numbers, symbols, or anything else (although it's recommended that the value should at least be serializable).
However, Redux Toolkit rests on the assumption that you use string action types. Specifically, some of its features rely on the fact that with strings, the toString()
method of an createAction()
action creator returns the matching action type. This is not the case for non-string action types because toString()
will return the string-converted type value rather than the type itself.
This means that, for instance, you cannot use a non-string-type action creator as a case reducer key for createReducer().
For this reason, we strongly recommend you to only use string action types.
actionCreator.match
Every generated actionCreator has a .match(action)
method that can be used to determine if the passed action is of the same type as an action that would be created by the action creator.
This has different uses:
As a TypeScript Type Guard
This match
method is a TypeScript type guard and can be used to discriminate the payload
type of an action.
This behavior can be particularly useful when used in custom middlewares, where manual casts might be neccessary otherwise.
With redux-observable
The match
method can also be used as a filter method, which makes it powerful when used with redux-observable:
Last updated