react-redux-0.5.2.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>`](#provider-store) - [`connect([mapStateToProps], [mapDispatchToProps], [mergeProps])`](#connectmapstatetoprops-mapdispatchtoprops-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. <center> <table> <thead> <tr> <th></th> <th>Location</th> <th>Use React-Redux</th> <th>To read data, they</th> <th>To change data, they</th> </tr> </thead> <tbody> <tr> <td>“Smart” Components</td> <td>Top level, route handlers</td> <td>Yes</th> <td>Subscribe to Redux state</td> <td>Dispatch Redux actions</td> </tr> <tr> <td>“Dumb” Components</td> <td>Middle and leaf components</td> <td>No</th> <td>Read data from props</td> <td>Invoke callbacks from props</td> </tr> </tbody> </table> </center> ### “Dumb” component is unaware of Redux Let’s say we have a `<Counter />` “dumb” component with a number `value` prop, and an `onIncrement` 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 ( <button onClick={this.props.onIncrement}> {this.props.value} </button> ); } } ``` ### “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. ##### `containers/CounterContainer.js` ```js import { Component } from 'react'; import { connect } from 'react-redux'; import Counter from '../components/Counter'; import { increment } from '../actionsCreators'; // Which part of the Redux global state does our component want to receive as props? function mapStateToProps(state) { return { value: state.counter }; } // Which action creators does it want to receive by props? function mapDispatchToProps(dispatch) { return { onIncrement: () => dispatch(increment()) }; } export default connect( mapStateToProps, mapDispatchToProps )(Counter); // You can also pass an object instead of defining `mapDispatchToProps`: // export default connect(mapStateToProps, CounterActionCreators)(Counter); // Or you can pass `dispatch` down as a prop if you omit `mapDispatchToProps`: // export default connect(mapStateToProps)(Counter); // See more recipes in detailed connect() examples below. ``` 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(mapStateToProps) 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 `<Provider>{() => ... }</Provider>` 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 `<Provider>` 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(( <Provider store={store}> {() => <App />} </Provider> ), targetEl); ``` ## API ### `<Provider store>` Makes Redux store available to the `connect()` calls in the component hierarchy below. You can’t use `connect()` without wrapping the root component in `<Provider>`. #### 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, `<Provider>` 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( <Provider store={store}> {() => <MyRootComponent>} </Provider>, rootEl ); ``` ##### React Router 0.13 ```js Router.run(routes, Router.HistoryLocation, (Handler) => { React.render( <Provider store={store}> {() => <Handler />} </Provider>, targetEl ); }); ``` ##### React Router 1.0 ```js React.render( <Provider store={store}> {() => <Router history={history}>...</Router>} </Provider>, targetEl ); ``` ### `connect([mapStateToProps], [mapDispatchToProps], [mergeProps])` Connects a React component to a Redux store. #### Arguments * [`mapStateToProps(state): stateProps`] \(*Function*): If specified, the component will subscribe to Redux store updates. Any time it updates, `mapStateToProps` will be called. Its result must be a plain object, and it will be merged into the component’s props. If you omit it, the component will not be subscribed to the Redux store. * [