{"files":[{"status":"M","path":"docs\/_data\/nav_docs.yml"},{"status":"A","path":"docs\/docs\/higher-order-components.md"}],"commit":{"shortRevision":"ce3b7ca475","authorName":"Andrew Clark","revision":"ce3b7ca475000eafe293bfea5f219a96073aa270","subject":"Add a document on higher-order components (#7869)","authorEmail":"acdlite@me.com","authoredAt":"2016-11-29T12:47:54-06:00"},"body":"","parents":["16bf42902926dd401206d8cff5ad61c0d7d49c96"],"patch":"diff --git a\/docs\/_data\/nav_docs.yml b\/docs\/_data\/nav_docs.yml\nindex a6be939b77..1e66741d1f 100644\n--- a\/docs\/_data\/nav_docs.yml\n+++ b\/docs\/_data\/nav_docs.yml\n@@ -48,6 +48,8 @@\n title: Context\n - id: web-components\n title: Web Components\n+ - id: higher-order-components\n+ title: Higher-Order Components\n - title: Reference\n items:\n - id: react-api\ndiff --git a\/docs\/docs\/higher-order-components.md b\/docs\/docs\/higher-order-components.md\nnew file mode 100644\nindex 0000000000..58d8b59292\n--- \/dev\/null\n+++ b\/docs\/docs\/higher-order-components.md\n@@ -0,0 +1,421 @@\n+---\n+id: higher-order-components\n+title: Higher-Order Components\n+permalink: docs\/higher-order-components.html\n+---\n+\n+A higher-order component (HOC) is an advanced technique in React for reusing component logic. HOCs are not part of the React API, per se. They are a pattern that emerges from React's compositional nature.\n+\n+Concretely, **a higher-order component is a function that takes a component and returns a new component.**\n+\n+```js\n+const EnhancedComponent = higherOrderComponent(WrappedComponent);\n+```\n+\n+Whereas a component transforms props into UI, a higher-order component transforms a component into another component.\n+\n+HOCs are common in third-party React libraries, such as Redux's [`connect`](https:\/\/github.com\/reactjs\/react-redux\/blob\/master\/docs\/api.md#connectmapstatetoprops-mapdispatchtoprops-mergeprops-options) and Relay's [`createContainer`](https:\/\/facebook.github.io\/relay\/docs\/api-reference-relay.html#createcontainer-static-method).\n+\n+In this document, we'll discuss why higher-order components are useful, and how to write your own.\n+\n+## Use HOCs For Cross-Cutting Concerns\n+\n+> **Note**\n+>\n+> We previously recommended mixins as a way to handle cross-cutting concerns. We've since realized that mixins create more trouble than they are worth. [Read more](\/react\/blog\/2016\/07\/13\/mixins-considered-harmful.html) about why we've moved away from mixins and how you can transition your existing components.\n+\n+Components are the primary unit of code reuse in React. However, you'll find that some patterns aren't a straightforward fit for traditional components.\n+\n+For example, say you have a `CommentList` component that subscribes to an external data source to render a list of comments:\n+\n+```js\n+class CommentList extends React.Component {\n+ constructor() {\n+ super();\n+ this.handleChange = this.handleChange.bind(this);\n+ this.state = {\n+ \/\/ \"DataSource\" is some global data source\n+ comments: DataSource.getComments()\n+ };\n+ }\n+\n+ componentDidMount() {\n+ \/\/ Subscribe to changes\n+ DataSource.addChangeListener(this.handleChange);\n+ }\n+\n+ componentWillUnmount() {\n+ \/\/ Clean up listener\n+ DataSource.removeChangeListener(this.handleChange);\n+ }\n+\n+ handleChange() {\n+ \/\/ Update component state whenever the data source changes\n+ this.setState({\n+ comments: DataSource.getComments()\n+ });\n+ }\n+\n+ render() {\n+ return (\n+

\n+ {this.state.comments.map((comment) => (\n+ \n+ ))}\n+ <\/div>\n+ );\n+ }}\n+```\n+\n+Later, you write a component for subscribing to a single blog post, which follows a similar pattern:\n+\n+```js\n+class BlogPost extends React.Component {\n+ constructor() {\n+ super();\n+ this.handleChange = this.handleChange.bind(this);\n+ this.state = {\n+ blogPost: DataSource.getBlogPost(props.id)\n+ };\n+ }\n+\n+ componentDidMount() {\n+ DataSource.addChangeListener(this.handleChange);\n+ }\n+\n+ componentWillUnmount() {\n+ DataSource.removeChangeListener(this.handleChange);\n+ }\n+\n+ handleChange() {\n+ this.setState({\n+ blogPost: DataSource.getBlogPost(this.props.id)\n+ });\n+ }\n+\n+ render() {\n+ return ;\n+ }}\n+```\n+\n+`CommentList` and `BlogPost` aren't identical — they call different methods on `DataSource`, and they render different output. But much of their implementation is the same:\n+\n+- On mount, add a change listener to `DataSource`.\n+- Inside the listener, call `setState` whenever the data source changes.\n+- On unmount, remove the change listener.\n+\n+You can imagine that in a large app, this same pattern of subscribing to `DataSource` and calling `setState` will occur over and over again. We want an abstraction that allows us to define this logic in a single place and share them across many components. This is where higher-order components excel.\n+\n+We can write a function that creates components, like `CommentList` and `BlogPost`, that subscribe to `DataSource`. The function will accept as one of its arguments a child component that receives the subscribed data as a prop. Let's call the function `withSubscription`:\n+\n+```js\n+const CommentListWithSubscription = withSubscription(\n+ CommentList,\n+ (DataSource) => DataSource.getComments()\n+);\n+\n+const BlogPostWithSubscription = withSubscription(\n+ BlogPost,\n+ (DataSource, props) => DataSource.getBlogPost(props.id)\n+});\n+```\n+\n+The first parameter is the wrapped component. The second parameter retrieves the data we're interested in, given a `DataSource` and the current props.\n+\n+When `CommentListWithSubscription` and `BlogPostWithSubscription` are rendered, `CommentList` and `BlogPost` will be passed a `data` prop with the most current data retrieved from `DataSource`:\n+\n+```js\n+\/\/ This function takes a component...\n+function withSubscription(WrappedComponent, selectData) {\n+ \/\/ ...and returns another component...\n+ return class extends React.Component {\n+ constructor(props) {\n+ super(props);\n+ this.handleChange = this.handleChange.bind(this);\n+ this.state = {\n+ data: selectData(DataSource, props)\n+ };\n+ }\n+\n+ componentDidMount() {\n+ \/\/ ... that takes care of the subscription...\n+ DataSource.addChangeListener(this.handleChange);\n+ }\n+\n+ componentWillUnmount() {\n+ DataSource.removeChangeListener(this.handleChange);\n+ }\n+\n+ handleChange() {\n+ this.setState({\n+ comments: selectData(DataSource, this.props)\n+ });\n+ }\n+\n+ render() {\n+ \/\/ ... and renders the wrapped component with the fresh data!\n+ \/\/ Notice that we pass through any additional props\n+ return ;\n+ }\n+ });\n+}\n+```\n+\n+Note that an HOC doesn't modify the input component, nor does it use inheritance to copy its behavior. Rather, an HOC *composes* the original component by *wrapping* it in a container component. An HOC is a pure function with zero side-effects.\n+\n+And that's it! The wrapped component receives all the props of the container, along with a new prop, `data`, which it uses to render its output. The HOC isn't concerned with how or why the data is used, and the wrapped component isn't concerned with where the data came from.\n+\n+Because `withSubscription` is a normal function, you can add as many or as few arguments as you like. For example, you may want to make the name of the `data` prop configurable, to further isolate the HOC from the wrapped component. Or you could accept an argument that configures `shouldComponentUpdate`, or one that configures the data source. These are all possible because the HOC has full control over how the component is defined.\n+\n+Like components, the contract between `withSubscription` and the wrapped component is entirely props-based. This makes it easy to swap one HOC for a different one, as long as they provide the same props to the wrapped component. This may be useful if you change data-fetching libraries, for example.\n+\n+## Don't Mutate the Original Component. Use Composition.\n+\n+Resist the temptation to modify a component's prototype (or otherwise mutate it) inside an HOC.\n+\n+```js\n+function logProps(InputComponent) {\n+ InputComponent.prototype.componentWillReceiveProps(nextProps) {\n+ console.log('Current props: ', this.props);\n+ console.log('Next props: ', nextProps);\n+ }\n+ \/\/ The fact that we're returning the original input is a hint that it has\n+ \/\/ been mutated.\n+ return InputComponent;\n+}\n+\n+\/\/ EnhancedComponent will log whenever props are received\n+const EnhancedComponent = logProps(InputComponent);\n+```\n+\n+There are a few problems with this. One is that the input component cannot be reused separately from the enhanced component. More crucially, if you apply another HOC to `EnhancedComponent` that *also* mutates `shouldComponentUpdate`, the first HOC's functionality will be overridden! This HOC also won't work with function components, which do not have lifecycle methods.\n+\n+Mutating HOCs are a leaky abstraction—the consumer must know how they are implemented in order to avoid conflicts with other HOCs.\n+\n+Instead of mutation, HOCs should use composition, by wrapping the input component in a container component:\n+\n+```js\n+function logProps(WrappedComponent) {\n+ return class extends React.Component {\n+ componentWillReceiveProps(nextProps) {\n+ console.log('Current props: ', this.props);\n+ console.log('Next props: ', nextProps);\n+ }\n+ render() {\n+ \/\/ Wraps the input component in a container, without mutating it. Good!\n+ return ;\n+ }\n+ }\n+}\n+```\n+\n+This HOC has the same functionality as the mutating version while avoiding the potential for clashes. It works equally well with class and functional components. And because it's a pure function, it's composable with other HOCs, or even with itself.\n+\n+You may have noticed similarities between HOCs and a pattern called **container components**. Container components are part of a strategy of separating responsibility between high-level and low-level concerns. Containers manage things like subscriptions and state, and pass props to components that handle things like rendering UI. HOCs use containers as part of their implementation. You can think of HOCs as parameterized container component definitions.\n+\n+## Convention: Pass Unrelated Props Through to the Wrapped Component\n+\n+HOCs add features to a component. They shouldn't drastically alter its contract. It's expected that the component returned from an HOC has a similar interface to the wrapped component.\n+\n+HOCs should pass through props that are unrelated to its specific concern. Most HOCs contain a render method that looks something like this:\n+\n+```js\n+render() {\n+ \/\/ Filter out extra props that are specific to this HOC and shouldn't be\n+ \/\/ passed through\n+ const { extraProp, ...passThroughProps } = this.props;\n+\n+ \/\/ Inject props into the wrapped component. These are usually state values or\n+ \/\/ instance methods.\n+ const injectedProp = someStateOrInstanceMethod;\n+\n+ \/\/ Pass props to wrapped component\n+ return (\n+ \n+ );\n+}\n+```\n+\n+This convention helps ensure that HOCs are as flexible and reusable as possible.\n+\n+## Convention: Maximizing Composability\n+\n+Not all HOCs look the same. Sometimes they accept only a single argument, the wrapped component:\n+\n+```js\n+const NavbarWithRouter = withRouter(Navbar);\n+```\n+\n+Usually, HOCs accept additional arguments. In this example from Relay, a config object is used to specify a component's data dependencies:\n+\n+```js\n+const CommentWithRelay = Relay.createContainer(Comment, config);\n+```\n+\n+The most common signature for HOCs looks like this:\n+\n+```js\n+\/\/ React Redux's `connect`\n+const ConnectedComment = connect(commentSelector, commentActions)(Comment);\n+```\n+\n+*What?!* If you break it apart, it's easier to see what's going on.\n+\n+```js\n+\/\/ connect is a function that returns another function\n+const enhance = connect(commentListSelector, commentListActions);\n+\/\/ The returned function is an HOC, which returns a component that is connected\n+\/\/ to the Redux store\n+const ConnectedComment = enhance(CommentList);\n+```\n+In other words, `connect` is a higher-order function that returns a higher-order component!\n+\n+This form may seem confusing or unnecessary, but it has a useful property. Single-argument HOCs like the one returned by the `connect` function have the signature `Component => Component`. Functions whose output type is the same as its input type are really easy to compose together.\n+\n+```js\n+\/\/ Instead of doing this...\n+const EnhancedComponent = connect(commentSelector)(withRouter(WrappedComponent))\n+\n+\/\/ ... you can use a function composition utility\n+\/\/ compose(f, g, h) is the same as (...args) => f(g(h(...args)))\n+const enhance = compose(\n+ \/\/ These are both single-argument HOCs\n+ connect(commentSelector),\n+ withRouter\n+)\n+const EnhancedComponent = enhance(WrappedComponent)\n+```\n+\n+(This same property also allows `connect` and other enhancer-style HOCs to be used as decorators, an experimental JavaScript proposal.)\n+\n+The `compose` utility function is provided by many third-party libraries including lodash (as [`lodash.flowRight`](https:\/\/lodash.com\/docs\/#flowRight)), [Redux](http:\/\/redux.js.org\/docs\/api\/compose.html), and [Rambda](http:\/\/ramdajs.com\/docs\/#compose).\n+\n+## Convention: Wrap the Display Name for Easy Debugging\n+\n+The container components created by HOCs show up in the [React Developer Tools](https:\/\/github.com\/facebook\/react-devtools) like any other component. To ease debugging, choose a display name that communicates that it's the result of an HOC.\n+\n+The most common technique is to wrap the display name of the wrapped component. So if your higher-order component is named `withSubscription`, and the wrapped component's display name is `CommentList`, use the display name `WithSubscription(CommentList)`:\n+\n+```js\n+function withSubscription(WrappedComponent) {\n+ class WithSubscription extends React.Component {\/* ... *\/}\n+ WithSubscription.displayName = `WithSubscription(${getDisplayName(WrappedComponent)})`;\n+ return WithSubscription;\n+}\n+\n+function getDisplayName(WrappedComponent) {\n+ return WrappedComponent.displayName || WrappedComponent.name || 'Component';\n+}\n+```\n+\n+\n+## Caveats\n+\n+Higher-order components come with a few caveats that aren't immediately obvious if you're new to React.\n+\n+### Don't Use HOCs Inside the render Method\n+\n+React's diffing algorithm (called reconciliation) uses component identity to determine whether it should update the existing subtree or throw it away and mount a new one. If the component returned from `render` is identical (`===`) to the component from the previous render, React recursively updates the subtree by diffing it with the new one. If they're not equal, the previous subtree is unmounted completely.\n+\n+Normally, you shouldn't need to think about this. But it matters for HOCs because it means you can't apply an HOC to a component within the render method of a component:\n+\n+```js\n+render() {\n+ \/\/ A new version of EnhancedComponent is created on every render\n+ \/\/ EnhancedComponent1 !== EnhancedComponent2\n+ const EnhancedComponent = enhance(MyComponent);\n+ \/\/ That causes the entire subtree to unmount\/remount each time!\n+ return ;\n+}\n+```\n+\n+The problem here isn't just about performance — remounting a component causes the state of that component and all of its children to be lost.\n+\n+Instead, apply HOCs outside the component definition so that the resulting component is created only once. Then, its identity will be consistent across renders. This is usually what you want, anyway.\n+\n+In those rare cases where you need to apply an HOC dynamically, you can also do it inside a component's lifecycle methods or its constructor.\n+\n+### Static Methods Must Be Copied Over\n+\n+Sometimes it's useful to define a static method on a React component. For example, Relay containers expose a static method `getFragment` to facilitate the composition of GraphQL fragments.\n+\n+When you apply an HOC to a component, though, the original component is wrapped with a container component. That means the new component does not have any of the static methods of the original component.\n+\n+```js\n+\/\/ Define a static method\n+WrappedComponent.staticMethod = function() {\/*...*\/}\n+\/\/ Now apply an HOC\n+const EnhancedComponent = enhance(WrappedComponent);\n+\n+\/\/ The enhanced component has no static method\n+typeof EnhancedComponent.staticMethod === 'undefined' \/\/ true\n+```\n+\n+To solve this, you could copy the methods onto the container before returning it:\n+\n+```js\n+function enhance(WrappedComponent) {\n+ class Enhance extends React.Component {\/*...*\/}\n+ \/\/ Must know exactly which method(s) to copy :(\n+ Enhance.staticMethod = WrappedComponent.staticMethod;\n+ return Enhance;\n+}\n+```\n+\n+However, this requires you to know exactly which methods need to be copied. You can use [hoist-non-react-statics](https:\/\/github.com\/mridgway\/hoist-non-react-statics) to automatically copy all non-React static methods:\n+\n+```js\n+import hoistNonReactStatic from 'hoist-non-react-statics';\n+function enhance(WrappedComponent) {\n+ class Enhance extends React.Component {\/*...*\/}\n+ hoistNonReactStatic(Enhance, WrappedComponent);\n+ return Enhance;\n+}\n+```\n+\n+Another possible solution is to export the static method separately from the component itself.\n+\n+```js\n+\/\/ Instead of...\n+MyComponent.someFunction = someFunction;\n+export default MyComponent;\n+\n+\/\/ ...export the method separately...\n+export { someFunction };\n+\n+\/\/ ...and in the consuming module, import both\n+import MyComponent, { someFunction } from '.\/MyComponent.js';\n+```\n+\n+### Refs Aren't Passed Through\n+\n+While the convention for higher-order components is to pass through all props to the wrapped component, it's not possible to pass through refs. That's because `ref` is not really a prop — like `key`, it's handled specially by React. If you add a ref to an element whose component is the result of an HOC, the ref refers to an instance of the outermost container component, not the wrapped component.\n+\n+If you find yourself facing this problem, the ideal solution is to figure out how to avoid using `ref` at all. Occasionally, users who are new to the React paradigm rely on refs in situations where a prop would work better.\n+\n+That said, there are times when refs are a necessary escape hatch — React wouldn't support them otherwise. Focusing an input field is an example where you may want imperative control of a component. In that case, one solution is to pass a ref callback as a normal prop, by giving it a different name:\n+\n+```js\n+function Field({ inputRef, ...rest }) {\n+ return ;\n+}\n+\n+\/\/ Wrap Field in a higher-order component\n+const EnhancedField = enhance(Field);\n+\n+\/\/ Inside a class component's render method...\n+ {\n+ \/\/ This callback gets passed through as a regular prop\n+ this.inputEl = inputEl\n+ }}\n+\/>\n+\n+\/\/ Now you can call imperative methods\n+this.inputEl.focus();\n+```\n+\n+This is not a perfect solution by any means. We prefer that refs remain a library concern, rather than require you to manually handle them. We are exploring ways to solve this problem so that using an HOC is unobservable.\n"}

dillon1000/react

Files changed