connect()
Overview
The connect()
function connects a React component to a Redux store.
It provides its connected component with the pieces of the data it needs from the store, and the functions it can use to dispatch actions to the store.
It does not modify the component class passed to it; instead, it returns a new, connected component class that wraps the component you passed in.
The mapStateToProps
and mapDispatchToProps
deals with your Redux store’s state
and dispatch
, respectively. state
and dispatch
will be supplied to your mapStateToProps
or mapDispatchToProps
functions as the first argument.
The returns of mapStateToProps
and mapDispatchToProps
are referred to internally as stateProps
and dispatchProps
, respectively. They will be supplied to mergeProps
, if defined, as the first and the second argument, where the third argument will be ownProps
. The combined result, commonly referred to as mergedProps
, will then be supplied to your connected component.
connect()
Parameters
connect()
Parametersconnect
accepts four different parameters, all optional. By convention, they are called:
mapStateToProps?: Function
mapDispatchToProps?: Function | Object
mergeProps?: Function
options?: Object
mapStateToProps?: (state, ownProps?) => Object
mapStateToProps?: (state, ownProps?) => Object
If a mapStateToProps
function is specified, the new wrapper component will subscribe to Redux store updates. This means that any time the store is updated, mapStateToProps
will be called. The results of mapStateToProps
must be a plain object, which will be merged into the wrapped component’s props. If you don't want to subscribe to store updates, pass null
or undefined
in place of mapStateToProps
.
Parameters
state: Object
ownProps?: Object
A mapStateToProps
function takes a maximum of two parameters. The number of declared function parameters (a.k.a. arity) affects when it will be called. This also determines whether the function will receive ownProps. See notes here.
state
If your mapStateToProps
function is declared as taking one parameter, it will be called whenever the store state changes, and given the store state as the only parameter.
ownProps
If your mapStateToProps
function is declared as taking two parameters, it will be called whenever the store state changes or when the wrapper component receives new props (based on shallow equality comparisons). It will be given the store state as the first parameter, and the wrapper component's props as the second parameter.
The second parameter is normally referred to as ownProps
by convention.
Returns
Your mapStateToProps
functions are expected to return an object. This object, normally referred to as stateProps
, will be merged as props to your connected component. If you define mergeProps
, it will be supplied as the first parameter to mergeProps
.
The return of the mapStateToProps
determine whether the connected component will re-render (details here).
For more details on recommended usage of mapStateToProps
, please refer to our guide on using mapStateToProps
.
You may define
mapStateToProps
andmapDispatchToProps
as a factory function, i.e., you return a function instead of an object. In this case your returned function will be treated as the realmapStateToProps
ormapDispatchToProps
, and be called in subsequent calls. You may see notes on Factory Functions or our guide on performance optimizations.
mapDispatchToProps?: Object | (dispatch, ownProps?) => Object
mapDispatchToProps?: Object | (dispatch, ownProps?) => Object
Conventionally called mapDispatchToProps
, this second parameter to connect()
may either be an object, a function, or not supplied.
Your component will receive dispatch
by default, i.e., when you do not supply a second parameter to connect()
:
If you define a mapDispatchToProps
as a function, it will be called with a maximum of two parameters.
Parameters
dispatch: Function
ownProps?: Object
dispatch
If your mapDispatchToProps
is declared as a function taking one parameter, it will be given the dispatch
of your store
.
ownProps
If your mapDispatchToProps
function is declared as taking two parameters, it will be called with dispatch
as the first parameter and the props passed to the wrapper component as the second parameter, and will be re-invoked whenever the connected component receives new props.
The second parameter is normally referred to as ownProps
by convention.
The number of declared function parameters of mapDispatchToProps
determines whether they receive ownProps. See notes here.
Returns
Your mapDispatchToProps
functions are expected to return an object. Each fields of the object should be a function, calling which is expected to dispatch an action to the store.
The return of your mapDispatchToProps
functions are regarded as dispatchProps
. It will be merged as props to your connected component. If you define mergeProps
, it will be supplied as the second parameter to mergeProps
.
For more details on recommended usage, please refer to our guide on using mapDispatchToProps
.
You may define
mapStateToProps
andmapDispatchToProps
as a factory function, i.e., you return a function instead of an object. In this case your returned function will be treated as the realmapStateToProps
ormapDispatchToProps
, and be called in subsequent calls. You may see notes on Factory Functions or our guide on performance optimizations.
Object Shorthand Form
mapDispatchToProps
may be an object where each field is an action creator.
In this case, React-Redux binds the dispatch
of your store to each of the action creators using bindActionCreators
. The result will be regarded as dispatchProps
, which will be either directly merged to your connected components, or supplied to mergeProps
as the second argument.
We also have a section in our mapDispatchToProps
guide on the usage of object shorthand form here.
mergeProps?: (stateProps, dispatchProps, ownProps) => Object
mergeProps?: (stateProps, dispatchProps, ownProps) => Object
If specified, defines how the final props for your own wrapped component are determined. If you do not provide mergeProps
, your wrapped component receives { ...ownProps, ...stateProps, ...dispatchProps }
by default.
Parameters
mergeProps
should be specified with maximum of three parameters. They are the result of mapStateToProps()
, mapDispatchToProps()
, and the wrapper component's props
, respectively:
stateProps
dispatchProps
ownProps
The fields in the plain object you return from it will be used as the props for the wrapped component. You may specify this function to select a slice of the state based on props, or to bind action creators to a particular variable from props.
Returns
The return value of mergeProps
is referred to as mergedProps
and the fields will be used as the props for the wrapped component.
options?: Object
options?: Object
context: Object
context: Object
Note: This parameter is supported in >= v6.0 only
React-Redux v6 allows you to supply a custom context instance to be used by React-Redux. You need to pass the instance of your context to both <Provider />
and your connected component. You may pass the context to your connected component either by passing it here as a field of option, or as a prop to your connected component in rendering.
pure: boolean
pure: boolean
default value:
true
Assumes that the wrapped component is a “pure” component and does not rely on any input or state other than its props and the selected Redux store’s state.
When options.pure
is true, connect
performs several equality checks that are used to avoid unnecessary calls to mapStateToProps
, mapDispatchToProps
, mergeProps
, and ultimately to render
. These include areStatesEqual
, areOwnPropsEqual
, areStatePropsEqual
, and areMergedPropsEqual
. While the defaults are probably appropriate 99% of the time, you may wish to override them with custom implementations for performance or other reasons.
We provide a few examples in the following sections.
areStatesEqual: (next: Object, prev: Object) => boolean
areStatesEqual: (next: Object, prev: Object) => boolean
default value:
strictEqual: (next, prev) => prev === next
When pure, compares incoming store state to its previous value.
Example 1
You may wish to override areStatesEqual
if your mapStateToProps
function is computationally expensive and is also only concerned with a small slice of your state. The example above will effectively ignore state changes for everything but that slice of state.
Example 2
If you have impure reducers that mutate your store state, you may wish to override areStatesEqual
to always return false:
This would likely impact the other equality checks as well, depending on your mapStateToProps
function.
areOwnPropsEqual: (next: Object, prev: Object) => boolean
default value:
shallowEqual: (objA, objB) => boolean
( returnstrue
when each field of the objects is equal )
When pure, compares incoming props to its previous value.
You may wish to override areOwnPropsEqual
as a way to whitelist incoming props. You'd also have to implement mapStateToProps
, mapDispatchToProps
and mergeProps
to also whitelist props. (It may be simpler to achieve this other ways, for example by using recompose's mapProps.)
areStatePropsEqual: (next: Object, prev: Object) => boolean
areStatePropsEqual: (next: Object, prev: Object) => boolean
type:
function
default value:
shallowEqual
When pure, compares the result of mapStateToProps
to its previous value.
areMergedPropsEqual: (next: Object, prev: Object) => boolean
areMergedPropsEqual: (next: Object, prev: Object) => boolean
default value:
shallowEqual
When pure, compares the result of mergeProps
to its previous value.
You may wish to override areStatePropsEqual
to use strictEqual
if your mapStateToProps
uses a memoized selector that will only return a new object if a relevant prop has changed. This would be a very slight performance improvement, since would avoid extra equality checks on individual props each time mapStateToProps
is called.
You may wish to override areMergedPropsEqual
to implement a deepEqual
if your selectors produce complex props. ex: nested objects, new arrays, etc. (The deep equal check may be faster than just re-rendering.)
forwardRef: boolean
forwardRef: boolean
Note: This parameter is supported in >= v6.0 only
If {forwardRef : true}
has been passed to connect
, adding a ref to the connected wrapper component will actually return the instance of the wrapped component.
connect()
Returns
connect()
ReturnsThe return of connect()
is a wrapper function that takes your component and returns a wrapper component with the additional props it injects.
In most cases, the wrapper function will be called right away, without being saved in a temporary variable:
Example Usage
Because connect
is so flexible, it may help to see some additional examples of how it can be called:
Inject just
dispatch
and don't listen to store
Inject all action creators (
addTodo
,completeTodo
, ...) without subscribing to the store
Inject
dispatch
and every field in the global state
Don’t do this! It kills any performance optimizations because
TodoApp
will rerender after every state change. It’s better to have more granularconnect()
on several components in your view hierarchy that each only listen to a relevant slice of the state.
Inject
dispatch
andtodos
Inject
todos
and all action creators
Inject
todos
and all action creators (addTodo
,completeTodo
, ...) asactions
Inject
todos
and a specific action creator (addTodo
)
Inject
todos
and specific action creators (addTodo
anddeleteTodo
) with shorthand syntax
Inject
todos
,todoActionCreators
astodoActions
, andcounterActionCreators
ascounterActions
Inject
todos
, and todoActionCreators and counterActionCreators together asactions
Inject
todos
, and alltodoActionCreators
andcounterActionCreators
directly as props
Inject
todos
of a specific user depending on props
Inject
todos
of a specific user depending on props, and injectprops.userId
into the action
Notes
The Arity of mapToProps
Functions
mapToProps
FunctionsThe number of declared function parameters of mapStateToProps
and mapDispatchToProps
determines whether they receive ownProps
Note:
ownProps
is not passed tomapStateToProps
andmapDispatchToProps
if the formal definition of the function contains one mandatory parameter (function has length 1). For example, functions defined like below won't receiveownProps
as the second argument
Functions with no mandatory parameters or two parameters*will receive ownProps
.
Factory Functions
If your mapStateToProps
or mapDispatchToProps
functions return a function, they will be called once when the component instantiates, and their returns will be used as the actual mapStateToProps
, mapDispatchToProps
, functions respectively, in their subsequent calls.
The factory functions are commonly used with memoized selectors. This gives you the ability to create component-instance-specific selectors inside the closure:
Last updated