react-redux-0.5.0.zip

React Redux ========================= Official React bindings for [Redux](https://github.com/gaearon/redux). Performant and flexible. [](https://www.npmjs.com/package/react-redux) [](https://www.npmjs.com/package/react-redux) [](http://www.reactiflux.com) >**Note: There is a project called `redux-react` on NPM that is [completely unrelated](https://github.com/cgarvis/redux-react/issues/1) to the official bindings. This documentation (and any other official Redux documentation) is for `react-redux`.** ## Table of Contents - [React Native](#react-native) - [Quick Start](#quick-start) - [API](#api) - [``](#provider-store) - [`connect([mapState], [mapDispatch], [mergeProps])(Component)`](#connectmapstate-mapdispatch-mergeprops) - [License](#license) ## React Native What you get from `react-redux` is for React. For React Native, import from `react-redux/native` instead. ## Quick Start React bindings for Redux embrace the idea of [dividing “smart” and “dumb” components](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0). It is advisable that only top-level components of your app (such as route handlers, for example) are aware of Redux. Components below them should be “dumb” and receive all data via props.

	Location	Use React-Redux	To read data, they	To change data, they
“Smart” Components	Top level, route handlers	Yes	Subscribe to Redux state	Dispatch Redux actions
“Dumb” Components	Middle and leaf components	No	Read data from props	Invoke callbacks from props

### “Dumb” component is unaware of Redux Let’s say we have a `` “dumb” component with a number `counter` prop, and an `increment` function prop that it will call when user presses an “Increment” button: ```js import { Component } from 'react'; export default class Counter extends Component { render() { return ( {this.props.counter} ); } } ``` ### “Smart” component is `connect()`-ed to Redux Here’s how we hook it up to the Redux Store. We will use `connect()` function provided by `react-redux` to turn a “dumb” `Counter` into a smart component. The `connect()` function lets you specify *which exactly* state from the Redux store your component wants to track. This lets you subscribe on any level of granularity. Passing action creator functions as the second parameter will bind them to the specific store instance, and they will be injected as props with the same names they were exported with. Why don’t we bind action creators to a store right away? This is because of the so-called “universal” apps that need to render on the server. They would have a different store instance for every request, so we don’t know the store instance during the definition! ##### `containers/CounterContainer.js` ```js import { Component } from 'react'; import { connect } from 'react-redux'; // Action creators: import { increment } from '../actionsCreators'; // “Dumb” component: import Counter from '../components/Counter'; // Which part of the Redux global state does our component want to receive as props? function mapState(state) { return { counter: state.counter }; } // First argument tells which state fields it’s interested in. // Second argument tells which action creators to bind and inject. // You may also pass a `dispatch` => Object function as a second argument. export default connect(mapState, { increment })(CounterContainer); ``` Whether to put `connect()` call in the same file as the “dumb” component, or separately, is up to you. Ask yourself whether you'd want to reuse this component but bind it to different data, or not. ### Nesting You can have many `connect()`-ed components in your app at any depth, and you can even nest them. It is however preferable that you try to only `connect()` top-level components such as route handlers, so the data flow in your application stays predictable. ### Support for Decorators You might have noticed that we used parens twice. This is called partial applications, and it lets people use ES7 decorator proposal syntax: ```js // Unstable syntax! It might change or break in production. @connect(mapState) export default class CounterContainer { ... } ``` Don’t forget decorators are experimental! And they desugar to function calls anyway as example above demonstrates. ### Additional Flexibility This the most basic usage, but `connect()` supports many other different patterns: just passing the vanilla `dispatch()` function down, binding multiple action creators, putting them as `actions` prop, selecting parts of state and binding action creators depending on `props`, and so on. Check out `connect()` docs below to learn more. ### Injecting Redux Store Finally, how do we actually hook it up to a Redux store? We need to create the store somewhere at the root of our component hierarchy. For client apps, the root component is a good place. For server rendering, you can do this in the request handler. The trick is to wrap the whole view hierarchy into `{() => ... }` where `Provider` is imported from `react-redux`. One gotcha is that **the child of `Provider` must be a function**. This is to work around an issue with how context (undocumented feature we have to rely on to pass Redux data to components below) works in React 0.13. In React 0.14, you will be able to put your view hierarchy in `` without wrapping it into a function. ```js import { Component } from 'react'; import { Provider } from 'react-redux'; class App extends Component { render() { // ... } } const targetEl = document.getElementById('root'); React.render(( {() => } ), targetEl); ``` ## API ### `` Makes Redux store available to the `connect()` calls in the component hierarchy below. You can’t use `connect()` without wrapping the root component in ``. #### Props * `store`: (*[Redux Store](http://gaearon.github.io/redux/docs/api/Store.html)*): The single Redux store in your application. * `children`: (*Function*): Unlike most React components, `` accepts a [function as a child](#child-must-be-a-function) with your root component. This is a temporary workaround for a React 0.13 context issue, which will be fixed when React 0.14 comes out. #### Example ##### Vanilla React ```js React.render( {() => } , rootEl ); ``` ##### React Router 0.13 ```js Router.run(routes, Router.HistoryLocation, (Handler) => { React.render( {() => } , targetEl ); }); ``` ##### React Router 1.0 ```js React.render( {() => ...} , targetEl ); ``` ### `connect([mapState], [mapDispatch], [mergeProps])` Connects a React component to a Redux store. #### Arguments * [`mapState`] \(*Function*): If specified, the component will subscribe to Redux store updates. Any time it updates, `mapState` will be called. Its result must be a plain object, and it w