@ -113,8 +113,8 @@ We're discontinuing active maintenance of React Addons packages. In truth, most
- **react-addons-create-fragment** – React 16 will have first-class support for fragments, at which point this package won't be necessary. We recommend using arrays of keyed elements instead.
- **react-addons-css-transition-group** - Use [react-transition-group/CSSTransitionGroup](https://github.com/reactjs/react-transition-group) instead. Version 1.1.1 provides a drop-in replacement.
- **react-addons-linked-state-mixin** - Explicitly set the `value` and `onChange` handler instead.
- **react-addons-pure-render-mixin** - Use [`React.PureComponent`](/docs/react-api.html#react.purecomponent) instead.
- **react-addons-shallow-compare** - Use [`React.PureComponent`](/docs/react-api.html#react.purecomponent) instead.
- **react-addons-pure-render-mixin** - Use [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) instead.
- **react-addons-shallow-compare** - Use [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) instead.
- **react-addons-transition-group** - Use [react-transition-group/TransitionGroup](https://github.com/reactjs/react-transition-group) instead. Version 1.1.1 provides a drop-in replacement.
- **react-addons-update** - Use [immutability-helper](https://github.com/kolodny/immutability-helper) instead, a drop-in replacement.
- **react-linked-input** - Explicitly set the `value` and `onChange` handler instead.
@ -163,7 +163,7 @@ Below is a detailed list of them.
```
React 15: Converts `NaN`s to strings and passes them through.
React 16: Warns and ignores them.
React 16: Converts `NaN`s to strings and passes them through with a warning.
While testing this release, we have also [created an automatically generated table](https://github.com/facebook/react/blob/master/fixtures/attribute-behavior/AttributeTableSnapshot.md) for all known attributes to track potential regressions.
@ -151,7 +151,7 @@ Refer to the previous announcement for [suggestions on how to migrate](/blog/201
React 16 includes a number of small breaking changes. These only affect uncommon use cases and we don't expect them to break most apps.
* React 15 had limited, undocumented support for error boundaries using `unstable_handleError`. This method has been renamed to `componentDidCatch`. You can use a codemod to [automatically migrate to the new API](https://github.com/reactjs/react-codemod#error-boundaries).
* `ReactDOM.render` and `ReactDOM.unstable_renderIntoContainer` now return null if called from inside a lifecycle method. To work around this, you can use [portals](https://github.com/facebook/react/issues/10309#issuecomment-318433235) or [refs](https://github.com/facebook/react/issues/10309#issuecomment-318434635).
* `ReactDOM.render` and `ReactDOM.unstable_renderSubtreeIntoContainer` now return null if called from inside a lifecycle method. To work around this, you can use [portals](https://github.com/facebook/react/issues/10309#issuecomment-318433235) or [refs](https://github.com/facebook/react/issues/10309#issuecomment-318434635).
* `setState`:
* Calling `setState` with null no longer triggers an update. This allows you to decide in an updater function if you want to re-render.
* Calling `setState` directly in render always causes an update. This was not previously the case. Regardless, you should not be calling setState from render.
> `shallowCompare` is a legacy add-on. Use [`React.PureComponent`](/docs/react-api.html#react.purecomponent) instead.
> `shallowCompare` is a legacy add-on. Use [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) instead.
**Importing**
@ -19,7 +19,7 @@ var shallowCompare = require('react-addons-shallow-compare'); // ES5 with npm
## Overview
Before [`React.PureComponent`](/docs/react-api.html#react.purecomponent) was introduced, `shallowCompare` was commonly used to achieve the same functionality as [`PureRenderMixin`](pure-render-mixin.html) while using ES6 classes with React.
Before [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) was introduced, `shallowCompare` was commonly used to achieve the same functionality as [`PureRenderMixin`](pure-render-mixin.html) while using ES6 classes with React.
If your React component's render function is "pure" (in other words, it renders the same result given the same props and state), you can use this helper function for a performance boost in some cases.
Pass a mocked component module to this method to augment it with useful methods that allow it to be used as a dummy React component. Instead of rendering as usual, the component will become a simple `<div>` (or other tag if `mockTagName` is provided) containing any provided children.
> Note:
>
> `mockComponent()` is a legacy API. We recommend using [shallow rendering](/docs/test-utils.html#shallow-rendering) or [`jest.mock()`](https://facebook.github.io/jest/docs/en/tutorial-react-native.html#mock-native-modules-using-jestmock) instead.
@ -21,8 +21,8 @@ The add-ons below are in the development (unminified) version of React only:
The add-ons below are considered legacy and their use is discouraged. They will keep working in observable future, but there is no further development.
- [`PureRenderMixin`](pure-render-mixin.html). Use [`React.PureComponent`](/docs/react-api.html#react.purecomponent) instead.
- [`shallowCompare`](shallow-compare.html), a helper function that performs a shallow comparison for props and state in a component to decide if a component should update.
- [`PureRenderMixin`](pure-render-mixin.html). Use [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) instead.
- [`shallowCompare`](shallow-compare.html), a helper function that performs a shallow comparison for props and state in a component to decide if a component should update. We recommend using [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) instead.
- [`update`](update.html). Use [`kolodny/immutability-helper`](https://github.com/kolodny/immutability-helper) instead.
- [`ReactDOMFactories`](dom-factories.html), pre-configured DOM factories to make React easier to use without JSX.
@ -139,3 +139,16 @@ class LoggingButton extends React.Component {
```
The problem with this syntax is that a different callback is created each time the `LoggingButton` renders. In most cases, this is fine. However, if this callback is passed as a prop to lower components, those components might do an extra re-rendering. We generally recommend binding in the constructor or using the class fields syntax, to avoid this sort of performance problem.
## Passing Arguments to Event Handlers
Inside a loop it is common to want to pass an extra parameter to an event handler. For example, if `id` is the row ID, either of the following would work:
The above two lines are equivalent, and use [arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions) and [`Function.prototype.bind`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_objects/Function/bind) respectively.
In both cases, the `e` argument representing the React event will be passed as a second argument after the ID. With an arrow function, we have to pass it explicitly, but with `bind` any further arguments are automatically forwarded.
@ -95,7 +95,7 @@ In order to accept your pull request, we need you to submit a CLA. You only need
### Contribution Prerequisites
* You have `node` installed at v4.0.0+ and `npm` at v2.0.0+.
* You have `node` installed at v6.0.0+ and `npm` at v3.0.0+.
* You have `gcc` installed or are comfortable installing a compiler if needed. Some of our `npm` dependencies may require a compilation step. On OS X, the Xcode Command Line Tools will cover this. On Ubuntu, `apt-get install build-essential` will install the required packages. Similar commands should work on other Linux distros. Windows will require some additional steps, see the [`node-gyp` installation instructions](https://github.com/nodejs/node-gyp#installation) for details.
* You are familiar with `npm` and know whether or not you need to use `sudo` when installing packages globally.
* You are familiar with `git`.
@ -118,7 +118,7 @@ First, run `npm run build`. This will produce pre-built bundles in `build` folde
The easiest way to try your changes is to run `npm run build` and then open `fixtures/packaging/babel-standalone/dev.html`. This file already uses `react.js` from the `build` folder so it will pick up your changes.
If you want to try your changes in your existing React project, you may copy `build/umd/react.development.js`, `build/umd/react-dom.development.js`, or any other build products into your app and use them instead of the stable version. If your project uses React from npm, you may delete `react` and `react-dom` in its dependencies and use `npm link` to point them to your local `build` folder:
If you want to try your changes in your existing React project, you may copy `build/dist/react.development.js`, `build/dist/react-dom.development.js`, or any other build products into your app and use them instead of the stable version. If your project uses React from npm, you may delete `react` and `react-dom` in its dependencies and use `npm link` to point them to your local `build` folder:
@ -308,7 +308,19 @@ You can mix together different types of children, so you can use string literals
</div>
```
A React component can't return multiple React elements, but a single JSX expression can have multiple children, so if you want a component to render multiple things you can wrap it in a `div` like this.
A React component can also return an array of elements:
```js
render() {
// No need to wrap list items in an extra element!
@ -166,6 +166,7 @@ class TemperatureInput extends React.Component {
render() {
const temperature = this.state.temperature;
// ...
```
However, we want these two inputs to be in sync with each other. When we update the Celsius input, the Fahrenheit input should reflect the converted temperature, and vice versa.
@ -182,6 +183,7 @@ First, we will replace `this.state.temperature` with `this.props.temperature` in
render() {
// Before: const temperature = this.state.temperature;
const temperature = this.props.temperature;
// ...
```
We know that [props are read-only](/docs/components-and-props.html#props-are-read-only). When the `temperature` was in the local state, the `TemperatureInput` could just call `this.setState()` to change it. However, now that the `temperature` is coming from the parent as a prop, the `TemperatureInput` has no control over it.
@ -194,6 +196,7 @@ Now, when the `TemperatureInput` wants to update its temperature, it calls `this
@ -142,9 +142,9 @@ As a last resort, you can pass item's index in the array as a key. This can work
## Tradeoffs
It is important to remember that the reconciliation algorithm is an implementation detail. React could rerender the whole app on every action; the end result would be the same. We are regularly refining the heuristics in order to make common use cases faster.
It is important to remember that the reconciliation algorithm is an implementation detail. React could rerender the whole app on every action; the end result would be the same. Just to be clear, rerender in this context means calling `render` for all components, it doesn't mean React will unmount and remount them. It will only apply the differences following the rules stated in the previous sections.
In the current implementation, you can express the fact that a subtree has been moved amongst its siblings, but you cannot tell that it has moved somewhere else. The algorithm will rerender that full subtree.
We are regularly refining the heuristics in order to make common use cases faster. In the current implementation, you can express the fact that a subtree has been moved amongst its siblings, but you cannot tell that it has moved somewhere else. The algorithm will rerender that full subtree.
Because React relies on heuristics, if the assumptions behind them are not met, performance will suffer.
@ -88,6 +88,22 @@ function ComponentWithTransition() {
Style keys are camelCased in order to be consistent with accessing the properties on DOM nodes from JS (e.g. `node.style.backgroundImage`). Vendor prefixes [other than `ms`](http://www.andismith.com/blog/2012/02/modernizr-prefixed/) should begin with a capital letter. This is why `WebkitTransition` has an uppercase "W".
React will automatically append a "px" suffix to certain inline style properties. For example:
```js
// This:
<divstyle={{height:10}}>
Hello World!
</div>;
// Becomes:
<divstyle="height: 10px;">
Hello World!
</div>
```
Not all style properties are converted to pixel strings though. Certain ones remain unitless (eg `zoom`, `order`, `flex`). A complete list of unitless properties can be seen [here](https://github.com/facebook/react/blob/4131af3e4bf52f3a003537ec95a1655147c81270/src/renderers/dom/shared/CSSProperty.js#L15-L59).
### suppressContentEditableWarning
Normally, there is a warning when an element with children is also marked as `contentEditable`, because it won't work. This attribute suppresses that warning. Don't use this unless you are building a library like [Draft.js](https://facebook.github.io/draft-js/) that manages `contentEditable` manually.
> The `PureRenderMixin` mixin predates `React.PureComponent`. This reference doc is provided for legacy purposes, and you should consider using [`React.PureComponent`](/docs/react-api.html#react.purecomponent) instead.
> The `PureRenderMixin` mixin predates `React.PureComponent`. This reference doc is provided for legacy purposes, and you should consider using [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) instead.
If your React component's render function renders the same result given the same props and state, you can use this mixin for a performance boost in some cases.
@ -204,7 +204,7 @@ Returning `false` does not prevent child components from re-rendering when *thei
Currently, if `shouldComponentUpdate()` returns `false`, then [`componentWillUpdate()`](#componentwillupdate), [`render()`](#render), and [`componentDidUpdate()`](#componentdidupdate) will not be invoked. Note that in the future React may treat `shouldComponentUpdate()` as a hint rather than a strict directive, and returning `false` may still result in a re-rendering of the component.
If you determine a specific component is slow after profiling, you may change it to inherit from [`React.PureComponent`](/docs/react-api.html#react.purecomponent) which implements `shouldComponentUpdate()` with a shallow prop and state comparison. If you are confident you want to write it by hand, you may compare `this.props` with `nextProps` and `this.state` with `nextState` and return `false` to tell React the update can be skipped.
If you determine a specific component is slow after profiling, you may change it to inherit from [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) which implements `shouldComponentUpdate()` with a shallow prop and state comparison. If you are confident you want to write it by hand, you may compare `this.props` with `nextProps` and `this.state` with `nextState` and return `false` to tell React the update can be skipped.
@ -49,7 +49,9 @@ If you call [`ReactDOM.hydrate()`](/docs/react-dom.html#hydrate) on a node that
ReactDOMServer.renderToStaticMarkup(element)
```
Similar to [`renderToString`](#rendertostring), except this doesn't create extra DOM attributes such as `data-reactid`, that React uses internally. This is useful if you want to use React as a simple static page generator, as stripping away the extra attributes can save lots of bytes.
Similar to [`renderToString`](#rendertostring), except this doesn't create extra DOM attributes that React uses internally, such as `data-reactroot`. This is useful if you want to use React as a simple static page generator, as stripping away the extra attributes can save some bytes.
If you plan to use React on the client to make the markup interactive, do not use this method. Instead, use [`renderToString`](#rendertostring) on the server and [`ReactDOM.hydrate()`](/docs/react-dom.html#hydrate) on the client.
* * *
@ -59,10 +61,12 @@ Similar to [`renderToString`](#rendertostring), except this doesn't create extra
ReactDOMNodeStream.renderToNodeStream(element)
```
Render a React element to its initial HTML. Returns a [Readable stream](https://nodejs.org/api/stream.html#stream_readable_streams) that outputs an HTML string. The HTML output by this stream is exactly equal to what [`ReactDOMServer.renderToString`](#rendertostring) would return.
Render a React element to its initial HTML. Returns a [Readable stream](https://nodejs.org/api/stream.html#stream_readable_streams) that outputs an HTML string. The HTML output by this stream is exactly equal to what [`ReactDOMServer.renderToString`](#rendertostring) would return. You can use this method to generate HTML on the server and send the markup down on the initial request for faster page loads and to allow search engines to crawl your pages for SEO purposes.
If you call [`ReactDOM.hydrate()`](/docs/react-dom.html#hydrate) on a node that already has this server-rendered markup, React will preserve it and only attach event handlers, allowing you to have a very performant first-load experience.
> Note:
>
>
> Server-only. This API is not available in the browser.
>
> The stream returned from this method will return a byte stream encoded in utf-8. If you need a stream in another encoding, take a look a project like [iconv-lite](https://www.npmjs.com/package/iconv-lite), which provides transform streams for transcoding text.
@ -75,10 +79,14 @@ Render a React element to its initial HTML. Returns a [Readable stream](https://
Similar to [`renderToNodeStream`](#rendertonodestream), except this doesn't create extra DOM attributes such as `data-reactid`, that React uses internally. The HTML output by this stream is exactly equal to what [`ReactDOMServer.renderToStaticMarkup`](#rendertostaticmarkup) would return.
Similar to [`renderToNodeStream`](#rendertonodestream), except this doesn't create extra DOM attributes that React uses internally, such as `data-reactroot`. This is useful if you want to use React as a simple static page generator, as stripping away the extra attributes can save some bytes.
The HTML output by this stream is exactly equal to what [`ReactDOMServer.renderToStaticMarkup`](#rendertostaticmarkup) would return.
If you plan to use React on the client to make the markup interactive, do not use this method. Instead, use [`renderToNodeStream`](#rendertonodestream) on the server and [`ReactDOM.hydrate()`](/docs/react-dom.html#hydrate) on the client.
> Note:
>
> Server-only. This API is not available in the browser.
>
>
> The stream returned from this method will return a byte stream encoded in utf-8. If you need a stream in another encoding, take a look a project like [iconv-lite](https://www.npmjs.com/package/iconv-lite), which provides transform streams for transcoding text.
@ -176,7 +176,11 @@ Returns the total number of components in `children`, equal to the number of tim
React.Children.only(children)
```
Returns the only child in `children`. Throws otherwise.
Verifies that `children` has only one child (a React element) and returns it. Otherwise this method throws.
> Note:
>
>`React.Children.only()` does not accept the return value of [`React.Children.map()`](#reactchildrenmap) because it is an array rather than a React element.
@ -158,7 +158,7 @@ Returns the root "test instance" object that is useful for making assertions abo
testInstance.find(test)
```
Find the first descendant test instance for which `test(testInstance)` returns `true`.
Find a single descendant test instance for which `test(testInstance)` returns `true`. If `test(testInstance)` does not return `true` for exactly one test instance, it will throw an error.
### `testInstance.findByType()`
@ -166,7 +166,7 @@ Find the first descendant test instance for which `test(testInstance)` returns `
testInstance.findByType(type)
```
Find the first descendant test instance with the provided `type`.
Find a single descendant test instance with the provided `type`. If there is not exactly one test instance with the provided `type`, it will throw an error.
### `testInstance.findByProps()`
@ -174,7 +174,7 @@ Find the first descendant test instance with the provided `type`.
testInstance.findByProps(props)
```
Find the first descendant test instance with the provided `props`.
Find a single descendant test instance with the provided `props`. If there is not exactly one test instance with the provided `props`, it will throw an error.
@ -82,7 +82,7 @@ There are two types of "model" data in React: props and state. It's important to
To make your UI interactive, you need to be able to trigger changes to your underlying data model. React makes this easy with **state**.
To build your app correctly, you first need to think of the minimal set of mutable state that your app needs. The key here is DRY: *Don't Repeat Yourself*. Figure out the absolute minimal representation of the state your application needs and compute everything else you need on-demand. For example, if you're building a TODO list, just keep an array of the TODO items around; don't keep a separate state variable for the count. Instead, when you want to render the TODO count, simply take the length of the TODO items array.
To build your app correctly, you first need to think of the minimal set of mutable state that your app needs. The key here is [DRY: *Don't Repeat Yourself*](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself). Figure out the absolute minimal representation of the state your application needs and compute everything else you need on-demand. For example, if you're building a TODO list, just keep an array of the TODO items around; don't keep a separate state variable for the count. Instead, when you want to render the TODO count, simply take the length of the TODO items array.
Think of all of the pieces of data in our example application. We have:
@ -1090,7 +1090,7 @@ Check out the final result here: [Final Result](https://codepen.io/gaearon/pen/g
If you have extra time or want to practice your new skills, here are some ideas for improvements you could make, listed in order of increasing difficulty:
1. Display the move locations in the format "(1, 3)" instead of "6".
1. Display the move locations in the format "(1, 3)" in the move list.
2. Bold the currently selected item in the move list.
3. Rewrite Board to use two loops to make the squares instead of hardcoding them.
4. Add a toggle button that lets you sort the moves in either ascending or descending order.
@ -19,7 +19,7 @@ You are probably here because you got one of the following error messages:
This usually means one of two things:
- You are trying to add a `ref` to an element that is being created outside of a component's render() function.
- You have multiple (conflicting) copies of React loaded (eg. due to a misconfigured NPM dependency)
- You have multiple (conflicting) copies of React loaded (eg. due to a misconfigured npm dependency)
## Invalid Refs
@ -28,6 +28,6 @@ Only a ReactOwner can have refs. This usually means that you're trying to add a
## Multiple copies of React
Bower does a good job of deduplicating dependencies, but NPM does not. If you aren't doing anything (fancy) with refs, there is a good chance that the problem is not with your refs, but rather an issue with having multiple copies of React loaded into your project. Sometimes, when you pull in a third-party module via npm, you will get a duplicate copy of the dependency library, and this can create problems.
Bower does a good job of deduplicating dependencies, but npm does not. If you aren't doing anything (fancy) with refs, there is a good chance that the problem is not with your refs, but rather an issue with having multiple copies of React loaded into your project. Sometimes, when you pull in a third-party module via npm, you will get a duplicate copy of the dependency library, and this can create problems.
If you are using npm... `npm ls` or `npm ls react` might help illuminate.
renanpvaz
7 years ago