diff --git a/accessibility.md b/accessibility.md
new file mode 100644
index 000000000..6e75e34e6
--- /dev/null
+++ b/accessibility.md
@@ -0,0 +1,519 @@
+---
+id: accessibility
+title: Accessibility
+permalink: docs/accessibility.html
+---
+
+## Why Accessibility? {#why-accessibility}
+
+Web accessibility (also referred to as [**a11y**](https://en.wiktionary.org/wiki/a11y)) is the design and creation of websites that can be used by everyone. Accessibility support is necessary to allow assistive technology to interpret web pages.
+
+React fully supports building accessible websites, often by using standard HTML techniques.
+
+## Standards and Guidelines {#standards-and-guidelines}
+
+### WCAG {#wcag}
+
+The [Web Content Accessibility Guidelines](https://www.w3.org/WAI/intro/wcag) provides guidelines for creating accessible web sites.
+
+The following WCAG checklists provide an overview:
+
+- [WCAG checklist from Wuhcag](https://www.wuhcag.com/wcag-checklist/)
+- [WCAG checklist from WebAIM](https://webaim.org/standards/wcag/checklist)
+- [Checklist from The A11Y Project](https://a11yproject.com/checklist.html)
+
+### WAI-ARIA {#wai-aria}
+
+The [Web Accessibility Initiative - Accessible Rich Internet Applications](https://www.w3.org/WAI/intro/aria) document contains techniques for building fully accessible JavaScript widgets.
+
+Note that all `aria-*` HTML attributes are fully supported in JSX. Whereas most DOM properties and attributes in React are camelCased, these attributes should be hyphen-cased (also known as kebab-case, lisp-case, etc) as they are in plain HTML:
+
+```javascript{3,4}
+<input
+  type="text"
+  aria-label={labelText}
+  aria-required="true"
+  onChange={onchangeHandler}
+  value={inputValue}
+  name="name"
+/>
+```
+
+## Semantic HTML {#semantic-html}
+Semantic HTML is the foundation of accessibility in a web application. Using the various HTML elements to reinforce the meaning of information
+in our websites will often give us accessibility for free.
+
+- [MDN HTML elements reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element)
+
+Sometimes we break HTML semantics when we add `<div>` elements to our JSX to make our React code work, especially when working with lists (`<ol>`, `<ul>` and `<dl>`) and the HTML `<table>`.
+In these cases we should rather use [React Fragments](/docs/fragments.html) to group together multiple elements.
+
+For example,
+
+```javascript{1,5,8}
+import React, { Fragment } from 'react';
+
+function ListItem({ item }) {
+  return (
+    <Fragment>
+      <dt>{item.term}</dt>
+      <dd>{item.description}</dd>
+    </Fragment>
+  );
+}
+
+function Glossary(props) {
+  return (
+    <dl>
+      {props.items.map(item => (
+        <ListItem item={item} key={item.id} />
+      ))}
+    </dl>
+  );
+}
+```
+
+You can map a collection of items to an array of fragments as you would any other type of element as well:
+
+```javascript{6,9}
+function Glossary(props) {
+  return (
+    <dl>
+      {props.items.map(item => (
+        // Fragments should also have a `key` prop when mapping collections
+        <Fragment key={item.id}>
+          <dt>{item.term}</dt>
+          <dd>{item.description}</dd>
+        </Fragment>
+      ))}
+    </dl>
+  );
+}
+```
+
+When you don't need any props on the Fragment tag you can use the [short syntax](/docs/fragments.html#short-syntax), if your tooling supports it:
+
+```javascript{3,6}
+function ListItem({ item }) {
+  return (
+    <>
+      <dt>{item.term}</dt>
+      <dd>{item.description}</dd>
+    </>
+  );
+}
+```
+
+For more info, see [the Fragments documentation](/docs/fragments.html).
+
+## Accessible Forms {#accessible-forms}
+
+### Labeling {#labeling}
+Every HTML form control, such as `<input>` and `<textarea>`, needs to be labeled accessibly. We need to provide descriptive labels that are also exposed to screen readers.
+
+The following resources show us how to do this:
+
+- [The W3C shows us how to label elements](https://www.w3.org/WAI/tutorials/forms/labels/)
+- [WebAIM shows us how to label elements](https://webaim.org/techniques/forms/controls)
+- [The Paciello Group explains accessible names](https://www.paciellogroup.com/blog/2017/04/what-is-an-accessible-name/)
+
+Although these standard HTML practices can be directly used in React, note that the `for` attribute is written as `htmlFor` in JSX:
+
+```javascript{1}
+<label htmlFor="namedInput">Name:</label>
+<input id="namedInput" type="text" name="name"/>
+```
+
+### Notifying the user of errors {#notifying-the-user-of-errors}
+
+Error situations need to be understood by all users. The following link shows us how to expose error texts to screen readers as well:
+
+- [The W3C demonstrates user notifications](https://www.w3.org/WAI/tutorials/forms/notifications/)
+- [WebAIM looks at form validation](https://webaim.org/techniques/formvalidation/)
+
+## Focus Control {#focus-control}
+
+Ensure that your web application can be fully operated with the keyboard only:
+
+- [WebAIM talks about keyboard accessibility](https://webaim.org/techniques/keyboard/)
+
+### Keyboard focus and focus outline {#keyboard-focus-and-focus-outline}
+
+Keyboard focus refers to the current element in the DOM that is selected to accept input from the keyboard. We see it everywhere as a focus outline similar to that shown in the following image:
+
+<img src="../images/docs/keyboard-focus.png" alt="Blue keyboard focus outline around a selected link." />
+
+Only ever use CSS that removes this outline, for example by setting `outline: 0`, if you are replacing it with another focus outline implementation.
+
+### Mechanisms to skip to desired content {#mechanisms-to-skip-to-desired-content}
+
+Provide a mechanism to allow users to skip past navigation sections in your application as this assists and speeds up keyboard navigation.
+
+Skiplinks or Skip Navigation Links are hidden navigation links that only become visible when keyboard users interact with the page. They are very easy to implement with internal page anchors and some styling:
+
+- [WebAIM - Skip Navigation Links](https://webaim.org/techniques/skipnav/)
+
+Also use landmark elements and roles, such as `<main>` and `<aside>`, to demarcate page regions as assistive technology allow the user to quickly navigate to these sections.
+
+Read more about the use of these elements to enhance accessibility here:
+
+- [Accessible Landmarks](https://www.scottohara.me/blog/2018/03/03/landmarks.html)
+
+### Programmatically managing focus {#programmatically-managing-focus}
+
+Our React applications continuously modify the HTML DOM during runtime, sometimes leading to keyboard focus being lost or set to an unexpected element. In order to repair this, we need to programmatically nudge the keyboard focus in the right direction. For example, by resetting keyboard focus to a button that opened a modal window after that modal window is closed.
+
+MDN Web Docs takes a look at this and describes how we can build [keyboard-navigable JavaScript widgets](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets).
+
+To set focus in React, we can use [Refs to DOM elements](/docs/refs-and-the-dom.html).
+
+Using this, we first create a ref to an element in the JSX of a component class:
+
+```javascript{4-5,8-9,13}
+class CustomTextInput extends React.Component {
+  constructor(props) {
+    super(props);
+    // Create a ref to store the textInput DOM element
+    this.textInput = React.createRef();
+  }
+  render() {
+  // Use the `ref` callback to store a reference to the text input DOM
+  // element in an instance field (for example, this.textInput).
+    return (
+      <input
+        type="text"
+        ref={this.textInput}
+      />
+    );
+  }
+}
+```
+
+Then we can focus it elsewhere in our component when needed:
+
+ ```javascript
+ focus() {
+   // Explicitly focus the text input using the raw DOM API
+   // Note: we're accessing "current" to get the DOM node
+   this.textInput.current.focus();
+ }
+ ```
+
+Sometimes a parent component needs to set focus to an element in a child component. We can do this by [exposing DOM refs to parent components](/docs/refs-and-the-dom.html#exposing-dom-refs-to-parent-components) through a special prop on the child component that forwards the parent's ref to the child's DOM node.
+
+```javascript{4,12,16}
+function CustomTextInput(props) {
+  return (
+    <div>
+      <input ref={props.inputRef} />
+    </div>
+  );
+}
+
+class Parent extends React.Component {
+  constructor(props) {
+    super(props);
+    this.inputElement = React.createRef();
+  }
+  render() {
+    return (
+      <CustomTextInput inputRef={this.inputElement} />
+    );
+  }
+}
+
+// Now you can set focus when required.
+this.inputElement.current.focus();
+```
+
+When using a HOC to extend components, it is recommended to [forward the ref](/docs/forwarding-refs.html) to the wrapped component using the `forwardRef` function of React. If a third party HOC does not implement ref forwarding, the above pattern can still be used as a fallback.
+
+A great focus management example is the [react-aria-modal](https://github.com/davidtheclark/react-aria-modal). This is a relatively rare example of a fully accessible modal window. Not only does it set initial focus on
+the cancel button (preventing the keyboard user from accidentally activating the success action) and trap keyboard focus inside the modal, it also resets focus back to the element that initially triggered the modal.
+
+>Note:
+>
+>While this is a very important accessibility feature, it is also a technique that should be used judiciously. Use it to repair the keyboard focus flow when it is disturbed, not to try and anticipate how
+>users want to use applications.
+
+## Mouse and pointer events {#mouse-and-pointer-events}
+
+Ensure that all functionality exposed through a mouse or pointer event can also be accessed using the keyboard alone. Depending only on the pointer device will lead to many cases where keyboard users cannot use your application.
+
+To illustrate this, let's look at a prolific example of broken accessibility caused by click events. This is the outside click pattern, where a user can disable an opened popover by clicking outside the element.
+
+<img src="../images/docs/outerclick-with-mouse.gif" alt="A toggle button opening a popover list implemented with the click outside pattern and operated with a mouse showing that the close action works." />
+
+This is typically implemented by attaching a `click` event to the `window` object that closes the popover:
+
+```javascript{12-14,26-30}
+class OuterClickExample extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.state = { isOpen: false };
+    this.toggleContainer = React.createRef();
+
+    this.onClickHandler = this.onClickHandler.bind(this);
+    this.onClickOutsideHandler = this.onClickOutsideHandler.bind(this);
+  }
+
+  componentDidMount() {
+    window.addEventListener('click', this.onClickOutsideHandler);
+  }
+
+  componentWillUnmount() {
+    window.removeEventListener('click', this.onClickOutsideHandler);
+  }
+
+  onClickHandler() {
+    this.setState(currentState => ({
+      isOpen: !currentState.isOpen
+    }));
+  }
+
+  onClickOutsideHandler(event) {
+    if (this.state.isOpen && !this.toggleContainer.current.contains(event.target)) {
+      this.setState({ isOpen: false });
+    }
+  }
+
+  render() {
+    return (
+      <div ref={this.toggleContainer}>
+        <button onClick={this.onClickHandler}>Select an option</button>
+        {this.state.isOpen && (
+          <ul>
+            <li>Option 1</li>
+            <li>Option 2</li>
+            <li>Option 3</li>
+          </ul>
+        )}
+      </div>
+    );
+  }
+}
+```
+
+This may work fine for users with pointer devices, such as a mouse, but operating this with the keyboard alone leads to broken functionality when tabbing to the next element as the `window` object never receives a `click` event. This can lead to obscured functionality which blocks users from using your application.
+
+<img src="../images/docs/outerclick-with-keyboard.gif" alt="A toggle button opening a popover list implemented with the click outside pattern and operated with the keyboard showing the popover not being closed on blur and it obscuring other screen elements." />
+
+The same functionality can be achieved by using appropriate event handlers instead, such as `onBlur` and `onFocus`:
+
+```javascript{19-29,31-34,37-38,40-41}
+class BlurExample extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.state = { isOpen: false };
+    this.timeOutId = null;
+
+    this.onClickHandler = this.onClickHandler.bind(this);
+    this.onBlurHandler = this.onBlurHandler.bind(this);
+    this.onFocusHandler = this.onFocusHandler.bind(this);
+  }
+
+  onClickHandler() {
+    this.setState(currentState => ({
+      isOpen: !currentState.isOpen
+    }));
+  }
+
+  // We close the popover on the next tick by using setTimeout.
+  // This is necessary because we need to first check if
+  // another child of the element has received focus as
+  // the blur event fires prior to the new focus event.
+  onBlurHandler() {
+    this.timeOutId = setTimeout(() => {
+      this.setState({
+        isOpen: false
+      });
+    });
+  }
+
+  // If a child receives focus, do not close the popover.
+  onFocusHandler() {
+    clearTimeout(this.timeOutId);
+  }
+
+  render() {
+    // React assists us by bubbling the blur and
+    // focus events to the parent.
+    return (
+      <div onBlur={this.onBlurHandler}
+           onFocus={this.onFocusHandler}>
+        <button onClick={this.onClickHandler}
+                aria-haspopup="true"
+                aria-expanded={this.state.isOpen}>
+          Select an option
+        </button>
+        {this.state.isOpen && (
+          <ul>
+            <li>Option 1</li>
+            <li>Option 2</li>
+            <li>Option 3</li>
+          </ul>
+        )}
+      </div>
+    );
+  }
+}
+```
+
+This code exposes the functionality to both pointer device and keyboard users. Also note the added `aria-*` props to support screen-reader users. For simplicity's sake the keyboard events to enable `arrow key` interaction of the popover options have not been implemented.
+
+<img src="../images/docs/blur-popover-close.gif" alt="A popover list correctly closing for both mouse and keyboard users." />
+
+This is one example of many cases where depending on only pointer and mouse events will break functionality for keyboard users. Always testing with the keyboard will immediately highlight the problem areas which can then be fixed by using keyboard aware event handlers.
+
+## More Complex Widgets {#more-complex-widgets}
+
+A more complex user experience should not mean a less accessible one. Whereas accessibility is most easily achieved by coding as close to HTML as possible, even the most complex widget can be coded accessibly.
+
+Here we require knowledge of [ARIA Roles](https://www.w3.org/TR/wai-aria/#roles) as well as [ARIA States and Properties](https://www.w3.org/TR/wai-aria/#states_and_properties).
+These are toolboxes filled with HTML attributes that are fully supported in JSX and enable us to construct fully accessible, highly functional React components.
+
+Each type of widget has a specific design pattern and is expected to function in a certain way by users and user agents alike:
+
+- [WAI-ARIA Authoring Practices - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices/#aria_ex)
+- [Heydon Pickering - ARIA Examples](https://heydonworks.com/practical_aria_examples/)
+- [Inclusive Components](https://inclusive-components.design/)
+
+## Other Points for Consideration {#other-points-for-consideration}
+
+### Setting the language {#setting-the-language}
+
+Indicate the human language of page texts as screen reader software uses this to select the correct voice settings:
+
+- [WebAIM - Document Language](https://webaim.org/techniques/screenreader/#language)
+
+### Setting the document title {#setting-the-document-title}
+
+Set the document `<title>` to correctly describe the current page content as this ensures that the user remains aware of the current page context:
+
+- [WCAG - Understanding the Document Title Requirement](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-title.html)
+
+We can set this in React using the [React Document Title Component](https://github.com/gaearon/react-document-title).
+
+### Color contrast {#color-contrast}
+
+Ensure that all readable text on your website has sufficient color contrast to remain maximally readable by users with low vision:
+
+- [WCAG - Understanding the Color Contrast Requirement](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html)
+- [Everything About Color Contrast And Why You Should Rethink It](https://www.smashingmagazine.com/2014/10/color-contrast-tips-and-tools-for-accessibility/)
+- [A11yProject - What is Color Contrast](https://a11yproject.com/posts/what-is-color-contrast/)
+
+It can be tedious to manually calculate the proper color combinations for all cases in your website so instead, you can [calculate an entire accessible color palette with Colorable](https://jxnblk.com/colorable/).
+
+Both the aXe and WAVE tools mentioned below also include color contrast tests and will report on contrast errors.
+
+If you want to extend your contrast testing abilities you can use these tools:
+
+- [WebAIM - Color Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- [The Paciello Group - Color Contrast Analyzer](https://www.paciellogroup.com/resources/contrastanalyser/)
+
+## Development and Testing Tools {#development-and-testing-tools}
+
+There are a number of tools we can use to assist in the creation of accessible web applications.
+
+### The keyboard {#the-keyboard}
+
+By far the easiest and also one of the most important checks is to test if your entire website can be reached and used with the keyboard alone. Do this by:
+
+1. Disconnecting your mouse.
+1. Using `Tab` and `Shift+Tab` to browse.
+1. Using `Enter` to activate elements.
+1. Where required, using your keyboard arrow keys to interact with some elements, such as menus and dropdowns.
+
+### Development assistance {#development-assistance}
+
+We can check some accessibility features directly in our JSX code. Often intellisense checks are already provided in JSX aware IDE's for the ARIA roles, states and properties. We also have access to the following tool:
+
+#### eslint-plugin-jsx-a11y {#eslint-plugin-jsx-a11y}
+
+The [eslint-plugin-jsx-a11y](https://github.com/evcohen/eslint-plugin-jsx-a11y) plugin for ESLint provides AST linting feedback regarding accessibility issues in your JSX. Many IDE's allow you to integrate these findings directly into code analysis and source code windows.
+
+[Create React App](https://github.com/facebookincubator/create-react-app) has this plugin with a subset of rules activated. If you want to enable even more accessibility rules, you can create an `.eslintrc` file in the root of your project with this content:
+
+  ```json
+  {
+    "extends": ["react-app", "plugin:jsx-a11y/recommended"],
+    "plugins": ["jsx-a11y"]
+  }
+  ```
+
+### Testing accessibility in the browser {#testing-accessibility-in-the-browser}
+
+A number of tools exist that can run accessibility audits on web pages in your browser. Please use them in combination with other accessibility checks mentioned here as they can only
+test the technical accessibility of your HTML.
+
+#### aXe, aXe-core and react-axe {#axe-axe-core-and-react-axe}
+
+Deque Systems offers [aXe-core](https://github.com/dequelabs/axe-core) for automated and end-to-end accessibility tests of your applications. This module includes integrations for Selenium.
+
+[The Accessibility Engine](https://www.deque.com/products/axe/) or aXe, is an accessibility inspector browser extension built on `aXe-core`.
+
+You can also use the [react-axe](https://github.com/dylanb/react-axe) module to report these accessibility findings directly to the console while developing and debugging.
+
+#### WebAIM WAVE {#webaim-wave}
+
+The [Web Accessibility Evaluation Tool](https://wave.webaim.org/extension/) is another accessibility browser extension.
+
+#### Accessibility inspectors and the Accessibility Tree {#accessibility-inspectors-and-the-accessibility-tree}
+
+[The Accessibility Tree](https://www.paciellogroup.com/blog/2015/01/the-browser-accessibility-tree/) is a subset of the DOM tree that contains accessible objects for every DOM element that should be exposed
+to assistive technology, such as screen readers.
+
+In some browsers we can easily view the accessibility information for each element in the accessibility tree:
+
+- [Using the Accessibility Inspector in Firefox](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector)
+- [Using the Accessibility Inspector in Chrome](https://developers.google.com/web/tools/chrome-devtools/accessibility/reference#pane)
+- [Using the Accessibility Inspector in OS X Safari](https://developer.apple.com/library/content/documentation/Accessibility/Conceptual/AccessibilityMacOSX/OSXAXTestingApps.html)
+
+### Screen readers {#screen-readers}
+
+Testing with a screen reader should form part of your accessibility tests.
+
+Please note that browser / screen reader combinations matter. It is recommended that you test your application in the browser best suited to your screen reader of choice.
+
+### Commonly Used Screen Readers {#commonly-used-screen-readers}
+
+#### NVDA in Firefox {#nvda-in-firefox}
+
+[NonVisual Desktop Access](https://www.nvaccess.org/) or NVDA is an open source Windows screen reader that is widely used.
+
+Refer to the following guides on how to best use NVDA:
+
+- [WebAIM - Using NVDA to Evaluate Web Accessibility](https://webaim.org/articles/nvda/)
+- [Deque - NVDA Keyboard Shortcuts](https://dequeuniversity.com/screenreaders/nvda-keyboard-shortcuts)
+
+#### VoiceOver in Safari {#voiceover-in-safari}
+
+VoiceOver is an integrated screen reader on Apple devices.
+
+Refer to the following guides on how activate and use VoiceOver:
+
+- [WebAIM - Using VoiceOver to Evaluate Web Accessibility](https://webaim.org/articles/voiceover/)
+- [Deque - VoiceOver for OS X Keyboard Shortcuts](https://dequeuniversity.com/screenreaders/voiceover-keyboard-shortcuts)
+- [Deque - VoiceOver for iOS Shortcuts](https://dequeuniversity.com/screenreaders/voiceover-ios-shortcuts)
+
+#### JAWS in Internet Explorer {#jaws-in-internet-explorer}
+
+[Job Access With Speech](https://www.freedomscientific.com/Products/software/JAWS/) or JAWS, is a prolifically used screen reader on Windows.
+
+Refer to the following guides on how to best use JAWS:
+
+- [WebAIM - Using JAWS to Evaluate Web Accessibility](https://webaim.org/articles/jaws/)
+- [Deque - JAWS Keyboard Shortcuts](https://dequeuniversity.com/screenreaders/jaws-keyboard-shortcuts)
+
+### Other Screen Readers {#other-screen-readers}
+
+#### ChromeVox in Google Chrome {#chromevox-in-google-chrome}
+
+[ChromeVox](https://www.chromevox.com/) is an integrated screen reader on Chromebooks and is available [as an extension](https://chrome.google.com/webstore/detail/chromevox/kgejglhpjiefppelpmljglcjbhoiplfn?hl=en) for Google Chrome.
+
+Refer to the following guides on how best to use ChromeVox:
+
+- [Google Chromebook Help - Use the Built-in Screen Reader](https://support.google.com/chromebook/answer/7031755?hl=en)
+- [ChromeVox Classic Keyboard Shortcuts Reference](https://www.chromevox.com/keyboard_shortcuts.html)
diff --git a/add-react-to-a-website.md b/add-react-to-a-website.md
new file mode 100644
index 000000000..a03d0e8a5
--- /dev/null
+++ b/add-react-to-a-website.md
@@ -0,0 +1,202 @@
+---
+id: add-react-to-a-website
+title: Add React to a Website
+permalink: docs/add-react-to-a-website.html
+redirect_from:
+  - "docs/add-react-to-an-existing-app.html"
+prev: getting-started.html
+next: create-a-new-react-app.html
+---
+
+Use as little or as much React as you need.
+
+React has been designed from the start for gradual adoption, and **you can use as little or as much React as you need**. Perhaps you only want to add some "sprinkles of interactivity" to an existing page. React components are a great way to do that.
+
+The majority of websites aren't, and don't need to be, single-page apps. With **a few lines of code and no build tooling**, try React in a small part of your website. You can then either gradually expand its presence, or keep it contained to a few dynamic widgets.
+
+---
+
+- [Add React in One Minute](#add-react-in-one-minute)
+- [Optional: Try React with JSX](#optional-try-react-with-jsx) (no bundler necessary!)
+
+## Add React in One Minute {#add-react-in-one-minute}
+
+In this section, we will show how to add a React component to an existing HTML page. You can follow along with your own website, or create an empty HTML file to practice.
+
+There will be no complicated tools or install requirements -- **to complete this section, you only need an internet connection, and a minute of your time.**
+
+Optional: [Download the full example (2KB zipped)](https://gist.github.com/gaearon/6668a1f6986742109c00a581ce704605/archive/f6c882b6ae18bde42dcf6fdb751aae93495a2275.zip)
+
+### Step 1: Add a DOM Container to the HTML {#step-1-add-a-dom-container-to-the-html}
+
+First, open the HTML page you want to edit. Add an empty `<div>` tag to mark the spot where you want to display something with React. For example:
+
+```html{3}
+<!-- ... existing HTML ... -->
+
+<div id="like_button_container"></div>
+
+<!-- ... existing HTML ... -->
+```
+
+We gave this `<div>` a unique `id` HTML attribute. This will allow us to find it from the JavaScript code later and display a React component inside of it.
+
+>Tip
+>
+>You can place a "container" `<div>` like this **anywhere** inside the `<body>` tag. You may have as many independent DOM containers on one page as you need. They are usually empty -- React will replace any existing content inside DOM containers.
+
+### Step 2: Add the Script Tags {#step-2-add-the-script-tags}
+
+Next, add three `<script>` tags to the HTML page right before the closing `</body>` tag:
+
+```html{5,6,9}
+  <!-- ... other HTML ... -->
+
+  <!-- Load React. -->
+  <!-- Note: when deploying, replace "development.js" with "production.min.js". -->
+  <script src="https://unpkg.com/react@16/umd/react.development.js" crossorigin></script>
+  <script src="https://unpkg.com/react-dom@16/umd/react-dom.development.js" crossorigin></script>
+
+  <!-- Load our React component. -->
+  <script src="like_button.js"></script>
+
+</body>
+```
+
+The first two tags load React. The third one will load your component code.
+
+### Step 3: Create a React Component {#step-3-create-a-react-component}
+
+Create a file called `like_button.js` next to your HTML page.
+
+Open **[this starter code](https://gist.github.com/gaearon/0b180827c190fe4fd98b4c7f570ea4a8/raw/b9157ce933c79a4559d2aa9ff3372668cce48de7/LikeButton.js)** and paste it into the file you created.
+
+>Tip
+>
+>This code defines a React component called `LikeButton`. Don't worry if you don't understand it yet -- we'll cover the building blocks of React later in our [hands-on tutorial](/tutorial/tutorial.html) and [main concepts guide](/docs/hello-world.html). For now, let's just get it showing on the screen!
+
+After **[the starter code](https://gist.github.com/gaearon/0b180827c190fe4fd98b4c7f570ea4a8/raw/b9157ce933c79a4559d2aa9ff3372668cce48de7/LikeButton.js)**, add two lines to the bottom of `like_button.js`:
+
+```js{3,4}
+// ... the starter code you pasted ...
+
+const domContainer = document.querySelector('#like_button_container');
+ReactDOM.render(e(LikeButton), domContainer);
+```
+
+These two lines of code find the `<div>` we added to our HTML in the first step, and then display our "Like" button React component inside of it. 
+
+### That's It! {#thats-it}
+
+There is no step four. **You have just added the first React component to your website.**
+
+Check out the next sections for more tips on integrating React.
+
+**[View the full example source code](https://gist.github.com/gaearon/6668a1f6986742109c00a581ce704605)**
+
+**[Download the full example (2KB zipped)](https://gist.github.com/gaearon/6668a1f6986742109c00a581ce704605/archive/f6c882b6ae18bde42dcf6fdb751aae93495a2275.zip)**
+
+### Tip: Reuse a Component {#tip-reuse-a-component}
+
+Commonly, you might want to display React components in multiple places on the HTML page. Here is an example that displays the "Like" button three times and passes some data to it:
+
+[View the full example source code](https://gist.github.com/gaearon/faa67b76a6c47adbab04f739cba7ceda)
+
+[Download the full example (2KB zipped)](https://gist.github.com/gaearon/faa67b76a6c47adbab04f739cba7ceda/archive/9d0dd0ee941fea05fd1357502e5aa348abb84c12.zip)
+
+>Note
+>
+>This strategy is mostly useful while React-powered parts of the page are isolated from each other. Inside React code, it's easier to use [component composition](/docs/components-and-props.html#composing-components) instead.
+
+### Tip: Minify JavaScript for Production {#tip-minify-javascript-for-production}
+
+Before deploying your website to production, be mindful that unminified JavaScript can significantly slow down the page for your users.
+
+If you already minify the application scripts, **your site will be production-ready** if you ensure that the deployed HTML loads the versions of React ending in `production.min.js`:
+
+```js
+<script src="https://unpkg.com/react@16/umd/react.production.min.js" crossorigin></script>
+<script src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js" crossorigin></script>
+```
+
+If you don't have a minification step for your scripts, [here's one way to set it up](https://gist.github.com/gaearon/42a2ffa41b8319948f9be4076286e1f3).
+
+## Optional: Try React with JSX {#optional-try-react-with-jsx}
+
+In the examples above, we only relied on features that are natively supported by the browsers. This is why we used a JavaScript function call to tell React what to display:
+
+```js
+const e = React.createElement;
+
+// Display a "Like" <button>
+return e(
+  'button',
+  { onClick: () => this.setState({ liked: true }) },
+  'Like'
+);
+```
+
+However, React also offers an option to use [JSX](/docs/introducing-jsx.html) instead:
+
+```js
+// Display a "Like" <button>
+return (
+  <button onClick={() => this.setState({ liked: true })}>
+    Like
+  </button>
+);
+```
+
+These two code snippets are equivalent. While **JSX is [completely optional](/docs/react-without-jsx.html)**, many people find it helpful for writing UI code -- both with React and with other libraries.
+
+You can play with JSX using [this online converter](https://babeljs.io/en/repl#?babili=false&browsers=&build=&builtIns=false&spec=false&loose=false&code_lz=DwIwrgLhD2B2AEcDCAbAlgYwNYF4DeAFAJTw4B88EAFmgM4B0tAphAMoQCGETBe86WJgBMAXJQBOYJvAC-RGWQBQ8FfAAyaQYuAB6cFDhkgA&debug=false&forceAllTransforms=false&shippedProposals=false&circleciRepo=&evaluate=false&fileSize=false&timeTravel=false&sourceType=module&lineWrap=true&presets=es2015%2Creact%2Cstage-2&prettier=false&targets=&version=7.4.3).
+
+### Quickly Try JSX {#quickly-try-jsx}
+
+The quickest way to try JSX in your project is to add this `<script>` tag to your page:
+
+```html
+<script src="https://unpkg.com/babel-standalone@6/babel.min.js"></script>
+```
+
+Now you can use JSX in any `<script>` tag by adding `type="text/babel"` attribute to it. Here is [an example HTML file with JSX](https://raw.githubusercontent.com/reactjs/reactjs.org/master/static/html/single-file-example.html) that you can download and play with.
+
+This approach is fine for learning and creating simple demos. However, it makes your website slow and **isn't suitable for production**. When you're ready to move forward, remove this new `<script>` tag and the `type="text/babel"` attributes you've added. Instead, in the next section you will set up a JSX preprocessor to convert all your `<script>` tags automatically.
+
+### Add JSX to a Project {#add-jsx-to-a-project}
+
+Adding JSX to a project doesn't require complicated tools like a bundler or a development server. Essentially, adding JSX **is a lot like adding a CSS preprocessor.** The only requirement is to have [Node.js](https://nodejs.org/) installed on your computer.
+
+Go to your project folder in the terminal, and paste these two commands:
+
+1. **Step 1:** Run `npm init -y` (if it fails, [here's a fix](https://gist.github.com/gaearon/246f6380610e262f8a648e3e51cad40d))
+2. **Step 2:** Run `npm install babel-cli@6 babel-preset-react-app@3`
+
+>Tip
+>
+>We're **using npm here only to install the JSX preprocessor;** you won't need it for anything else. Both React and the application code can stay as `<script>` tags with no changes.
+
+Congratulations! You just added a **production-ready JSX setup** to your project.
+
+
+### Run JSX Preprocessor {#run-jsx-preprocessor}
+
+Create a folder called `src` and run this terminal command:
+
+```
+npx babel --watch src --out-dir . --presets react-app/prod 
+```
+
+>Note
+>
+>`npx` is not a typo -- it's a [package runner tool that comes with npm 5.2+](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b).
+>
+>If you see an error message saying "You have mistakenly installed the `babel` package", you might have missed [the previous step](#add-jsx-to-a-project). Perform it in the same folder, and then try again.
+
+Don't wait for it to finish -- this command starts an automated watcher for JSX.
+
+If you now create a file called `src/like_button.js` with this **[JSX starter code](https://gist.github.com/gaearon/c8e112dc74ac44aac4f673f2c39d19d1/raw/09b951c86c1bf1116af741fa4664511f2f179f0a/like_button.js)**, the watcher will create a preprocessed `like_button.js` with the plain JavaScript code suitable for the browser. When you edit the source file with JSX, the transform will re-run automatically.
+
+As a bonus, this also lets you use modern JavaScript syntax features like classes without worrying about breaking older browsers. The tool we just used is called Babel, and you can learn more about it from [its documentation](https://babeljs.io/docs/en/babel-cli/).
+
+If you notice that you're getting comfortable with build tools and want them to do more for you, [the next section](/docs/create-a-new-react-app.html) describes some of the most popular and approachable toolchains. If not -- those script tags will do just fine!
diff --git a/addons-animation.md b/addons-animation.md
new file mode 100644
index 000000000..a619af76e
--- /dev/null
+++ b/addons-animation.md
@@ -0,0 +1,349 @@
+---
+id: animation
+title: Animation Add-Ons
+permalink: docs/animation.html
+layout: docs
+category: Add-Ons
+redirect_from:
+  - "docs/animation-ja-JP.html"
+  - "docs/animation-ko-KR.html"
+  - "docs/animation-zh-CN.html"
+---
+
+> Note:
+>
+> `ReactTransitionGroup` and `ReactCSSTransitionGroup` have been moved to the [`react-transition-group`](https://github.com/reactjs/react-transition-group/tree/v1-stable) package that is maintained by the community. Its 1.x branch is completely API-compatible with the existing addons. Please file bugs and feature requests in the [new repository](https://github.com/reactjs/react-transition-group/tree/v1-stable).
+
+The [`ReactTransitionGroup`](#low-level-api-reacttransitiongroup) add-on component is a low-level API for animation, and [`ReactCSSTransitionGroup`](#high-level-api-reactcsstransitiongroup) is an add-on component for easily implementing basic CSS animations and transitions.
+
+## High-level API: ReactCSSTransitionGroup {#high-level-api-reactcsstransitiongroup}
+
+`ReactCSSTransitionGroup` is a high-level API based on [`ReactTransitionGroup`](#low-level-api-reacttransitiongroup) and is an easy way to perform CSS transitions and animations when a React component enters or leaves the DOM. It's inspired by the excellent [ng-animate](https://docs.angularjs.org/api/ngAnimate) library.
+
+**Importing**
+
+```javascript
+import ReactCSSTransitionGroup from 'react-addons-css-transition-group'; // ES6
+var ReactCSSTransitionGroup = require('react-addons-css-transition-group'); // ES5 with npm
+```
+
+```javascript{31-36}
+class TodoList extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {items: ['hello', 'world', 'click', 'me']};
+    this.handleAdd = this.handleAdd.bind(this);
+  }
+
+  handleAdd() {
+    const newItems = this.state.items.concat([
+      prompt('Enter some text')
+    ]);
+    this.setState({items: newItems});
+  }
+
+  handleRemove(i) {
+    let newItems = this.state.items.slice();
+    newItems.splice(i, 1);
+    this.setState({items: newItems});
+  }
+
+  render() {
+    const items = this.state.items.map((item, i) => (
+      <div key={item} onClick={() => this.handleRemove(i)}>
+        {item}
+      </div>
+    ));
+
+    return (
+      <div>
+        <button onClick={this.handleAdd}>Add Item</button>
+        <ReactCSSTransitionGroup
+          transitionName="example"
+          transitionEnterTimeout={500}
+          transitionLeaveTimeout={300}>
+          {items}
+        </ReactCSSTransitionGroup>
+      </div>
+    );
+  }
+}
+```
+
+> Note:
+>
+> You must provide [the `key` attribute](/docs/lists-and-keys.html#keys) for all children of `ReactCSSTransitionGroup`, even when only rendering a single item. This is how React will determine which children have entered, left, or stayed.
+
+In this component, when a new item is added to `ReactCSSTransitionGroup` it will get the `example-enter` CSS class and the `example-enter-active` CSS class added in the next tick. This is a convention based on the `transitionName` prop.
+
+You can use these classes to trigger a CSS animation or transition. For example, try adding this CSS and adding a new list item:
+
+```css
+.example-enter {
+  opacity: 0.01;
+}
+
+.example-enter.example-enter-active {
+  opacity: 1;
+  transition: opacity 500ms ease-in;
+}
+
+.example-leave {
+  opacity: 1;
+}
+
+.example-leave.example-leave-active {
+  opacity: 0.01;
+  transition: opacity 300ms ease-in;
+}
+```
+
+You'll notice that animation durations need to be specified in both the CSS and the render method; this tells React when to remove the animation classes from the element and -- if it's leaving -- when to remove the element from the DOM.
+
+### Animate Initial Mounting {#animate-initial-mounting}
+
+`ReactCSSTransitionGroup` provides the optional prop `transitionAppear`, to add an extra transition phase at the initial mount of the component. There is generally no transition phase at the initial mount as the default value of `transitionAppear` is `false`. The following is an example which passes the prop `transitionAppear` with the value `true`.
+
+```javascript{5-6}
+render() {
+  return (
+    <ReactCSSTransitionGroup
+      transitionName="example"
+      transitionAppear={true}
+      transitionAppearTimeout={500}
+      transitionEnter={false}
+      transitionLeave={false}>
+      <h1>Fading at Initial Mount</h1>
+    </ReactCSSTransitionGroup>
+  );
+}
+```
+
+During the initial mount `ReactCSSTransitionGroup` will get the `example-appear` CSS class and the `example-appear-active` CSS class added in the next tick.
+
+```css
+.example-appear {
+  opacity: 0.01;
+}
+
+.example-appear.example-appear-active {
+  opacity: 1;
+  transition: opacity .5s ease-in;
+}
+```
+
+At the initial mount, all children of the `ReactCSSTransitionGroup` will `appear` but not `enter`. However, all children later added to an existing `ReactCSSTransitionGroup` will `enter` but not `appear`.
+
+> Note:
+>
+> The prop `transitionAppear` was added to `ReactCSSTransitionGroup` in version `0.13`. To maintain backwards compatibility, the default value is set to `false`.
+>
+> However, the default values of `transitionEnter` and `transitionLeave` are `true` so you must specify `transitionEnterTimeout` and `transitionLeaveTimeout` by default. If you don't need either enter or leave animations, pass `transitionEnter={false}` or `transitionLeave={false}`.
+
+### Custom Classes {#custom-classes}
+
+It is also possible to use custom class names for each of the steps in your transitions. Instead of passing a string into transitionName you can pass an object containing either the `enter` and `leave` class names, or an object containing the `enter`, `enter-active`, `leave-active`, and `leave` class names. If only the enter and leave classes are provided, the enter-active and leave-active classes will be determined by appending '-active' to the end of the class name. Here are two examples using custom classes:
+
+```javascript
+// ...
+<ReactCSSTransitionGroup
+  transitionName={ {
+    enter: 'enter',
+    enterActive: 'enterActive',
+    leave: 'leave',
+    leaveActive: 'leaveActive',
+    appear: 'appear',
+    appearActive: 'appearActive'
+  } }>
+  {item}
+</ReactCSSTransitionGroup>
+
+<ReactCSSTransitionGroup
+  transitionName={ {
+    enter: 'enter',
+    leave: 'leave',
+    appear: 'appear'
+  } }>
+  {item2}
+</ReactCSSTransitionGroup>
+// ...
+```
+
+### Animation Group Must Be Mounted To Work {#animation-group-must-be-mounted-to-work}
+
+In order for it to apply transitions to its children, the `ReactCSSTransitionGroup` must already be mounted in the DOM or the prop `transitionAppear` must be set to `true`.
+
+The example below would **not** work, because the `ReactCSSTransitionGroup` is being mounted along with the new item, instead of the new item being mounted within it. Compare this to the [Getting Started](#getting-started) section above to see the difference.
+
+```javascript{4,6,13}
+render() {
+  const items = this.state.items.map((item, i) => (
+    <div key={item} onClick={() => this.handleRemove(i)}>
+      <ReactCSSTransitionGroup transitionName="example">
+        {item}
+      </ReactCSSTransitionGroup>
+    </div>
+  ));
+
+  return (
+    <div>
+      <button onClick={this.handleAdd}>Add Item</button>
+      {items}
+    </div>
+  );
+}
+```
+
+### Animating One or Zero Items {#animating-one-or-zero-items}
+
+In the example above, we rendered a list of items into `ReactCSSTransitionGroup`. However, the children of `ReactCSSTransitionGroup` can also be one or zero items. This makes it possible to animate a single element entering or leaving. Similarly, you can animate a new element replacing the current element. For example, we can implement a simple image carousel like this:
+
+```javascript{10}
+import ReactCSSTransitionGroup from 'react-addons-css-transition-group';
+
+function ImageCarousel(props) {
+  return (
+    <div>
+      <ReactCSSTransitionGroup
+        transitionName="carousel"
+        transitionEnterTimeout={300}
+        transitionLeaveTimeout={300}>
+        <img src={props.imageSrc} key={props.imageSrc} />
+      </ReactCSSTransitionGroup>
+    </div>
+  );
+}
+```
+
+### Disabling Animations {#disabling-animations}
+
+You can disable animating `enter` or `leave` animations if you want. For example, sometimes you may want an `enter` animation and no `leave` animation, but `ReactCSSTransitionGroup` waits for an animation to complete before removing your DOM node. You can add `transitionEnter={false}` or `transitionLeave={false}` props to `ReactCSSTransitionGroup` to disable these animations.
+
+> Note:
+>
+> When using `ReactCSSTransitionGroup`, there's no way for your components to be notified when a transition has ended or to perform any more complex logic around animation. If you want more fine-grained control, you can use the lower-level `ReactTransitionGroup` API which provides the hooks you need to do custom transitions.
+
+* * *
+
+## Low-level API: ReactTransitionGroup {#low-level-api-reacttransitiongroup}
+
+**Importing**
+
+```javascript
+import ReactTransitionGroup from 'react-addons-transition-group' // ES6
+var ReactTransitionGroup = require('react-addons-transition-group') // ES5 with npm
+```
+
+`ReactTransitionGroup` is the basis for animations. When children are declaratively added or removed from it (as in the [example above](#getting-started)), special lifecycle methods are called on them.
+
+ - [`componentWillAppear()`](#componentwillappear)
+ - [`componentDidAppear()`](#componentdidappear)
+ - [`componentWillEnter()`](#componentwillenter)
+ - [`componentDidEnter()`](#componentdidenter)
+ - [`componentWillLeave()`](#componentwillleave)
+ - [`componentDidLeave()`](#componentdidleave)
+
+#### Rendering a Different Component {#rendering-a-different-component}
+
+`ReactTransitionGroup` renders as a `span` by default. You can change this behavior by providing a `component` prop. For example, here's how you would render a `<ul>`:
+
+```javascript{1}
+<ReactTransitionGroup component="ul">
+  {/* ... */}
+</ReactTransitionGroup>
+```
+
+Any additional, user-defined, properties will become properties of the rendered component. For example, here's how you would render a `<ul>` with CSS class:
+
+```javascript{1}
+<ReactTransitionGroup component="ul" className="animated-list">
+  {/* ... */}
+</ReactTransitionGroup>
+```
+
+Every DOM component that React can render is available for use. However, `component` does not need to be a DOM component. It can be any React component you want; even ones you've written yourself! Just write `component={List}` and your component will receive `this.props.children`.
+
+#### Rendering a Single Child {#rendering-a-single-child}
+
+People often use `ReactTransitionGroup` to animate mounting and unmounting of a single child such as a collapsible panel. Normally `ReactTransitionGroup` wraps all its children in a `span` (or a custom `component` as described above). This is because any React component has to return a single root element, and `ReactTransitionGroup` is no exception to this rule.
+
+However if you only need to render a single child inside `ReactTransitionGroup`, you can completely avoid wrapping it in a `<span>` or any other DOM component. To do this, create a custom component that renders the first child passed to it directly:
+
+```javascript
+function FirstChild(props) {
+  const childrenArray = React.Children.toArray(props.children);
+  return childrenArray[0] || null;
+}
+```
+
+Now you can specify `FirstChild` as the `component` prop in `<ReactTransitionGroup>` props and avoid any wrappers in the result DOM:
+
+```javascript
+<ReactTransitionGroup component={FirstChild}>
+  {someCondition ? <MyComponent /> : null}
+</ReactTransitionGroup>
+```
+
+This only works when you are animating a single child in and out, such as a collapsible panel. This approach wouldn't work when animating multiple children or replacing the single child with another child, such as an image carousel. For an image carousel, while the current image is animating out, another image will animate in, so `<ReactTransitionGroup>` needs to give them a common DOM parent. You can't avoid the wrapper for multiple children, but you can customize the wrapper with the `component` prop as described above.
+
+* * *
+
+## Reference {#reference}
+
+### `componentWillAppear()` {#componentwillappear}
+
+```javascript
+componentWillAppear(callback)
+```
+
+This is called at the same time as `componentDidMount()` for components that are initially mounted in a `TransitionGroup`. It will block other animations from occurring until `callback` is called. It is only called on the initial render of a `TransitionGroup`.
+
+* * *
+
+### `componentDidAppear()` {#componentdidappear}
+
+```javascript
+componentDidAppear()
+```
+
+This is called after the `callback` function that was passed to `componentWillAppear` is called.
+
+* * *
+
+### `componentWillEnter()` {#componentwillenter}
+
+```javascript
+componentWillEnter(callback)
+```
+
+This is called at the same time as `componentDidMount()` for components added to an existing `TransitionGroup`. It will block other animations from occurring until `callback` is called. It will not be called on the initial render of a `TransitionGroup`.
+
+* * *
+
+### `componentDidEnter()` {#componentdidenter}
+
+```javascript
+componentDidEnter()
+```
+
+This is called after the `callback` function that was passed to [`componentWillEnter()`](#componentwillenter) is called.
+
+* * *
+
+### `componentWillLeave()` {#componentwillleave}
+
+```javascript
+componentWillLeave(callback)
+```
+
+This is called when the child has been removed from the `ReactTransitionGroup`. Though the child has been removed, `ReactTransitionGroup` will keep it in the DOM until `callback` is called.
+
+* * *
+
+### `componentDidLeave()` {#componentdidleave}
+
+```javascript
+componentDidLeave()
+```
+
+This is called when the `willLeave` `callback` is called (at the same time as `componentWillUnmount()`).
diff --git a/addons-create-fragment.md b/addons-create-fragment.md
new file mode 100644
index 000000000..7c5fc9fda
--- /dev/null
+++ b/addons-create-fragment.md
@@ -0,0 +1,68 @@
+---
+id: create-fragment
+title: Keyed Fragments
+permalink: docs/create-fragment.html
+layout: docs
+category: Add-Ons
+---
+
+> Note:
+>
+> `React.addons` entry point is deprecated as of React v15.5. We now have first class support for fragments which you can read about [here](/docs/fragments.html).
+
+## Importing {#importing}
+
+```javascript
+import createFragment from 'react-addons-create-fragment'; // ES6
+var createFragment = require('react-addons-create-fragment'); // ES5 with npm
+```
+
+## Overview {#overview}
+
+In most cases, you can use the `key` prop to specify keys on the elements you're returning from `render`. However, this breaks down in one situation: if you have two sets of children that you need to reorder, there's no way to put a key on each set without adding a wrapper element.
+
+That is, if you have a component such as:
+
+```js
+function Swapper(props) {
+  let children;
+  if (props.swapped) {
+    children = [props.rightChildren, props.leftChildren];
+  } else {
+    children = [props.leftChildren, props.rightChildren];
+  }
+  return <div>{children}</div>;
+}
+```
+
+The children will unmount and remount as you change the `swapped` prop because there aren't any keys marked on the two sets of children.
+
+To solve this problem, you can use the `createFragment` add-on to give keys to the sets of children.
+
+#### `Array<ReactNode> createFragment(object children)` {#arrayreactnode-createfragmentobject-children}
+
+Instead of creating arrays, we write:
+
+```javascript
+import createFragment from 'react-addons-create-fragment';
+
+function Swapper(props) {
+  let children;
+  if (props.swapped) {
+    children = createFragment({
+      right: props.rightChildren,
+      left: props.leftChildren
+    });
+  } else {
+    children = createFragment({
+      left: props.leftChildren,
+      right: props.rightChildren
+    });
+  }
+  return <div>{children}</div>;
+}
+```
+
+The keys of the passed object (that is, `left` and `right`) are used as keys for the entire set of children, and the order of the object's keys is used to determine the order of the rendered children. With this change, the two sets of children will be properly reordered in the DOM without unmounting.
+
+The return value of `createFragment` should be treated as an opaque object; you can use the [`React.Children`](/docs/react-api.html#react.children) helpers to loop through a fragment but should not access it directly. Note also that we're relying on the JavaScript engine preserving object enumeration order here, which is not guaranteed by the spec but is implemented by all major browsers and VMs for objects with non-numeric keys.
diff --git a/addons-perf.md b/addons-perf.md
new file mode 100644
index 000000000..a07b1d05a
--- /dev/null
+++ b/addons-perf.md
@@ -0,0 +1,148 @@
+---
+id: perf
+title: Performance Tools
+permalink: docs/perf.html
+layout: docs
+category: Add-Ons
+---
+
+> Note:
+>
+> As of React 16, `react-addons-perf` is not supported. Please use [your browser's profiling tools](/docs/optimizing-performance.html#profiling-components-with-the-chrome-performance-tab) to get insight into which components re-render.
+
+**Importing**
+
+```javascript
+import Perf from 'react-addons-perf'; // ES6
+var Perf = require('react-addons-perf'); // ES5 with npm
+```
+
+
+## Overview {#overview}
+
+React is usually quite fast out of the box. However, in situations where you need to squeeze every ounce of performance out of your app, it provides a [shouldComponentUpdate()](/docs/react-component.html#shouldcomponentupdate) method where you can add optimization hints to React's diff algorithm.
+
+In addition to giving you an overview of your app's overall performance, `Perf` is a profiling tool that tells you exactly where you need to put these methods.
+
+See these articles for an introduction to React performance tooling:
+
+ - ["How to Benchmark React Components"](https://medium.com/code-life/how-to-benchmark-react-components-the-quick-and-dirty-guide-f595baf1014c)
+ - ["Performance Engineering with React"](https://benchling.engineering/performance-engineering-with-react/)
+ - ["A Deep Dive into React Perf Debugging"](https://benchling.engineering/deep-dive-react-perf-debugging/) 
+
+### Development vs. Production Builds {#development-vs-production-builds}
+
+If you're benchmarking or seeing performance problems in your React apps, make sure you're testing with the [minified production build](/downloads.html). The development build includes extra warnings that are helpful when building your apps, but it is slower due to the extra bookkeeping it does.
+
+However, the perf tools described on this page only work when using the development build of React. Therefore, the profiler only serves to indicate the _relatively_ expensive parts of your app.
+
+### Using Perf {#using-perf}
+
+The `Perf` object can be used with React in development mode only. You should not include this bundle when building your app for production.
+
+#### Getting Measurements {#getting-measurements}
+
+ - [`start()`](#start)
+ - [`stop()`](#stop)
+ - [`getLastMeasurements()`](#getlastmeasurements)
+
+#### Printing Results {#printing-results}
+
+The following methods use the measurements returned by [`Perf.getLastMeasurements()`](#getlastmeasurements) to pretty-print the result.
+
+ - [`printInclusive()`](#printinclusive)
+ - [`printExclusive()`](#printexclusive)
+ - [`printWasted()`](#printwasted)
+ - [`printOperations()`](#printoperations)
+ - [`printDOM()`](#printdom)
+
+* * *
+
+## Reference {#reference}
+
+### `start()` {#start}
+### `stop()` {#stop}
+
+```javascript
+Perf.start()
+// ...
+Perf.stop()
+```
+
+Start/stop the measurement. The React operations in-between are recorded for analyses below. Operations that took an insignificant amount of time are ignored.
+
+After stopping, you will need [`Perf.getLastMeasurements()`](#getlastmeasurements) to get the measurements.
+
+* * *
+
+### `getLastMeasurements()` {#getlastmeasurements}
+
+```javascript
+Perf.getLastMeasurements()
+```
+
+Get the opaque data structure describing measurements from the last start-stop session. You can save it and pass it to the other print methods in [`Perf`](#printing-results) to analyze past measurements.
+
+> Note
+>
+> Don't rely on the exact format of the return value because it may change in minor releases. We will update the documentation if the return value format becomes a supported part of the public API.
+
+* * *
+
+### `printInclusive()` {#printinclusive}
+
+```javascript
+Perf.printInclusive(measurements)
+```
+
+Prints the overall time taken. When no arguments are passed, `printInclusive` defaults to all the measurements from the last recording. This prints a nicely formatted table in the console, like so:
+
+![](../images/docs/perf-inclusive.png)
+
+* * *
+
+### `printExclusive()` {#printexclusive}
+
+```javascript
+Perf.printExclusive(measurements)
+```
+
+"Exclusive" times don't include the times taken to mount the components: processing props, calling `componentWillMount` and `componentDidMount`, etc.
+
+![](../images/docs/perf-exclusive.png)
+
+* * *
+
+### `printWasted()` {#printwasted}
+
+```javascript
+Perf.printWasted(measurements)
+```
+
+**The most useful part of the profiler**.
+
+"Wasted" time is spent on components that didn't actually render anything, e.g. the render stayed the same, so the DOM wasn't touched.
+
+![](../images/docs/perf-wasted.png)
+
+* * *
+
+### `printOperations()` {#printoperations}
+
+```javascript
+Perf.printOperations(measurements)
+```
+
+Prints the underlying DOM manipulations, e.g. "set innerHTML" and "remove".
+
+![](../images/docs/perf-dom.png)
+
+* * *
+
+### `printDOM()` {#printdom}
+
+```javascript
+Perf.printDOM(measurements)
+```
+
+This method has been renamed to [`printOperations()`](#printoperations). Currently `printDOM()` still exists as an alias but it prints a deprecation warning and will eventually be removed.
diff --git a/addons-pure-render-mixin.md b/addons-pure-render-mixin.md
new file mode 100644
index 000000000..872445309
--- /dev/null
+++ b/addons-pure-render-mixin.md
@@ -0,0 +1,44 @@
+---
+id: pure-render-mixin
+title: PureRenderMixin
+permalink: docs/pure-render-mixin.html
+layout: docs
+category: Add-Ons
+---
+
+> Note:
+>
+> `PureRenderMixin` is a legacy add-on. Use [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) instead.
+
+**Importing**
+
+```javascript
+import PureRenderMixin from 'react-addons-pure-render-mixin'; // ES6
+var PureRenderMixin = require('react-addons-pure-render-mixin'); // ES5 with npm
+```
+
+## Overview {#overview}
+
+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.
+
+Example:
+
+```js
+const createReactClass = require('create-react-class');
+
+createReactClass({
+  mixins: [PureRenderMixin],
+
+  render: function() {
+    return <div className={this.props.className}>foo</div>;
+  }
+});
+```
+
+Under the hood, the mixin implements [shouldComponentUpdate](/docs/component-specs.html#updating-shouldcomponentupdate), in which it compares the current props and state with the next ones and returns `false` if the equalities pass.
+
+> Note:
+>
+> This only shallowly compares the objects. If these contain complex data structures, it may produce false-negatives for deeper differences. Only mix into components which have simple props and state, or use `forceUpdate()` when you know deep data structures have changed. Or, consider using [immutable objects](https://facebook.github.io/immutable-js/) to facilitate fast comparisons of nested data.
+>
+> Furthermore, `shouldComponentUpdate` skips updates for the whole component subtree. Make sure all the children components are also "pure".
diff --git a/addons-shallow-compare.md b/addons-shallow-compare.md
new file mode 100644
index 000000000..44bee0cf3
--- /dev/null
+++ b/addons-shallow-compare.md
@@ -0,0 +1,44 @@
+---
+id: shallow-compare
+title: Shallow Compare
+permalink: docs/shallow-compare.html
+layout: docs
+category: Reference
+---
+
+> Note:
+>
+> `shallowCompare` is a legacy add-on. Use [`React.memo`](/docs/react-api.html#reactmemo) or [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) instead.
+
+**Importing**
+
+```javascript
+import shallowCompare from 'react-addons-shallow-compare'; // ES6
+var shallowCompare = require('react-addons-shallow-compare'); // ES5 with npm
+```
+
+## Overview {#overview}
+
+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.
+
+Example:
+
+```js
+export class SampleComponent extends React.Component {
+  shouldComponentUpdate(nextProps, nextState) {
+    return shallowCompare(this, nextProps, nextState);
+  }
+
+  render() {
+    return <div className={this.props.className}>foo</div>;
+  }
+}
+```
+
+`shallowCompare` performs a shallow equality check on the current `props` and `nextProps` objects as well as the current `state` and `nextState` objects.  
+It does this by iterating on the keys of the objects being compared and returning true when the values of a key in each object are not strictly equal.
+
+`shallowCompare` returns `true` if the shallow comparison for props or state fails and therefore the component should update.  
+`shallowCompare` returns `false` if the shallow comparison for props and state both pass and therefore the component does not need to update.
diff --git a/addons-shallow-renderer.md b/addons-shallow-renderer.md
new file mode 100644
index 000000000..7b7f29f3c
--- /dev/null
+++ b/addons-shallow-renderer.md
@@ -0,0 +1,68 @@
+---
+id: shallow-renderer
+title: Shallow Renderer
+permalink: docs/shallow-renderer.html
+layout: docs
+category: Reference
+---
+
+**Importing**
+
+```javascript
+import ShallowRenderer from 'react-test-renderer/shallow'; // ES6
+var ShallowRenderer = require('react-test-renderer/shallow'); // ES5 with npm
+```
+
+## Overview {#overview}
+
+When writing unit tests for React, shallow rendering can be helpful. Shallow rendering lets you render a component "one level deep" and assert facts about what its render method returns, without worrying about the behavior of child components, which are not instantiated or rendered. This does not require a DOM.
+
+For example, if you have the following component:
+
+```javascript
+function MyComponent() {
+  return (
+    <div>
+      <span className="heading">Title</span>
+      <Subcomponent foo="bar" />
+    </div>
+  );
+}
+```
+
+Then you can assert:
+
+```javascript
+import ShallowRenderer from 'react-test-renderer/shallow';
+
+// in your test:
+const renderer = new ShallowRenderer();
+renderer.render(<MyComponent />);
+const result = renderer.getRenderOutput();
+
+expect(result.type).toBe('div');
+expect(result.props.children).toEqual([
+  <span className="heading">Title</span>,
+  <Subcomponent foo="bar" />
+]);
+```
+
+Shallow testing currently has some limitations, namely not supporting refs.
+
+> Note:
+>
+> We also recommend checking out Enzyme's [Shallow Rendering API](https://airbnb.io/enzyme/docs/api/shallow.html). It provides a nicer higher-level API over the same functionality.
+
+## Reference {#reference}
+
+### `shallowRenderer.render()` {#shallowrendererrender}
+
+You can think of the shallowRenderer as a "place" to render the component you're testing, and from which you can extract the component's output.
+
+`shallowRenderer.render()` is similar to [`ReactDOM.render()`](/docs/react-dom.html#render) but it doesn't require DOM and only renders a single level deep. This means you can test components isolated from how their children are implemented.
+
+### `shallowRenderer.getRenderOutput()` {#shallowrenderergetrenderoutput}
+
+After `shallowRenderer.render()` has been called, you can use `shallowRenderer.getRenderOutput()` to get the shallowly rendered output.
+
+You can then begin to assert facts about the output.
diff --git a/addons-test-utils.md b/addons-test-utils.md
new file mode 100644
index 000000000..d269eaa73
--- /dev/null
+++ b/addons-test-utils.md
@@ -0,0 +1,351 @@
+---
+id: test-utils
+title: Test Utilities
+permalink: docs/test-utils.html
+layout: docs
+category: Reference
+---
+
+**Importing**
+
+```javascript
+import ReactTestUtils from 'react-dom/test-utils'; // ES6
+var ReactTestUtils = require('react-dom/test-utils'); // ES5 with npm
+```
+
+## Overview {#overview}
+
+`ReactTestUtils` makes it easy to test React components in the testing framework of your choice. At Facebook we use [Jest](https://facebook.github.io/jest/) for painless JavaScript testing. Learn how to get started with Jest through the Jest website's [React Tutorial](https://jestjs.io/docs/tutorial-react).
+
+> Note:
+>
+> We recommend using [React Testing Library](https://testing-library.com/react) which is designed to enable and encourage writing tests that use your components as the end users do.
+>
+> Alternatively, Airbnb has released a testing utility called [Enzyme](https://airbnb.io/enzyme/), which makes it easy to assert, manipulate, and traverse your React Components' output.
+
+ - [`act()`](#act)
+ - [`mockComponent()`](#mockcomponent)
+ - [`isElement()`](#iselement)
+ - [`isElementOfType()`](#iselementoftype)
+ - [`isDOMComponent()`](#isdomcomponent)
+ - [`isCompositeComponent()`](#iscompositecomponent)
+ - [`isCompositeComponentWithType()`](#iscompositecomponentwithtype)
+ - [`findAllInRenderedTree()`](#findallinrenderedtree)
+ - [`scryRenderedDOMComponentsWithClass()`](#scryrendereddomcomponentswithclass)
+ - [`findRenderedDOMComponentWithClass()`](#findrendereddomcomponentwithclass)
+ - [`scryRenderedDOMComponentsWithTag()`](#scryrendereddomcomponentswithtag)
+ - [`findRenderedDOMComponentWithTag()`](#findrendereddomcomponentwithtag)
+ - [`scryRenderedComponentsWithType()`](#scryrenderedcomponentswithtype)
+ - [`findRenderedComponentWithType()`](#findrenderedcomponentwithtype)
+ - [`renderIntoDocument()`](#renderintodocument)
+ - [`Simulate`](#simulate)
+
+## Reference {#reference}
+
+### `act()` {#act}
+
+To prepare a component for assertions, wrap the code rendering it and performing updates inside an `act()` call. This makes your test run closer to how React works in the browser.
+
+>Note
+>
+>If you use `react-test-renderer`, it also provides an `act` export that behaves the same way.
+
+For example, let's say we have this `Counter` component:
+
+```js
+class Counter extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {count: 0};
+    this.handleClick = this.handleClick.bind(this);
+  }
+  componentDidMount() {
+    document.title = `You clicked ${this.state.count} times`;
+  }
+  componentDidUpdate() {
+    document.title = `You clicked ${this.state.count} times`;
+  }
+  handleClick() {
+    this.setState(state => ({
+      count: state.count + 1,
+    }));
+  }
+  render() {
+    return (
+      <div>
+        <p>You clicked {this.state.count} times</p>
+        <button onClick={this.handleClick}>
+          Click me
+        </button>
+      </div>
+    );
+  }
+}
+```
+
+Here is how we can test it:
+
+```js{3,20-22,29-31}
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { act } from 'react-dom/test-utils';
+import Counter from './Counter';
+
+let container;
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  document.body.removeChild(container);
+  container = null;
+});
+
+it('can render and update a counter', () => {
+  // Test first render and componentDidMount
+  act(() => {
+    ReactDOM.render(<Counter />, container);
+  });
+  const button = container.querySelector('button');
+  const label = container.querySelector('p');
+  expect(label.textContent).toBe('You clicked 0 times');
+  expect(document.title).toBe('You clicked 0 times');
+
+  // Test second render and componentDidUpdate
+  act(() => {
+    button.dispatchEvent(new MouseEvent('click', {bubbles: true}));
+  });
+  expect(label.textContent).toBe('You clicked 1 times');
+  expect(document.title).toBe('You clicked 1 times');
+});
+```
+
+- Don't forget that dispatching DOM events only works when the DOM container is added to the `document`. You can use a library like [React Testing Library](https://testing-library.com/react) to reduce the boilerplate code.
+
+- The [`recipes`](/docs/testing-recipes.html) document contains more details on how `act()` behaves, with examples and usage.
+
+* * *
+
+### `mockComponent()` {#mockcomponent}
+
+```javascript
+mockComponent(
+  componentClass,
+  [mockTagName]
+)
+```
+
+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 [`jest.mock()`](https://facebook.github.io/jest/docs/en/tutorial-react-native.html#mock-native-modules-using-jestmock) instead.
+
+* * *
+
+### `isElement()` {#iselement}
+
+```javascript
+isElement(element)
+```
+
+Returns `true` if `element` is any React element.
+
+* * *
+
+### `isElementOfType()` {#iselementoftype}
+
+```javascript
+isElementOfType(
+  element,
+  componentClass
+)
+```
+
+Returns `true` if `element` is a React element whose type is of a React `componentClass`.
+
+* * *
+
+### `isDOMComponent()` {#isdomcomponent}
+
+```javascript
+isDOMComponent(instance)
+```
+
+Returns `true` if `instance` is a DOM component (such as a `<div>` or `<span>`).
+
+* * *
+
+### `isCompositeComponent()` {#iscompositecomponent}
+
+```javascript
+isCompositeComponent(instance)
+```
+
+Returns `true` if `instance` is a user-defined component, such as a class or a function.
+
+* * *
+
+### `isCompositeComponentWithType()` {#iscompositecomponentwithtype}
+
+```javascript
+isCompositeComponentWithType(
+  instance,
+  componentClass
+)
+```
+
+Returns `true` if `instance` is a component whose type is of a React `componentClass`.
+
+* * *
+
+### `findAllInRenderedTree()` {#findallinrenderedtree}
+
+```javascript
+findAllInRenderedTree(
+  tree,
+  test
+)
+```
+
+Traverse all components in `tree` and accumulate all components where `test(component)` is `true`. This is not that useful on its own, but it's used as a primitive for other test utils.
+
+* * *
+
+### `scryRenderedDOMComponentsWithClass()` {#scryrendereddomcomponentswithclass}
+
+```javascript
+scryRenderedDOMComponentsWithClass(
+  tree,
+  className
+)
+```
+
+Finds all DOM elements of components in the rendered tree that are DOM components with the class name matching `className`.
+
+* * *
+
+### `findRenderedDOMComponentWithClass()` {#findrendereddomcomponentwithclass}
+
+```javascript
+findRenderedDOMComponentWithClass(
+  tree,
+  className
+)
+```
+
+Like [`scryRenderedDOMComponentsWithClass()`](#scryrendereddomcomponentswithclass) but expects there to be one result, and returns that one result, or throws exception if there is any other number of matches besides one.
+
+* * *
+
+### `scryRenderedDOMComponentsWithTag()` {#scryrendereddomcomponentswithtag}
+
+```javascript
+scryRenderedDOMComponentsWithTag(
+  tree,
+  tagName
+)
+```
+
+Finds all DOM elements of components in the rendered tree that are DOM components with the tag name matching `tagName`.
+
+* * *
+
+### `findRenderedDOMComponentWithTag()` {#findrendereddomcomponentwithtag}
+
+```javascript
+findRenderedDOMComponentWithTag(
+  tree,
+  tagName
+)
+```
+
+Like [`scryRenderedDOMComponentsWithTag()`](#scryrendereddomcomponentswithtag) but expects there to be one result, and returns that one result, or throws exception if there is any other number of matches besides one.
+
+* * *
+
+### `scryRenderedComponentsWithType()` {#scryrenderedcomponentswithtype}
+
+```javascript
+scryRenderedComponentsWithType(
+  tree,
+  componentClass
+)
+```
+
+Finds all instances of components with type equal to `componentClass`.
+
+* * *
+
+### `findRenderedComponentWithType()` {#findrenderedcomponentwithtype}
+
+```javascript
+findRenderedComponentWithType(
+  tree,
+  componentClass
+)
+```
+
+Same as [`scryRenderedComponentsWithType()`](#scryrenderedcomponentswithtype) but expects there to be one result and returns that one result, or throws exception if there is any other number of matches besides one.
+
+***
+
+### `renderIntoDocument()` {#renderintodocument}
+
+```javascript
+renderIntoDocument(element)
+```
+
+Render a React element into a detached DOM node in the document. **This function requires a DOM.** It is effectively equivalent to:
+
+```js
+const domContainer = document.createElement('div');
+ReactDOM.render(element, domContainer);
+```
+
+> Note:
+>
+> You will need to have `window`, `window.document` and `window.document.createElement` globally available **before** you import `React`. Otherwise React will think it can't access the DOM and methods like `setState` won't work.
+
+* * *
+
+## Other Utilities {#other-utilities}
+
+### `Simulate` {#simulate}
+
+```javascript
+Simulate.{eventName}(
+  element,
+  [eventData]
+)
+```
+
+Simulate an event dispatch on a DOM node with optional `eventData` event data.
+
+`Simulate` has a method for [every event that React understands](/docs/events.html#supported-events).
+
+**Clicking an element**
+
+```javascript
+// <button ref={(node) => this.button = node}>...</button>
+const node = this.button;
+ReactTestUtils.Simulate.click(node);
+```
+
+**Changing the value of an input field and then pressing ENTER.**
+
+```javascript
+// <input ref={(node) => this.textInput = node} />
+const node = this.textInput;
+node.value = 'giraffe';
+ReactTestUtils.Simulate.change(node);
+ReactTestUtils.Simulate.keyDown(node, {key: "Enter", keyCode: 13, which: 13});
+```
+
+> Note
+>
+> You will have to provide any event property that you're using in your component (e.g. keyCode, which, etc...) as React is not creating any of these for you.
+
+* * *
diff --git a/addons-two-way-binding-helpers.md b/addons-two-way-binding-helpers.md
new file mode 100644
index 000000000..37c00679a
--- /dev/null
+++ b/addons-two-way-binding-helpers.md
@@ -0,0 +1,131 @@
+---
+id: two-way-binding-helpers
+title: Two-way Binding Helpers
+permalink: docs/two-way-binding-helpers.html
+layout: docs
+category: Add-Ons
+---
+
+> Note:
+>
+> `LinkedStateMixin` is deprecated as of React v15. The recommendation is to explicitly set the value and change handler, instead of using `LinkedStateMixin`.
+
+**Importing**
+
+```javascript
+import LinkedStateMixin from 'react-addons-linked-state-mixin'; // ES6
+var LinkedStateMixin = require('react-addons-linked-state-mixin'); // ES5 with npm
+```
+
+## Overview {#overview}
+
+`LinkedStateMixin` is an easy way to express two-way binding with React.
+
+In React, data flows one way: from owner to child. We think that this makes your app's code easier to understand. You can think of it as "one-way data binding."
+
+However, there are lots of applications that require you to read some data and flow it back into your program. For example, when developing forms, you'll often want to update some React `state` when you receive user input. Or perhaps you want to perform layout in JavaScript and react to changes in some DOM element size.
+
+In React, you would implement this by listening to a "change" event, read from your data source (usually the DOM) and call `setState()` on one of your components. "Closing the data flow loop" explicitly leads to more understandable and easier-to-maintain programs. See [our forms documentation](/docs/forms.html) for more information.
+
+Two-way binding -- implicitly enforcing that some value in the DOM is always consistent with some React `state` -- is concise and supports a wide variety of applications. We've provided `LinkedStateMixin`: syntactic sugar for setting up the common data flow loop pattern described above, or "linking" some data source to React `state`.
+
+> Note:
+>
+> `LinkedStateMixin` is just a thin wrapper and convention around the `onChange`/`setState()` pattern. It doesn't fundamentally change how data flows in your React application.
+
+## LinkedStateMixin: Before and After {#linkedstatemixin-before-and-after}
+
+Here's a simple form example without using `LinkedStateMixin`:
+
+```javascript
+var createReactClass = require('create-react-class');
+
+var NoLink = createReactClass({
+  getInitialState: function() {
+    return {message: 'Hello!'};
+  },
+  handleChange: function(event) {
+    this.setState({message: event.target.value});
+  },
+  render: function() {
+    var message = this.state.message;
+    return <input type="text" value={message} onChange={this.handleChange} />;
+  }
+});
+```
+
+This works really well and it's very clear how data is flowing, however, with a lot of form fields it could get a bit verbose. Let's use `LinkedStateMixin` to save us some typing:
+
+```javascript{4,9}
+var createReactClass = require('create-react-class');
+
+var WithLink = createReactClass({
+  mixins: [LinkedStateMixin],
+  getInitialState: function() {
+    return {message: 'Hello!'};
+  },
+  render: function() {
+    return <input type="text" valueLink={this.linkState('message')} />;
+  }
+});
+```
+
+`LinkedStateMixin` adds a method to your React component called `linkState()`. `linkState()` returns a `valueLink` object which contains the current value of the React state and a callback to change it.
+
+`valueLink` objects can be passed up and down the tree as props, so it's easy (and explicit) to set up two-way binding between a component deep in the hierarchy and state that lives higher in the hierarchy.
+
+Note that checkboxes have a special behavior regarding their `value` attribute, which is the value that will be sent on form submit if the checkbox is checked (defaults to `on`). The `value` attribute is not updated when the checkbox is checked or unchecked. For checkboxes, you should use `checkedLink` instead of `valueLink`:
+```
+<input type="checkbox" checkedLink={this.linkState('booleanValue')} />
+```
+
+## Under the Hood {#under-the-hood}
+
+There are two sides to `LinkedStateMixin`: the place where you create the `valueLink` instance and the place where you use it. To prove how simple `LinkedStateMixin` is, let's rewrite each side separately to be more explicit.
+
+### valueLink Without LinkedStateMixin {#valuelink-without-linkedstatemixin}
+
+```javascript{7-9,11-14}
+var createReactClass = require('create-react-class');
+
+var WithoutMixin = createReactClass({
+  getInitialState: function() {
+    return {message: 'Hello!'};
+  },
+  handleChange: function(newValue) {
+    this.setState({message: newValue});
+  },
+  render: function() {
+    var valueLink = {
+      value: this.state.message,
+      requestChange: this.handleChange
+    };
+    return <input type="text" valueLink={valueLink} />;
+  }
+});
+```
+
+As you can see, `valueLink` objects are very simple objects that just have a `value` and `requestChange` prop. And `LinkedStateMixin` is similarly simple: it just populates those fields with a value from `this.state` and a callback that calls `this.setState()`.
+
+### LinkedStateMixin Without valueLink {#linkedstatemixin-without-valuelink}
+
+```javascript
+var LinkedStateMixin = require('react-addons-linked-state-mixin');
+var createReactClass = require('create-react-class');
+
+var WithoutLink = createReactClass({
+  mixins: [LinkedStateMixin],
+  getInitialState: function() {
+    return {message: 'Hello!'};
+  },
+  render: function() {
+    var valueLink = this.linkState('message');
+    var handleChange = function(e) {
+      valueLink.requestChange(e.target.value);
+    };
+    return <input type="text" value={valueLink.value} onChange={handleChange} />;
+  }
+});
+```
+
+The `valueLink` prop is also quite simple. It simply handles the `onChange` event and calls `this.props.valueLink.requestChange()` and also uses `this.props.valueLink.value` instead of `this.props.value`. That's it!
diff --git a/addons-update.md b/addons-update.md
new file mode 100644
index 000000000..0e0241074
--- /dev/null
+++ b/addons-update.md
@@ -0,0 +1,117 @@
+---
+id: update
+title: Immutability Helpers
+permalink: docs/update.html
+layout: docs
+category: Add-Ons
+---
+
+> Note:
+>
+> `update` is a legacy add-on. Use [`immutability-helper`](https://github.com/kolodny/immutability-helper) instead.
+
+**Importing**
+
+```javascript
+import update from 'react-addons-update'; // ES6
+var update = require('react-addons-update'); // ES5 with npm
+```
+
+## Overview {#overview}
+
+React lets you use whatever style of data management you want, including mutation. However, if you can use immutable data in performance-critical parts of your application it's easy to implement a fast [`shouldComponentUpdate()`](/docs/react-component.html#shouldcomponentupdate) method to significantly speed up your app.
+
+Dealing with immutable data in JavaScript is more difficult than in languages designed for it, like [Clojure](https://clojure.org/). However, we've provided a simple immutability helper, `update()`, that makes dealing with this type of data much easier, *without* fundamentally changing how your data is represented. You can also take a look at Facebook's [Immutable-js](https://facebook.github.io/immutable-js/docs/) and the [Advanced Performance](/docs/advanced-performance.html) section for more detail on Immutable-js.
+
+### The Main Idea {#the-main-idea}
+
+If you mutate data like this:
+
+```js
+myData.x.y.z = 7;
+// or...
+myData.a.b.push(9);
+```
+
+You have no way of determining which data has changed since the previous copy has been overwritten. Instead, you need to create a new copy of `myData` and change only the parts of it that need to be changed. Then you can compare the old copy of `myData` with the new one in `shouldComponentUpdate()` using triple-equals:
+
+```js
+const newData = deepCopy(myData);
+newData.x.y.z = 7;
+newData.a.b.push(9);
+```
+
+Unfortunately, deep copies are expensive, and sometimes impossible. You can alleviate this by only copying objects that need to be changed and by reusing the objects that haven't changed. Unfortunately, in today's JavaScript this can be cumbersome:
+
+```js
+const newData = extend(myData, {
+  x: extend(myData.x, {
+    y: extend(myData.x.y, {z: 7}),
+  }),
+  a: extend(myData.a, {b: myData.a.b.concat(9)})
+});
+```
+
+While this is fairly performant (since it only makes a shallow copy of `log n` objects and reuses the rest), it's a big pain to write. Look at all the repetition! This is not only annoying, but also provides a large surface area for bugs.
+
+## `update()` {#update}
+
+`update()` provides simple syntactic sugar around this pattern to make writing this code easier. This code becomes:
+
+```js
+import update from 'react-addons-update';
+
+const newData = update(myData, {
+  x: {y: {z: {$set: 7}}},
+  a: {b: {$push: [9]}}
+});
+```
+
+While the syntax takes a little getting used to (though it's inspired by [MongoDB's query language](https://docs.mongodb.com/manual/crud/#query)) there's no redundancy, it's statically analyzable and it's not much more typing than the mutative version.
+
+The `$`-prefixed keys are called *commands*. The data structure they are "mutating" is called the *target*.
+
+## Available Commands {#available-commands}
+
+  * `{$push: array}` `push()` all the items in `array` on the target.
+  * `{$unshift: array}` `unshift()` all the items in `array` on the target.
+  * `{$splice: array of arrays}` for each item in `arrays` call `splice()` on the target with the parameters provided by the item.
+  * `{$set: any}` replace the target entirely.
+  * `{$merge: object}` merge the keys of `object` with the target.
+  * `{$apply: function}` passes in the current value to the function and updates it with the new returned value.
+
+## Examples {#examples}
+
+### Simple push {#simple-push}
+
+```js
+const initialArray = [1, 2, 3];
+const newArray = update(initialArray, {$push: [4]}); // => [1, 2, 3, 4]
+```
+`initialArray` is still `[1, 2, 3]`.
+
+### Nested collections {#nested-collections}
+
+```js
+const collection = [1, 2, {a: [12, 17, 15]}];
+const newCollection = update(collection, {2: {a: {$splice: [[1, 1, 13, 14]]}}});
+// => [1, 2, {a: [12, 13, 14, 15]}]
+```
+This accesses `collection`'s index `2`, key `a`, and does a splice of one item starting from index `1` (to remove `17`) while inserting `13` and `14`.
+
+### Updating a value based on its current one {#updating-a-value-based-on-its-current-one}
+
+```js
+const obj = {a: 5, b: 3};
+const newObj = update(obj, {b: {$apply: function(x) {return x * 2;}}});
+// => {a: 5, b: 6}
+// This is equivalent, but gets verbose for deeply nested collections:
+const newObj2 = update(obj, {b: {$set: obj.b * 2}});
+```
+
+### (Shallow) Merge {#shallow-merge}
+
+```js
+const obj = {a: 5, b: 3};
+const newObj = update(obj, {$merge: {b: 6, c: 7}}); // => {a: 5, b: 6, c: 7}
+```
diff --git a/addons.md b/addons.md
new file mode 100644
index 000000000..a19f4ba79
--- /dev/null
+++ b/addons.md
@@ -0,0 +1,49 @@
+---
+id: addons
+title: Add-Ons
+permalink: docs/addons.html
+---
+
+> Note:
+>
+> `React.addons` entry point is deprecated as of React v15.5. The add-ons have moved to separate modules, and some of them have been deprecated.
+
+The React add-ons are a collection of useful utility modules for building React apps. **These should be considered experimental** and tend to change more often than the core.
+
+- [`createFragment`](/docs/create-fragment.html), to create a set of externally-keyed children.
+
+The add-ons below are in the development (unminified) version of React only:
+
+- [`Perf`](/docs/perf.html), a performance profiling tool for finding optimization opportunities.
+- [`ReactTestUtils`](/docs/test-utils.html), simple helpers for writing test cases.
+
+### Legacy Add-ons {#legacy-add-ons}
+
+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`](/docs/pure-render-mixin.html). Use [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) instead.
+- [`shallowCompare`](/docs/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`](/docs/update.html). Use [`kolodny/immutability-helper`](https://github.com/kolodny/immutability-helper) instead.
+- [`ReactDOMFactories`](https://www.npmjs.com/package/react-dom-factories), pre-configured DOM factories to make React easier to use without JSX.
+
+### Deprecated Add-ons {#deprecated-add-ons}
+
+- [`LinkedStateMixin`](/docs/two-way-binding-helpers.html) has been deprecated.
+- [`TransitionGroup` and `CSSTransitionGroup`](/docs/animation.html) have been deprecated in favor of [their drop-in replacements](https://github.com/reactjs/react-transition-group/tree/v1-stable).
+
+## Using React with Add-ons {#using-react-with-add-ons}
+
+You can install the add-ons individually from npm (e.g. `npm install react-addons-create-fragment`) and import them:
+
+```javascript
+import createFragment from 'react-addons-create-fragment'; // ES6
+var createFragment = require('react-addons-create-fragment'); // ES5 with npm
+```
+
+When using React 15 or earlier from a CDN, you can use `react-with-addons.js` instead of `react.js`:
+
+```html
+<script src="https://unpkg.com/react@15/dist/react-with-addons.js"></script>
+```
+
+The add-ons will be available via the `React.addons` global (e.g. `React.addons.TestUtils`).
diff --git a/cdn-links.md b/cdn-links.md
new file mode 100644
index 000000000..73e3e8171
--- /dev/null
+++ b/cdn-links.md
@@ -0,0 +1,37 @@
+---
+id: cdn-links
+title: CDN Links
+permalink: docs/cdn-links.html
+prev: create-a-new-react-app.html
+next: hello-world.html
+---
+
+Both React and ReactDOM are available over a CDN.
+
+```html
+<script crossorigin src="https://unpkg.com/react@16/umd/react.development.js"></script>
+<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.development.js"></script>
+```
+
+The versions above are only meant for development, and are not suitable for production. Minified and optimized production versions of React are available at:
+
+```html
+<script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
+<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>
+```
+
+To load a specific version of `react` and `react-dom`, replace `16` with the version number.
+
+### Why the `crossorigin` Attribute? {#why-the-crossorigin-attribute}
+
+If you serve React from a CDN, we recommend to keep the [`crossorigin`](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) attribute set:
+
+```html
+<script crossorigin src="..."></script>
+```
+
+We also recommend to verify that the CDN you are using sets the `Access-Control-Allow-Origin: *` HTTP header:
+
+![Access-Control-Allow-Origin: *](../images/docs/cdn-cors-header.png)
+
+This enables a better [error handling experience](/blog/2017/07/26/error-handling-in-react-16.html) in React 16 and later.
diff --git a/code-splitting.md b/code-splitting.md
new file mode 100644
index 000000000..9d1101cdc
--- /dev/null
+++ b/code-splitting.md
@@ -0,0 +1,250 @@
+---
+id: code-splitting
+title: Code-Splitting
+permalink: docs/code-splitting.html
+---
+
+## Bundling {#bundling}
+
+Most React apps will have their files "bundled" using tools like
+[Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/) or 
+[Browserify](http://browserify.org/).
+Bundling is the process of following imported files and merging them into a
+single file: a "bundle". This bundle can then be included on a webpage to load
+an entire app at once.
+
+#### Example {#example}
+
+**App:**
+
+```js
+// app.js
+import { add } from './math.js';
+
+console.log(add(16, 26)); // 42
+```
+
+```js
+// math.js
+export function add(a, b) {
+  return a + b;
+}
+```
+
+**Bundle:**
+
+```js
+function add(a, b) {
+  return a + b;
+}
+
+console.log(add(16, 26)); // 42
+```
+
+> Note:
+>
+> Your bundles will end up looking a lot different than this.
+
+If you're using [Create React App](https://github.com/facebookincubator/create-react-app), [Next.js](https://github.com/zeit/next.js/), [Gatsby](https://www.gatsbyjs.org/), or a similar tool, you will have a Webpack setup out of the box to bundle your
+app.
+
+If you aren't, you'll need to setup bundling yourself. For example, see the
+[Installation](https://webpack.js.org/guides/installation/) and
+[Getting Started](https://webpack.js.org/guides/getting-started/) guides on the
+Webpack docs.
+
+## Code Splitting {#code-splitting}
+
+Bundling is great, but as your app grows, your bundle will grow too. Especially
+if you are including large third-party libraries. You need to keep an eye on
+the code you are including in your bundle so that you don't accidentally make
+it so large that your app takes a long time to load.
+
+To avoid winding up with a large bundle, it's good to get ahead of the problem
+and start "splitting" your bundle.
+Code-Splitting is a feature
+supported by bundlers like [Webpack](https://webpack.js.org/guides/code-splitting/), [Rollup](https://rollupjs.org/guide/en/#code-splitting) and Browserify (via
+[factor-bundle](https://github.com/browserify/factor-bundle)) which can create
+multiple bundles that can be dynamically loaded at runtime.
+
+Code-splitting your app can help you "lazy-load" just the things that are
+currently needed by the user, which can dramatically improve the performance of
+your app. While you haven't reduced the overall amount of code in your app,
+you've avoided loading code that the user may never need, and reduced the amount
+of code needed during the initial load.
+
+## `import()` {#import}
+
+The best way to introduce code-splitting into your app is through the dynamic
+`import()` syntax.
+
+**Before:**
+
+```js
+import { add } from './math';
+
+console.log(add(16, 26));
+```
+
+**After:**
+
+```js
+import("./math").then(math => {
+  console.log(math.add(16, 26));
+});
+```
+
+> Note:
+>
+> The dynamic `import()` syntax is a ECMAScript (JavaScript)
+> [proposal](https://github.com/tc39/proposal-dynamic-import) not currently
+> part of the language standard. It is expected to be accepted in the
+> near future.
+
+When Webpack comes across this syntax, it automatically starts code-splitting
+your app. If you're using Create React App, this is already configured for you
+and you can [start using it](https://facebook.github.io/create-react-app/docs/code-splitting) immediately. It's also supported
+out of the box in [Next.js](https://github.com/zeit/next.js/#dynamic-import).
+
+If you're setting up Webpack yourself, you'll probably want to read Webpack's
+[guide on code splitting](https://webpack.js.org/guides/code-splitting/). Your Webpack config should look vaguely [like this](https://gist.github.com/gaearon/ca6e803f5c604d37468b0091d9959269).
+
+When using [Babel](https://babeljs.io/), you'll need to make sure that Babel can
+parse the dynamic import syntax but is not transforming it. For that you will need [babel-plugin-syntax-dynamic-import](https://yarnpkg.com/en/package/babel-plugin-syntax-dynamic-import).
+
+## `React.lazy` {#reactlazy}
+
+> Note:
+>
+> `React.lazy` and Suspense are not yet available for server-side rendering. If you want to do code-splitting in a server rendered app, we recommend [Loadable Components](https://github.com/smooth-code/loadable-components). It has a nice [guide for bundle splitting with server-side rendering](https://github.com/smooth-code/loadable-components/blob/master/packages/server/README.md).
+
+The `React.lazy` function lets you render a dynamic import as a regular component.
+
+**Before:**
+
+```js
+import OtherComponent from './OtherComponent';
+```
+
+**After:**
+
+```js
+const OtherComponent = React.lazy(() => import('./OtherComponent'));
+```
+
+This will automatically load the bundle containing the `OtherComponent` when this component is first rendered.
+
+`React.lazy` takes a function that must call a dynamic `import()`. This must return a `Promise` which resolves to a module with a `default` export containing a React component.
+
+The lazy component should then be rendered inside a `Suspense` component, which allows us to show some fallback content (such as a loading indicator) while we're waiting for the lazy component to load.
+
+```js
+const OtherComponent = React.lazy(() => import('./OtherComponent'));
+
+function MyComponent() {
+  return (
+    <div>
+      <Suspense fallback={<div>Loading...</div>}>
+        <OtherComponent />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+The `fallback` prop accepts any React elements that you want to render while waiting for the component to load. You can place the `Suspense` component anywhere above the lazy component. You can even wrap multiple lazy components with a single `Suspense` component.
+
+```js
+const OtherComponent = React.lazy(() => import('./OtherComponent'));
+const AnotherComponent = React.lazy(() => import('./AnotherComponent'));
+
+function MyComponent() {
+  return (
+    <div>
+      <Suspense fallback={<div>Loading...</div>}>
+        <section>
+          <OtherComponent />
+          <AnotherComponent />
+        </section>
+      </Suspense>
+    </div>
+  );
+}
+```
+
+### Error boundaries {#error-boundaries}
+
+If the other module fails to load (for example, due to network failure), it will trigger an error. You can handle these errors to show a nice user experience and manage recovery with [Error Boundaries](/docs/error-boundaries.html). Once you've created your Error Boundary, you can use it anywhere above your lazy components to display an error state when there's a network error.
+
+```js
+import MyErrorBoundary from './MyErrorBoundary';
+const OtherComponent = React.lazy(() => import('./OtherComponent'));
+const AnotherComponent = React.lazy(() => import('./AnotherComponent'));
+
+const MyComponent = () => (
+  <div>
+    <MyErrorBoundary>
+      <Suspense fallback={<div>Loading...</div>}>
+        <section>
+          <OtherComponent />
+          <AnotherComponent />
+        </section>
+      </Suspense>
+    </MyErrorBoundary>
+  </div>
+);
+```
+
+## Route-based code splitting {#route-based-code-splitting}
+
+Deciding where in your app to introduce code splitting can be a bit tricky. You
+want to make sure you choose places that will split bundles evenly, but won't
+disrupt the user experience.
+
+A good place to start is with routes. Most people on the web are used to
+page transitions taking some amount of time to load. You also tend to be
+re-rendering the entire page at once so your users are unlikely to be
+interacting with other elements on the page at the same time.
+
+Here's an example of how to setup route-based code splitting into your app using
+libraries like [React Router](https://reacttraining.com/react-router/) with `React.lazy`.
+
+```js
+import { BrowserRouter as Router, Route, Switch } from 'react-router-dom';
+import React, { Suspense, lazy } from 'react';
+
+const Home = lazy(() => import('./routes/Home'));
+const About = lazy(() => import('./routes/About'));
+
+const App = () => (
+  <Router>
+    <Suspense fallback={<div>Loading...</div>}>
+      <Switch>
+        <Route exact path="/" component={Home}/>
+        <Route path="/about" component={About}/>
+      </Switch>
+    </Suspense>
+  </Router>
+);
+```
+
+## Named Exports {#named-exports}
+
+`React.lazy` currently only supports default exports. If the module you want to import uses named exports, you can create an intermediate module that reexports it as the default. This ensures that tree shaking keeps working and that you don't pull in unused components.
+
+```js
+// ManyComponents.js
+export const MyComponent = /* ... */;
+export const MyUnusedComponent = /* ... */;
+```
+
+```js
+// MyComponent.js
+export { MyComponent as default } from "./ManyComponents.js";
+```
+
+```js
+// MyApp.js
+import React, { lazy } from 'react';
+const MyComponent = lazy(() => import("./MyComponent.js"));
+```
diff --git a/codebase-overview.md b/codebase-overview.md
new file mode 100644
index 000000000..091aff3aa
--- /dev/null
+++ b/codebase-overview.md
@@ -0,0 +1,226 @@
+---
+id: codebase-overview
+title: Codebase Overview
+layout: contributing
+permalink: docs/codebase-overview.html
+prev: how-to-contribute.html
+next: implementation-notes.html
+redirect_from:
+  - "contributing/codebase-overview.html"
+---
+
+This section will give you an overview of the React codebase organization, its conventions, and the implementation.
+
+If you want to [contribute to React](/docs/how-to-contribute.html) we hope that this guide will help you feel more comfortable making changes.
+
+We don't necessarily recommend any of these conventions in React apps. Many of them exist for historical reasons and might change with time.
+
+### External Dependencies {#external-dependencies}
+
+React has almost no external dependencies. Usually, a `require()` points to a file in React's own codebase. However, there are a few relatively rare exceptions.
+
+The [fbjs repository](https://github.com/facebook/fbjs) exists because React shares some small utilities with libraries like [Relay](https://github.com/facebook/relay), and we keep them in sync. We don't depend on equivalent small modules in the Node ecosystem because we want Facebook engineers to be able to make changes to them whenever necessary. None of the utilities inside fbjs are considered to be public API, and they are only intended for use by Facebook projects such as React.
+
+### Top-Level Folders {#top-level-folders}
+
+After cloning the [React repository](https://github.com/facebook/react), you will see a few top-level folders in it:
+
+* [`packages`](https://github.com/facebook/react/tree/master/packages) contains metadata (such as `package.json`) and the source code (`src` subdirectory) for all packages in the React repository. **If your change is related to the code, the `src` subdirectory of each package is where you'll spend most of your time.**
+* [`fixtures`](https://github.com/facebook/react/tree/master/fixtures) contains a few small React test applications for contributors.
+* `build` is the build output of React. It is not in the repository but it will appear in your React clone after you [build it](/docs/how-to-contribute.html#development-workflow) for the first time.
+
+The documentation is hosted [in a separate repository from React](https://github.com/reactjs/reactjs.org).
+
+There are a few other top-level folders but they are mostly used for the tooling and you likely won't ever encounter them when contributing.
+
+### Colocated Tests {#colocated-tests}
+
+We don't have a top-level directory for unit tests. Instead, we put them into a directory called `__tests__` relative to the files that they test.
+
+For example, a test for [`setInnerHTML.js`](https://github.com/facebook/react/blob/87724bd87506325fcaf2648c70fc1f43411a87be/src/renderers/dom/client/utils/setInnerHTML.js) is located in [`__tests__/setInnerHTML-test.js`](https://github.com/facebook/react/blob/87724bd87506325fcaf2648c70fc1f43411a87be/src/renderers/dom/client/utils/__tests__/setInnerHTML-test.js) right next to it.
+
+### Warnings and Invariants {#warnings-and-invariants}
+
+The React codebase uses the `warning` module to display warnings:
+
+```js
+var warning = require('warning');
+
+warning(
+  2 + 2 === 4,
+  'Math is not working today.'
+);
+```
+
+**The warning is shown when the `warning` condition is `false`.**
+
+One way to think about it is that the condition should reflect the normal situation rather than the exceptional one.
+
+It is a good idea to avoid spamming the console with duplicate warnings:
+
+```js
+var warning = require('warning');
+
+var didWarnAboutMath = false;
+if (!didWarnAboutMath) {
+  warning(
+    2 + 2 === 4,
+    'Math is not working today.'
+  );
+  didWarnAboutMath = true;
+}
+```
+
+Warnings are only enabled in development. In production, they are completely stripped out. If you need to forbid some code path from executing, use `invariant` module instead:
+
+```js
+var invariant = require('invariant');
+
+invariant(
+  2 + 2 === 4,
+  'You shall not pass!'
+);
+```
+
+**The invariant is thrown when the `invariant` condition is `false`.**
+
+"Invariant" is just a way of saying "this condition always holds true". You can think about it as making an assertion.
+
+It is important to keep development and production behavior similar, so `invariant` throws both in development and in production. The error messages are automatically replaced with error codes in production to avoid negatively affecting the byte size.
+
+### Development and Production {#development-and-production}
+
+You can use `__DEV__` pseudo-global variable in the codebase to guard development-only blocks of code.
+
+It is inlined during the compile step, and turns into `process.env.NODE_ENV !== 'production'` checks in the CommonJS builds.
+
+For standalone builds, it becomes `true` in the unminified build, and gets completely stripped out with the `if` blocks it guards in the minified build.
+
+```js
+if (__DEV__) {
+  // This code will only run in development.
+}
+```
+
+### Flow {#flow}
+
+We recently started introducing [Flow](https://flow.org/) checks to the codebase. Files marked with the `@flow` annotation in the license header comment are being typechecked.
+
+We accept pull requests [adding Flow annotations to existing code](https://github.com/facebook/react/pull/7600/files). Flow annotations look like this:
+
+```js
+ReactRef.detachRefs = function(
+  instance: ReactInstance,
+  element: ReactElement | string | number | null | false,
+): void {
+  // ...
+}
+```
+
+When possible, new code should use Flow annotations.
+You can run `yarn flow` locally to check your code with Flow.
+
+### Dynamic Injection {#dynamic-injection}
+
+React uses dynamic injection in some modules. While it is always explicit, it is still unfortunate because it hinders understanding of the code. The main reason it exists is because React originally only supported DOM as a target. React Native started as a React fork. We had to add dynamic injection to let React Native override some behaviors.
+
+You may see modules declaring their dynamic dependencies like this:
+
+```js
+// Dynamically injected
+var textComponentClass = null;
+
+// Relies on dynamically injected value
+function createInstanceForText(text) {
+  return new textComponentClass(text);
+}
+
+var ReactHostComponent = {
+  createInstanceForText,
+
+  // Provides an opportunity for dynamic injection
+  injection: {
+    injectTextComponentClass: function(componentClass) {
+      textComponentClass = componentClass;
+    },
+  },
+};
+
+module.exports = ReactHostComponent;
+```
+
+The `injection` field is not handled specially in any way. But by convention, it means that this module wants to have some (presumably platform-specific) dependencies injected into it at runtime.
+
+There are multiple injection points in the codebase. In the future, we intend to get rid of the dynamic injection mechanism and wire up all the pieces statically during the build.
+
+### Multiple Packages {#multiple-packages}
+
+React is a [monorepo](https://danluu.com/monorepo/). Its repository contains multiple separate packages so that their changes can be coordinated together, and issues live in one place.
+
+### React Core {#react-core}
+
+The "core" of React includes all the [top-level `React` APIs](/docs/top-level-api.html#react), for example:
+
+* `React.createElement()`
+* `React.Component`
+* `React.Children`
+
+**React core only includes the APIs necessary to define components.** It does not include the [reconciliation](/docs/reconciliation.html) algorithm or any platform-specific code. It is used both by React DOM and React Native components.
+
+The code for React core is located in [`packages/react`](https://github.com/facebook/react/tree/master/packages/react) in the source tree. It is available on npm as the [`react`](https://www.npmjs.com/package/react) package. The corresponding standalone browser build is called `react.js`, and it exports a global called `React`.
+
+### Renderers {#renderers}
+
+React was originally created for the DOM but it was later adapted to also support native platforms with [React Native](https://facebook.github.io/react-native/). This introduced the concept of "renderers" to React internals.
+
+**Renderers manage how a React tree turns into the underlying platform calls.**
+
+Renderers are also located in [`packages/`](https://github.com/facebook/react/tree/master/packages/):
+
+* [React DOM Renderer](https://github.com/facebook/react/tree/master/packages/react-dom) renders React components to the DOM. It implements [top-level `ReactDOM` APIs](/docs/react-dom.html) and is available as [`react-dom`](https://www.npmjs.com/package/react-dom) npm package. It can also be used as standalone browser bundle called `react-dom.js` that exports a `ReactDOM` global.
+* [React Native Renderer](https://github.com/facebook/react/tree/master/packages/react-native-renderer) renders React components to native views. It is used internally by React Native.
+* [React Test Renderer](https://github.com/facebook/react/tree/master/packages/react-test-renderer) renders React components to JSON trees. It is used by the [Snapshot Testing](https://facebook.github.io/jest/blog/2016/07/27/jest-14.html) feature of [Jest](https://facebook.github.io/jest) and is available as [react-test-renderer](https://www.npmjs.com/package/react-test-renderer) npm package.
+
+The only other officially supported renderer is [`react-art`](https://github.com/facebook/react/tree/master/packages/react-art). It used to be in a separate [GitHub repository](https://github.com/reactjs/react-art) but we moved it into the main source tree for now.
+
+>**Note:**
+>
+>Technically the [`react-native-renderer`](https://github.com/facebook/react/tree/master/packages/react-native-renderer) is a very thin layer that teaches React to interact with React Native implementation. The real platform-specific code managing the native views lives in the [React Native repository](https://github.com/facebook/react-native) together with its components.
+
+### Reconcilers {#reconcilers}
+
+Even vastly different renderers like React DOM and React Native need to share a lot of logic. In particular, the [reconciliation](/docs/reconciliation.html) algorithm should be as similar as possible so that declarative rendering, custom components, state, lifecycle methods, and refs work consistently across platforms.
+
+To solve this, different renderers share some code between them. We call this part of React a "reconciler". When an update such as `setState()` is scheduled, the reconciler calls `render()` on components in the tree and mounts, updates, or unmounts them.
+
+Reconcilers are not packaged separately because they currently have no public API. Instead, they are exclusively used by renderers such as React DOM and React Native.
+
+### Stack Reconciler {#stack-reconciler}
+
+The "stack" reconciler is the implementation powering React 15 and earlier. We have since stopped using it, but it is documented in detail in the [next section](/docs/implementation-notes.html).
+
+### Fiber Reconciler {#fiber-reconciler}
+
+The "fiber" reconciler is a new effort aiming to resolve the problems inherent in the stack reconciler and fix a few long-standing issues. It has been the default reconciler since React 16.
+
+Its main goals are:
+
+* Ability to split interruptible work in chunks.
+* Ability to prioritize, rebase and reuse work in progress.
+* Ability to yield back and forth between parents and children to support layout in React.
+* Ability to return multiple elements from `render()`.
+* Better support for error boundaries.
+
+You can read more about React Fiber Architecture [here](https://github.com/acdlite/react-fiber-architecture) and [here](https://blog.ag-grid.com/inside-fiber-an-in-depth-overview-of-the-new-reconciliation-algorithm-in-react). While it has shipped with React 16, the async features are not enabled by default yet.
+
+Its source code is located in [`packages/react-reconciler`](https://github.com/facebook/react/tree/master/packages/react-reconciler).
+
+### Event System {#event-system}
+
+React implements a synthetic event system which is agnostic of the renderers and works both with React DOM and React Native. Its source code is located in [`packages/react-events`](https://github.com/facebook/react/tree/master/packages/react-events).
+
+There is a [video with a deep code dive into it](https://www.youtube.com/watch?v=dRo_egw7tBc) (66 mins).
+
+### What Next? {#what-next}
+
+Read the [next section](/docs/implementation-notes.html) to learn about the pre-React 16 implementation of reconciler in more detail. We haven't documented the internals of the new reconciler yet.
diff --git a/components-and-props.md b/components-and-props.md
new file mode 100644
index 000000000..3cb5988c3
--- /dev/null
+++ b/components-and-props.md
@@ -0,0 +1,263 @@
+---
+id: components-and-props
+title: कौम्पोनॅन्ट तथा Props
+permalink: docs/components-and-props.html
+redirect_from:
+  - "docs/reusable-components.html"
+  - "docs/reusable-components-zh-CN.html"
+  - "docs/transferring-props.html"
+  - "docs/transferring-props-it-IT.html"
+  - "docs/transferring-props-ja-JP.html"
+  - "docs/transferring-props-ko-KR.html"
+  - "docs/transferring-props-zh-CN.html"
+  - "tips/props-in-getInitialState-as-anti-pattern.html"
+  - "tips/communicate-between-components.html"
+prev: rendering-elements.html
+next: state-and-lifecycle.html
+---
+कौम्पोनॅन्टस हमें UI को स्वतंत्र, पुन: प्रयोज्य टुकड़ो में विभाजित करने में मदद करते हैं, तथा हर हिस्से को अलग मानते है| यह पेज कौम्पोनॅन्टस का परिचय देता है| आपको [यहाँ पर विस्तृत कौम्पोनॅन्ट API reference](/docs/react-component.html) मिल जाएगी|
+
+सैद्धांतिक रूप से, कौम्पोनॅन्टस जावास्क्रिप्ट फंक्शन्स जैसे हैं| वे अर्बिट्ररी इनपुट्स स्वीकार करते है (जिसे "props" बुलाया जाता है ) और React एलिमेंट्स रीटर्न करते हैं जो वर्णन करती है की स्क्रीन पर क्या दिखना चाहिए|
+
+## फंक्शन्स तथा क्लास कौम्पोनॅन्टस {#function-and-class-components}
+
+कौम्पोनॅन्ट को परिभाषित करने कासबसे सरल तरीका एक जावास्क्रिप्ट फंक्शन् है:
+
+```js
+function Welcome(props) {
+  return <h1>नमस्ते, {props.name}</h1>;
+}
+```
+
+यह फंक्शन्स एक वैध React कौम्पोनॅन्ट है क्योकि यह एक अकेला "props" (जो properties का प्रतिनिधित्व करता है) ऑब्जेक्ट आर्गुमेंट डाटा सहित स्वीकार करता है और React एलिमेंट् वापस करता है| हम इन कौम्पोनॅन्टस को "फंक्शन्स कौम्पोनॅन्टस" कहते है क्योकि वो वाकई में एक जावास्क्रिप्ट फंक्शन् है|
+
+आप कौम्पोनॅन्ट को परिभाषित करने के लिए एक [ES6 class](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Classes) का उपयोग भी कर सकते हैं:
+
+```js
+class Welcome extends React.Component {
+  render() {
+    return <h1>नमस्ते, {this.props.name}</h1>;
+  }
+}
+```
+
+ऊपर के दोनों कौम्पोनॅन्ट React के दृष्टिकोण से बराबर है|
+
+क्लासेज की कुछ अतिरिक्त विशेषताएं भी हैं जिसकी हम चर्चा [अगले खंड](/docs/state-and-lifecycle.html) में करेंगे| तब तक, हम उनकी संक्षिप्तता के लिए फ़ंक्शन कौम्पोनॅन्टस का उपयोग करेंगे।
+
+## कौम्पोनॅन्ट रेंडरिंग {#rendering-a-component}
+
+इससे पहले, हमने केवल वही React एलिमेंट्स का सामना किया जो DOM टैग्स को दर्शाते थे:
+
+```js
+const element = <div />;
+```
+
+हालाँकि, एलिमेंट्स यूज़र डिफ़ाइंड कौम्पोनॅन्टस को भी दर्शा सकते है:
+
+```js
+const element = <Welcome name="नेहा" />;
+```
+
+जब कभी भी React एक एलिमेंट को यूजर-डिफाइंड कौम्पोनॅन्ट का प्रतिनिधित्व करते हुए देखता है, तुरंत ही इन कौम्पोनॅन्टs को एक ऑब्जेक्ट के रूप में JSX ऐट्रिब्यूट्स पास कर देता है| हम इस ऑब्जेक्ट को "props" कहते हैं|
+
+उदाहरण के लिए, यह कोड पेज पर रेंडर करता है "नमस्ते, नेहा":
+
+```js{1,5}
+function Welcome(props) {
+  return <h1>नमस्ते, {props.name}</h1>;
+}
+
+const element = <Welcome name="नेहा" />;
+ReactDOM.render(
+  element,
+  document.getElementById('root')
+);
+```
+
+[](codepen://components-and-props/rendering-a-component)
+
+चलिए देख़ते है इस उदाहरण में क्या होता है:
+
+1. हम `<Welcome name="नेहा" />` के द्वारा `ReactDOM.render()` को call karte है|
+2. React `Welcome` कौम्पोनॅन्ट को `name: 'नेहा'}` के साथ props के रूप मे call करती है|
+3. हमारा `Welcome` कौम्पोनॅन्ट परिणाम के तौर पर `<h1>नमस्ते, नेहा</h1>` एलिमेंट वापस लौटाता करता है|
+4. React DOM कुशलता पूर्वक DOM को `<h1>नमस्ते, नेहा</h1>` से अपडेट करता है|
+
+>**ध्यान दें:** कौम्पोनॅन्टस के नाम की शुरुवात हमेशा कैपिटल लेटर से होनी चाहिए|
+>
+>React उन कौम्पोनॅन्टस को DOM टैग्स मानता है जो लोअरकेस अक्षरों से स्टार्ट होते है| उदाहरण के लिए, `<div />` HTML div टैग्स को दर्शाता है, पर `<Welcome />` एक कौम्पोनॅन्ट को दर्शाता है और इसके लिए Welcome स्कोप में चाहिए होता है|
+>
+>इसके पीछे की सोच के बारे में और गहराई में जानने के लिए, कृपया [JSX गहराई में](/docs/jsx-in-depth.html#user-defined-components-must-be-capitalized) पढ़ें|
+
+## कौम्पोनॅन्टस की रचना {#composing-components}
+
+कौम्पोनॅन्टस अपने आउटपुट में अन्य कौम्पोनॅन्टस को रेफेर कर सकते हैं| यह हमें कौम्पोनॅन्ट अब्स्ट्रक्शंस का उपयोग विवरण के किसी भी स्तर के लिए करने देता है| एक बटन, एक फॉर्म, एक डायलॉग, एक स्क्रीन: इन React ऍप्स में सबको आमतौर पर कौम्पोनॅन्टस के रूप में व्यक्त किया जाता है|
+
+उदाहरण के लिए, हम एक `App` बना सकते हैं जो Welcome को कई बार रेंडर करती है:
+
+```js{8-10}
+function Welcome(props) {
+  return <h1>नमस्ते, {props.name}</h1>;
+}
+
+function App() {
+  return (
+    <div>
+      <Welcome name="नेहा" />
+      <Welcome name="चहल" />
+      <Welcome name="राम" />
+    </div>
+  );
+}
+
+ReactDOM.render(
+  <App />,
+  document.getElementById('root')
+);
+```
+
+[](codepen://components-and-props/composing-components)
+
+आम तौर पर, नए React ऍप्स के अंदर एक अकेला `App` कॉम्पोनेन्ट सबसे ऊपर होता है| हालाँकि, अगर आप React को एक मौजूदा ऐप में इंटेग्रेट करते है, आप बेहद छोटी चीज़ो के रेंडर्स से शुरुवात कर सकते हैं जैसे `Button` और धीरे-धीरे दृश्य पदानुक्रम के नीचे से ऊपर तक जा सकते है|
+
+## कौम्पोनॅन्टस निकालना {#extracting-components}
+
+कौम्पोनॅन्टस को छोटे छोटे कौम्पोनॅन्टस में विभाजित करने में संकोच ना करे|
+
+उदाहरण के लिए, इस `Comment` कौम्पोनॅन्ट पर विचार करें:
+
+```js
+function Comment(props) {
+  return (
+    <div className="Comment">
+      <div className="UserInfo">
+        <img className="Avatar"
+          src={props.author.avatarUrl}
+          alt={props.author.name}
+        />
+        <div className="UserInfo-name">
+          {props.author.name}
+        </div>
+      </div>
+      <div className="Comment-text">
+        {props.text}
+      </div>
+      <div className="Comment-date">
+        {formatDate(props.date)}
+      </div>
+    </div>
+  );
+}
+```
+
+[](codepen://components-and-props/extracting-components)
+
+यह `author` (एक ऑब्जेक्ट), `text` (एक string), और `date` (एक date) को props के द्वारा स्वीकार करता है, और सोशल मीडिया वेबसाइट पर एक टिप्पणी का वर्णन करता है|
+
+इस कौम्पोनॅन्टस की नेस्टिंग की वजह से बदलना मुश्किल हो सकता है, तथा इसके अकेले पार्ट्स का पुन: उपयोग करना भी कठिन है| चलिए इसमें से कुछ कौम्पोनॅन्टस निकालने की कोशिश करते हैं |
+
+सबसे पहले, हम निकालेंगे `Avatar`:
+
+```js{3-6}
+function Avatar(props) {
+  return (
+    <img className="Avatar"
+      src={props.user.avatarUrl}
+      alt={props.user.name}
+    />
+  );
+}
+```
+
+इस `Avatar` को जानने की जरूरत नहीं है कि यह एक `Comment` के अंदर रेंडर किया जा रहा है| इसलिए हमने इसके prop को `author` के बजाय एक ज्यादा
+सामान्य नाम `user` दिया है|
+
+Props का नामकरण हम कौम्पोनॅन्टस के अनुसार करने की सलाह देते हैं बजाय जिसमें इसका उपयोग किया जा रहा है उसके अनुसार हो|
+
+हम अब `Comment` को थोड़ा सरल कर सकते हैं:
+
+```js{5}
+function Comment(props) {
+  return (
+    <div className="Comment">
+      <div className="UserInfo">
+        <Avatar user={props.author} />
+        <div className="UserInfo-name">
+          {props.author.name}
+        </div>
+      </div>
+      <div className="Comment-text">
+        {props.text}
+      </div>
+      <div className="Comment-date">
+        {formatDate(props.date)}
+      </div>
+    </div>
+  );
+}
+```
+
+आगे, हम इसमें से एक `UserInfo` कौम्पोनॅन्टस निकालेंगे जो यूजर के नाम के पास `Avatar` को रेंडर करेगा:
+
+```js{3-8}
+function UserInfo(props) {
+  return (
+    <div className="UserInfo">
+      <Avatar user={props.user} />
+      <div className="UserInfo-name">
+        {props.user.name}
+      </div>
+    </div>
+  );
+}
+```
+
+यह हमे `Comment` को और भी ज्यादा आसान बनाने का मौका देता है:
+
+```js{4}
+function Comment(props) {
+  return (
+    <div className="Comment">
+      <UserInfo user={props.author} />
+      <div className="Comment-text">
+        {props.text}
+      </div>
+      <div className="Comment-date">
+        {formatDate(props.date)}
+      </div>
+    </div>
+  );
+}
+```
+
+[](codepen://components-and-props/extracting-components-continued)
+
+कौम्पोनॅन्टस निकालने के लिए पहली बार में असंतोषजनक काम लग सकता है, लेकिन पुन: प्रयोज्य कौम्पोनॅन्टस का एक पैलेट होना बड़े ऐप्स बनाने में सहायता करता है| यह एक अच्छी आदत है की अगर आपके UI के पार्ट कई बार इस्तेमाल किये गए हो (`Button`, `Panel`, `Avatar`), या अपने आप में काफी जटिल हो (`App`, `FeedStory`, `Comment`), तब इन परिस्तियों में यह पुन: प्रयोज्य कौम्पोनॅन्ट होने के लिए एक अच्छा उम्मीदवार होगा|
+
+## Props केवल-पढ़ने के लिए हैं {#props-are-read-only}
+
+जब भी आप एक कॉम्पोनेन्ट को [फंक्शन या क्लास के जैसे](#function-and-class-components) डिक्लेअर करें, इसे कभी भी खुदके props का संशोधित नहीं करना चाहिए| इस `sum` फंक्शन्स पर विचार करो:
+
+```js
+function sum(a, b) {
+  return a + b;
+}
+```
+
+ऐसे फंक्शन्स को हम ["pure"](https://en.wikipedia.org/wiki/Pure_function) कहते है क्योंकि वे अपने इनपुट को बदलने का प्रयास नहीं करते हैं, और हमेशा समान इनपुट के लिए समान परिणाम लौटाते हैं| 
+
+इसके विपरीत, यह फंक्शन्स impure है क्योंकि यह अपना इनपुट खुद बदलता है:
+
+```js
+function withdraw(account, amount) {
+  account.total -= amount;
+}
+```
+
+React बहुत लचीला है, लेकिन इसमें एक सख्त नियम है:
+
+**सारे React कौम्पोनॅन्टस को अपने props के अनुसार pure फंक्शन्स की तरह कार्य करना चाहिए|**
+
+
+बेशक, एप्लीकेशन UI गतिशील हैं और समय के साथ बदलते रहते हैं| अब [अगले सेक्शन](/docs/state-and-lifecycle.html) में, हम एक नई अवधारणा "state" पेश करेंगे| State React कौम्पोनॅन्टस को उपयोगकर्ता क्रियाओं, नेटवर्क प्रतिक्रियाएँ या कुछ भी, के जवाब में समय के साथ अपने आउटपुट को बदलने के लिए अनुमति देता है, बिना इस नियम का उल्लंघन किए|
diff --git a/composition-vs-inheritance.md b/composition-vs-inheritance.md
new file mode 100644
index 000000000..3a096484d
--- /dev/null
+++ b/composition-vs-inheritance.md
@@ -0,0 +1,172 @@
+---
+id: composition-vs-inheritance
+title: Composition vs Inheritance
+permalink: docs/composition-vs-inheritance.html
+redirect_from:
+  - "docs/multiple-components.html"
+prev: lifting-state-up.html
+next: thinking-in-react.html
+---
+
+React का कम्पोजीशन मॉडल शक्तिशाली है, और हम सलाह देते है कि आप कौम्पोनॅन्ट के बीच कोड के दुबारा प्रयोग के लिए इनहेरिटेंस कि जगह कम्पोजीशन का प्रयोग करे|
+
+इस भाग में, हम कुछ समस्याएं देखेंगे जहाँ React के नए डेवेलपर्स इनहेरिटेंस का प्रयोग करने की दिशा में जाते है, और यह भी देखेंगे की हम उनका समाधान कम्पोजीशन से कैसे कर सकते हैं|
+
+## कन्टेनमेंट {#containment}
+
+कुछ कौम्पोनॅन्ट अपने children के बारे में समय से पूर्व नहीं जान पाते| यह उन कौम्पोनॅन्ट्स के लिए आम बात है, जो सामान्य "boxes" दर्शाते है, जैसे `Sidebar` एवं `Dialog`।
+
+हम सलाह देते है कि, यह कौम्पोनॅन्ट्स विशेष `children` props का प्रयोग करे जिनसे children एलिमेंट्स को सीधा आउटपुट में पास करना मुमकिन होगा|
+
+```js{4}
+function FancyBorder(props) {
+  return (
+    <div className={'FancyBorder FancyBorder-' + props.color}>
+      {props.children}
+    </div>
+  );
+}
+```
+
+यह दूसरे कौम्पोनॅन्ट्स को JSX की nesting के माध्यम से मनमाना children पास करने देता है|
+
+```js{4-9}
+function WelcomeDialog() {
+  return (
+    <FancyBorder color="blue">
+      <h1 className="Dialog-title">
+        Welcome
+      </h1>
+      <p className="Dialog-message">
+        Thank you for visiting our spacecraft!
+      </p>
+    </FancyBorder>
+  );
+}
+```
+
+**[Try it on CodePen](https://codepen.io/gaearon/pen/ozqNOV?editors=0010)**
+
+`<FancyBorder>` JSX टैग के अंदर कुछ भी हो, वह `FancyBorder` कौम्पोनॅन्ट में `चिल्ड्रेंस` prop की तरह पास किया जा सकता है। क्यूंकि `FancyBorder`, `{props.children}` को `<div>` के अंदर रेंडर करता है, पास किये गए एल्मेंट्स अंतिम परिणाम में देखे जा सकते हैं|
+
+जबकि यह सामान्य नहीं है, कई बारी आपको एक कौम्पोनॅन्ट में एक से अधिक "holes" की आवश्यकता पढ़ सकती है। इन परिस्थियों में आप `children` की जगह अपनी कन्वेंशंस इजात कर सकते हैं:
+
+```js{5,8,18,21}
+function SplitPane(props) {
+  return (
+    <div className="SplitPane">
+      <div className="SplitPane-left">
+        {props.left}
+      </div>
+      <div className="SplitPane-right">
+        {props.right}
+      </div>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <SplitPane
+      left={
+        <Contacts />
+      }
+      right={
+        <Chat />
+      } />
+  );
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/gwZOJp?editors=0010)
+
+React एलिमेंट्स जैसे कि `<Contacts />` एवं `<Chat />` केवल एक ऑब्जेक्ट है, आप इनको props की तरह पास कर सकते है, जैसे आप बाक़ी डाटा को पास करते है । यह तरिका आपको और लाइब्रेरीज में "slot" की तरह लग रहा होगा परन्तु React में कोई रोक नहीं है कि आप props में क्या पास कर सकते हैं|
+
+## स्पेशलाइजेशन {#specialization}
+
+कई बार हम कौम्पोनॅन्ट्स को और कौम्पोनॅन्ट्स का "स्पेशल केसेस" समझते है। उदहारण के लिए हम कह सकते है `WelcomeDialog`, `Dialog` का विशेष केस है।
+
+React में यह भी कम्पोजीशन से उपलब्ध किया जाता है, जहाँ एक "विशिष्ट" कौम्पोनॅन्ट एक "सामान्य" कौम्पोनॅन्ट को रेंडर करता है और उसको props के द्वारा कॉन्फ़िगर करता है:
+
+```js{5,8,16-18}
+function Dialog(props) {
+  return (
+    <FancyBorder color="blue">
+      <h1 className="Dialog-title">
+        {props.title}
+      </h1>
+      <p className="Dialog-message">
+        {props.message}
+      </p>
+    </FancyBorder>
+  );
+}
+
+function WelcomeDialog() {
+  return (
+    <Dialog
+      title="Welcome"
+      message="Thank you for visiting our spacecraft!" />
+  );
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/kkEaOZ?editors=0010)
+
+कम्पोजीशन, classes वाले कौम्पोनॅन्ट के लिए भी समान रूप से काम करता है:
+
+```js{10,27-31}
+function Dialog(props) {
+  return (
+    <FancyBorder color="blue">
+      <h1 className="Dialog-title">
+        {props.title}
+      </h1>
+      <p className="Dialog-message">
+        {props.message}
+      </p>
+      {props.children}
+    </FancyBorder>
+  );
+}
+
+class SignUpDialog extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleChange = this.handleChange.bind(this);
+    this.handleSignUp = this.handleSignUp.bind(this);
+    this.state = {login: ''};
+  }
+
+  render() {
+    return (
+      <Dialog title="Mars Exploration Program"
+              message="How should we refer to you?">
+        <input value={this.state.login}
+               onChange={this.handleChange} />
+        <button onClick={this.handleSignUp}>
+          Sign Me Up!
+        </button>
+      </Dialog>
+    );
+  }
+
+  handleChange(e) {
+    this.setState({login: e.target.value});
+  }
+
+  handleSignUp() {
+    alert(`Welcome aboard, ${this.state.login}!`);
+  }
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/gwZbYa?editors=0010)
+
+## So What About Inheritance? {#so-what-about-inheritance}
+
+Facebook में हम हज़ारों React कौम्पोनॅन्ट्स का प्रयोग करते हैं, लेकिन हमे कोई भी ऐसा केस नहीं मिला जहाँ हम आपको कौम्पोनॅन्ट्स इन्हेरिटेंस हाईरारकीस बनाने की सलाह दे।
+
+Props एवं कम्पोजीशन आपको हर प्रकार का लचीलापन देता है ताकि आप अपने कौम्पोनॅन्ट का देख दिखाव एवं बिहेवियर एक सुरक्षित एवं एक्सप्लिसित तरीके से बदल सके। याद रखिये की एक कौम्पोनॅन्ट आरबिटीआरी props, जिसमे प्रिमिटिव वैल्यू हो, React एलिमेंट्स या फिर फंक्शन्स को स्वीकार कर सकता है।
+
+अगर आप अपने कौम्पोनॅन्ट के बीच कोई भी non-UI फंक्शनलिटी का प्रयोग करना चाहते है, हम सुझाव देंगे की आप एक अलग जावास्क्रिप्ट मॉड्यूल का प्रयोग करें क्योंकि कोई भी कौम्पोनॅन्ट इसको इम्पोर्ट कर सकता है एवं बिना इसको एक्सटेंड करे इसको फंक्शन, ऑब्जेक्ट, या फिर class की तरह प्रयोग कर सकता है|
\ No newline at end of file
diff --git a/conditional-rendering.md b/conditional-rendering.md
new file mode 100644
index 000000000..7df19bb98
--- /dev/null
+++ b/conditional-rendering.md
@@ -0,0 +1,243 @@
+---
+id: conditional-rendering
+title: Conditional Rendering
+permalink: docs/conditional-rendering.html
+prev: handling-events.html
+next: lists-and-keys.html
+redirect_from:
+  - "tips/false-in-jsx.html"
+---
+
+In React, you can create distinct components that encapsulate behavior you need. Then, you can render only some of them, depending on the state of your application.
+
+Conditional rendering in React works the same way conditions work in JavaScript. Use JavaScript operators like [`if`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/if...else) or the [conditional operator](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Operators/Conditional_Operator) to create elements representing the current state, and let React update the UI to match them.
+
+Consider these two components:
+
+```js
+function UserGreeting(props) {
+  return <h1>Welcome back!</h1>;
+}
+
+function GuestGreeting(props) {
+  return <h1>Please sign up.</h1>;
+}
+```
+
+We'll create a `Greeting` component that displays either of these components depending on whether a user is logged in:
+
+```javascript{3-7,11,12}
+function Greeting(props) {
+  const isLoggedIn = props.isLoggedIn;
+  if (isLoggedIn) {
+    return <UserGreeting />;
+  }
+  return <GuestGreeting />;
+}
+
+ReactDOM.render(
+  // Try changing to isLoggedIn={true}:
+  <Greeting isLoggedIn={false} />,
+  document.getElementById('root')
+);
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/ZpVxNq?editors=0011)
+
+This example renders a different greeting depending on the value of `isLoggedIn` prop.
+
+### Element Variables {#element-variables}
+
+You can use variables to store elements. This can help you conditionally render a part of the component while the rest of the output doesn't change.
+
+Consider these two new components representing Logout and Login buttons:
+
+```js
+function LoginButton(props) {
+  return (
+    <button onClick={props.onClick}>
+      Login
+    </button>
+  );
+}
+
+function LogoutButton(props) {
+  return (
+    <button onClick={props.onClick}>
+      Logout
+    </button>
+  );
+}
+```
+
+In the example below, we will create a [stateful component](/docs/state-and-lifecycle.html#adding-local-state-to-a-class) called `LoginControl`.
+
+It will render either `<LoginButton />` or `<LogoutButton />` depending on its current state. It will also render a `<Greeting />` from the previous example:
+
+```javascript{20-25,29,30}
+class LoginControl extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleLoginClick = this.handleLoginClick.bind(this);
+    this.handleLogoutClick = this.handleLogoutClick.bind(this);
+    this.state = {isLoggedIn: false};
+  }
+
+  handleLoginClick() {
+    this.setState({isLoggedIn: true});
+  }
+
+  handleLogoutClick() {
+    this.setState({isLoggedIn: false});
+  }
+
+  render() {
+    const isLoggedIn = this.state.isLoggedIn;
+    let button;
+
+    if (isLoggedIn) {
+      button = <LogoutButton onClick={this.handleLogoutClick} />;
+    } else {
+      button = <LoginButton onClick={this.handleLoginClick} />;
+    }
+
+    return (
+      <div>
+        <Greeting isLoggedIn={isLoggedIn} />
+        {button}
+      </div>
+    );
+  }
+}
+
+ReactDOM.render(
+  <LoginControl />,
+  document.getElementById('root')
+);
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/QKzAgB?editors=0010)
+
+While declaring a variable and using an `if` statement is a fine way to conditionally render a component, sometimes you might want to use a shorter syntax. There are a few ways to inline conditions in JSX, explained below.
+
+### Inline If with Logical && Operator {#inline-if-with-logical--operator}
+
+You may [embed any expressions in JSX](/docs/introducing-jsx.html#embedding-expressions-in-jsx) by wrapping them in curly braces. This includes the JavaScript logical `&&` operator. It can be handy for conditionally including an element:
+
+```js{6-10}
+function Mailbox(props) {
+  const unreadMessages = props.unreadMessages;
+  return (
+    <div>
+      <h1>Hello!</h1>
+      {unreadMessages.length > 0 &&
+        <h2>
+          You have {unreadMessages.length} unread messages.
+        </h2>
+      }
+    </div>
+  );
+}
+
+const messages = ['React', 'Re: React', 'Re:Re: React'];
+ReactDOM.render(
+  <Mailbox unreadMessages={messages} />,
+  document.getElementById('root')
+);
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/ozJddz?editors=0010)
+
+It works because in JavaScript, `true && expression` always evaluates to `expression`, and `false && expression` always evaluates to `false`.
+
+Therefore, if the condition is `true`, the element right after `&&` will appear in the output. If it is `false`, React will ignore and skip it.
+
+### Inline If-Else with Conditional Operator {#inline-if-else-with-conditional-operator}
+
+Another method for conditionally rendering elements inline is to use the JavaScript conditional operator [`condition ? true : false`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Operators/Conditional_Operator).
+
+In the example below, we use it to conditionally render a small block of text.
+
+```javascript{5}
+render() {
+  const isLoggedIn = this.state.isLoggedIn;
+  return (
+    <div>
+      The user is <b>{isLoggedIn ? 'currently' : 'not'}</b> logged in.
+    </div>
+  );
+}
+```
+
+It can also be used for larger expressions although it is less obvious what's going on:
+
+```js{5,7,9}
+render() {
+  const isLoggedIn = this.state.isLoggedIn;
+  return (
+    <div>
+      {isLoggedIn ? (
+        <LogoutButton onClick={this.handleLogoutClick} />
+      ) : (
+        <LoginButton onClick={this.handleLoginClick} />
+      )}
+    </div>
+  );
+}
+```
+
+Just like in JavaScript, it is up to you to choose an appropriate style based on what you and your team consider more readable. Also remember that whenever conditions become too complex, it might be a good time to [extract a component](/docs/components-and-props.html#extracting-components).
+
+### Preventing Component from Rendering {#preventing-component-from-rendering}
+
+In rare cases you might want a component to hide itself even though it was rendered by another component. To do this return `null` instead of its render output.
+
+In the example below, the `<WarningBanner />` is rendered depending on the value of the prop called `warn`. If the value of the prop is `false`, then the component does not render:
+
+```javascript{2-4,29}
+function WarningBanner(props) {
+  if (!props.warn) {
+    return null;
+  }
+
+  return (
+    <div className="warning">
+      Warning!
+    </div>
+  );
+}
+
+class Page extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {showWarning: true};
+    this.handleToggleClick = this.handleToggleClick.bind(this);
+  }
+
+  handleToggleClick() {
+    this.setState(state => ({
+      showWarning: !state.showWarning
+    }));
+  }
+
+  render() {
+    return (
+      <div>
+        <WarningBanner warn={this.state.showWarning} />
+        <button onClick={this.handleToggleClick}>
+          {this.state.showWarning ? 'Hide' : 'Show'}
+        </button>
+      </div>
+    );
+  }
+}
+
+ReactDOM.render(
+  <Page />,
+  document.getElementById('root')
+);
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/Xjoqwm?editors=0010)
+
+Returning `null` from a component's `render` method does not affect the firing of the component's lifecycle methods. For instance `componentDidUpdate` will still be called.
diff --git a/content/community/conferences.md b/content/community/conferences.md
index 0e129a5b2..77ccf89d2 100644
--- a/content/community/conferences.md
+++ b/content/community/conferences.md
@@ -12,6 +12,11 @@ Do you know of a local React.js conference? Add it here! (Please keep the list c
 
 ## Upcoming Conferences {#upcoming-conferences}
 
+### React Summit 2019 {#reactsummit2019}
+November 30, 2019 in Lagos, Nigeria
+
+[Website](https://reactsummit2019.splashthat.com) -[Twitter](https://twitter.com/react_summit)
+
 ### React Conf 2019 {#react-conf-2019}
 October 24-25, 2019 in Henderson, Nevada USA
 
@@ -37,6 +42,11 @@ February 27 & 28, 2020 in Sydney, Australia
 
 [Website](https://reactconfau.com/) - [Twitter](https://twitter.com/reactconfau) - [Facebook](https://www.facebook.com/reactconfau) - [Instagram](https://www.instagram.com/reactconfau/)
 
+### React Summit Amsterdam 2020 {#react-summit-2020}
+April 15-17, 2020 in Amsterdam, The Netherlands
+
+[Website](https://reactsummit.com) - [Twitter](https://twitter.com/reactamsterdam) - [Facebook](https://www.facebook.com/reactamsterdam) - [Videos](https://youtube.com/c/ReactConferences)
+
 ### Render-Atlanta 2020 {#render-atlanta-2020}
 May 4-6, 2020. Atlanta, GA, USA.
 
@@ -90,7 +100,7 @@ February 22 & 23 in San Francisco, CA
 ### React Amsterdam 2016 {#react-amsterdam-2016}
 April 16 in Amsterdam, The Netherlands
 
-[Website](https://react.amsterdam) - [Twitter](https://twitter.com/reactamsterdam) - [Facebook](https://www.facebook.com/reactamsterdam) - [Videos](https://youtube.com/c/ReactConferences)
+[Website](https://reactsummit.com) - [Twitter](https://twitter.com/reactamsterdam) - [Facebook](https://www.facebook.com/reactamsterdam) - [Videos](https://youtube.com/c/ReactConferences)
 
 ### ReactEurope 2016 {#reacteurope-2016}
 June 2 & 3 in Paris, France
@@ -140,7 +150,7 @@ March 28th at the [QEII Centre, London](http://qeiicentre.london/)
 ### React Amsterdam 2017 {#react-amsterdam-2017}
 April 21st in Amsterdam, The Netherlands
 
-[Website](https://react.amsterdam) - [Twitter](https://twitter.com/reactamsterdam) - [Videos](https://youtube.com/c/ReactConferences)
+[Website](https://reactsummit.com) - [Twitter](https://twitter.com/reactamsterdam) - [Videos](https://youtube.com/c/ReactConferences)
 
 ### ReactEurope 2017 {#reacteurope-2017}
 May 18th & 19th in Paris, France
@@ -245,7 +255,7 @@ March 31 in Kiev, Ukraine
 ### React Amsterdam 2018 {#react-amsterdam-2018}
 April 13 in Amsterdam, The Netherlands
 
-[Website](https://react.amsterdam) - [Twitter](https://twitter.com/reactamsterdam) - [Facebook](https://www.facebook.com/reactamsterdam)
+[Website](https://reactsummit.com) - [Twitter](https://twitter.com/reactamsterdam) - [Facebook](https://www.facebook.com/reactamsterdam)
 
 ### React Finland 2018 {#react-finland-2018}
 April 24-26 in Helsinki, Finland
@@ -350,7 +360,7 @@ April 4-5, 2019 in Kraków, Poland
 ### React Amsterdam 2019 {#react-amsterdam-2019}
 April 12, 2019 in Amsterdam, The Netherlands
 
-[Website](https://react.amsterdam) - [Twitter](https://twitter.com/reactamsterdam) - [Facebook](https://www.facebook.com/reactamsterdam) - [Videos](https://youtube.com/c/ReactConferences)
+[Website](https://reactsummit.com) - [Twitter](https://twitter.com/reactamsterdam) - [Facebook](https://www.facebook.com/reactamsterdam) - [Videos](https://youtube.com/c/ReactConferences)
 
 ### React Finland 2019 {#react-finland-2019}
 April 24-26 in Helsinki, Finland
diff --git a/content/community/meetups.md b/content/community/meetups.md
index 074440cff..78bcf1dd6 100644
--- a/content/community/meetups.md
+++ b/content/community/meetups.md
@@ -131,6 +131,8 @@ Do you have a local React.js meetup? Add it here! (Please keep the list alphabet
 * [Austin, TX - ReactJS](https://www.meetup.com/ReactJS-Austin-Meetup/)
 * [Boston, MA - ReactJS](https://www.meetup.com/ReactJS-Boston/)
 * [Boston, MA - React Native](https://www.meetup.com/Boston-React-Native-Meetup/)
+* [Charlotte, NC - ReactJS](https://www.meetup.com/ReactJS-Charlotte/)
+* [Charlotte, NC - React Native](https://www.meetup.com/cltreactnative/)
 * [Chicago, IL - ReactJS](https://www.meetup.com/React-Chicago/)
 * [Columbus, OH - ReactJS](https://www.meetup.com/ReactJS-Columbus-meetup/)
 * [Dallas, TX - ReactJS](https://www.meetup.com/ReactDallas/)
diff --git a/content/community/tools-ui-components.md b/content/community/tools-ui-components.md
index fe3d4953d..7b0e59ce9 100644
--- a/content/community/tools-ui-components.md
+++ b/content/community/tools-ui-components.md
@@ -82,3 +82,4 @@ permalink: community/ui-components.html
 * **[KendoReact](https://www.telerik.com/kendo-react-ui/)**: UI for React Developers.
 * **[Mobiscroll React UI Components](https://mobiscroll.com/react)** Mobile UI Controls for the Productive React Developer.
 * **[React UI Toolkit](https://react-ui-tools.com/)**: 115+ professionally maintainted UI components ranging from a robust grid to charts and more. Try for FREE and build React apps faster.
+* **[Flatlogic React Admin Templates](https://flatlogic.com/templates/react)** 5+ Paid and Free React Admin templates with a lot of components to speed up web development. No jQuery.
diff --git a/content/docs/faq-structure.md b/content/docs/faq-structure.md
index 4241a04dd..0290bc814 100644
--- a/content/docs/faq-structure.md
+++ b/content/docs/faq-structure.md
@@ -6,13 +6,13 @@ layout: docs
 category: FAQ
 ---
 
-### Is there a recommended way to structure React projects? {#is-there-a-recommended-way-to-structure-react-projects}
+### क्या React प्रोजेक्ट्स की संरचना का अनुशंसित तरीका है? {#is-there-a-recommended-way-to-structure-react-projects}
 
-React doesn't have opinions on how you put files into folders. That said there are a few common approaches popular in the ecosystem you may want to consider.
+React को यह नहीं पता कि आप फ़ाइलों को फ़ोल्डर्स में कैसे डालते हैं। आप जिस इकोसिस्टम पर विचार करना चाहते हैं, उसमें कुछ सामान्य दृष्टिकोण लोकप्रिय हैं।
 
-#### Grouping by features or routes {#grouping-by-features-or-routes}
+#### फीचर्स या रआउट्स द्वारा समूहीकरण {#grouping-by-features-or-routes}
 
-One common way to structure projects is locate CSS, JS, and tests together inside folders grouped by feature or route.
+प्रोजेक्ट्स की संरचना का एक सामान्य तरीका CSS, JS का पता लगाकर, फ़ीचर या रआउट्स द्वारा समूहीकृत फ़ोल्डर के अंदर एक साथ परीक्षण करना हैं।
 
 ```
 common/
@@ -35,11 +35,11 @@ profile/
   ProfileAPI.js
 ```
 
-The definition of a "feature" is not universal, and it is up to you to choose the granularity. If you can't come up with a list of top-level folders, you can ask the users of your product what major parts it consists of, and use their mental model as a blueprint.
+"फीचर" की परिभाषा सार्वभौमिक नहीं है, और यह आप पर निर्भर है कि आप किस विवरण का चयन करते हैं। यदि आप शीर्ष स्तर के फ़ोल्डरों की सूची के साथ नहीं आ सकते हैं, तो आप अपने उत्पाद के उपयोगकर्ताओं से पूछ सकते हैं कि इसमें कौन से प्रमुख भाग हैं, और उनके मानसिक मॉडल का ब्लूप्रिंट के रूप में उपयोग कर सकते हैं।
 
-#### Grouping by file type {#grouping-by-file-type}
+#### फ़ाइल प्रकार द्वारा समूहीकरण {#grouping-by-file-type}
 
-Another popular way to structure projects is to group similar files together, for example:
+ प्रोजेक्ट्स के लिए एक और लोकप्रिय तरीका समान फ़ाइलों को एक साथ समूहित करना है, उदाहरण के लिए:
 
 ```
 api/
@@ -59,16 +59,16 @@ components/
   ProfileHeader.css
 ```
 
-Some people also prefer to go further, and separate components into different folders depending on their role in the application. For example, [Atomic Design](http://bradfrost.com/blog/post/atomic-web-design/) is a design methodology built on this principle. Remember that it's often more productive to treat such methodologies as helpful examples rather than strict rules to follow.
+कुछ लोग गहराई में जाना पसंद करते हैं, और कॉम्पोनेन्ट को उनकी भूमिका के आधार पर विभिन्न फ़ोल्डर्स में अलग अलग करते हैं। उदाहरण के लिए, [एटॉमिक डिजाइन](http://bradfrost.com/blog/post/atomic-web-design/) इस सिद्धांत पर निर्मित एक डिजाइन पद्धति है। याद रखें कि इस तरह की कार्यप्रणालियों को व्यवहार में लाने के लिए अक्सर सख्त नियमों के बजाय सहायक उदाहरणों का उपयोग करना अधिक लाभदायक होता है।
 
-#### Avoid too much nesting {#avoid-too-much-nesting}
+#### बहुत ज्यादा नेस्टिंग से बचें {#avoid-too-much-nesting}
 
-There are many pain points associated with deep directory nesting in JavaScript projects. It becomes harder to write relative imports between them, or to update those imports when the files are moved. Unless you have a very compelling reason to use a deep folder structure, consider limiting yourself to a maximum of three or four nested folders within a single project. Of course, this is only a recommendation, and it may not be relevant to your project.
+जावास्क्रिप्ट प्रोजेक्ट्स में डीप डायरेक्टरी नेस्टिंग को लेकर काफी समस्याएं हैं। जब फाइल्स को मूव कराते हैं तब उनके बीच सापेक्ष इम्पोर्ट्स लिखना या उन इम्पोर्ट्स को अपडेट करना मुश्किल हो जाता है। जब तक आपके पास एक गहरी फ़ोल्डर संरचना का उपयोग करने के लिए एक बहुत ही सम्मोहक कारण नहीं है, तब तक अपने आप को एक ही प्रोजेक्ट के भीतर अधिकतम तीन या चार नेस्टेड फ़ोल्डरों तक सीमित करने पर विचार करें। बेशक, यह केवल एक सिफारिश है, और यह आपके प्रोजेक्ट के लिए प्रासंगिक नहीं हो सकता है।
 
-#### Don't overthink it {#dont-overthink-it}
+####  ज़रूरत से ज्यादा न सोचें {#dont-overthink-it}
 
-If you're just starting a project, [don't spend more than five minutes](https://en.wikipedia.org/wiki/Analysis_paralysis) on choosing a file structure. Pick any of the above approaches (or come up with your own) and start writing code! You'll likely want to rethink it anyway after you've written some real code.
+यदि आप एक प्रोजेक्ट शुरू कर रहें हैं, तो फ़ाइल संरचना चुनने के लिए [पांच मिनट से अधिक समय न लगाएं](https://en.wikipedia.org/wiki/Analysis_paralysis) । 
+उपरोक्त किसी भी दृष्टिकोण को चुनें (या अपने स्वयं के साथ आएं) और कोड लिखना शुरू करें! आपके द्वारा कुछ वास्तविक कोड लिखे जाने के बाद, आप इसे वैसे भी पुनर्विचार करना चाहेंगे।
+यदि आप पूरी तरह से फंसे हुए महसूस करते हैं, तो सभी फ़ाइलों को एक फ़ोल्डर में रखकर शुरू करें। आखिरकार यह काफी बड़ा हो जाएगा कि आप कुछ फ़ाइलों को बाकी हिस्सों से अलग करना चाहेंगे। उस समय तक आपको यह पर्याप्त ज्ञान होगा कि आप यह बता सकेंगे की आप किन फ़ाइलों पर अक्सर काम करते हैं। सामान्य तौर पर, फाइलों को रखना एक अच्छा विचार है जो अक्सर एक-दूसरे के करीब बदल जाते हैं। इस सिद्धांत को "कोलोकेशन" कहा जाता है।
 
-If you feel completely stuck, start by keeping all files in a single folder. Eventually it will grow large enough that you will want to separate some files from the rest. By that time you'll have enough knowledge to tell which files you edit together most often. In general, it is a good idea to keep files that often change together close to each other. This principle is called "colocation".
-
-As projects grow larger, they often use a mix of both of the above approaches in practice. So choosing the "right" one in the beginning isn't very important.
+जैसे-जैसे प्रोजेक्ट बड़े होते हैं, वे अक्सर अभ्यास में उपरोक्त दोनों दृष्टिकोणों के मिश्रण का उपयोग करते हैं। इसलिए शुरुआत में किसी एक को "सही" चुनना बहुत महत्वपूर्ण नहीं है।
diff --git a/content/docs/uncontrolled-components.md b/content/docs/uncontrolled-components.md
index 10b6eab28..54b729e96 100644
--- a/content/docs/uncontrolled-components.md
+++ b/content/docs/uncontrolled-components.md
@@ -4,7 +4,7 @@ title: Uncontrolled Components
 permalink: docs/uncontrolled-components.html
 ---
 
-In most cases, we recommend using [controlled components](/docs/forms.html) to implement forms. In a controlled component, form data is handled by a React component. The alternative is uncontrolled components, where form data is handled by the DOM itself.
+In most cases, we recommend using [controlled components](/docs/forms.html#controlled-components) to implement forms. In a controlled component, form data is handled by a React component. The alternative is uncontrolled components, where form data is handled by the DOM itself.
 
 To write an uncontrolled component, instead of writing an event handler for every state update, you can [use a ref](/docs/refs-and-the-dom.html) to get form values from the DOM.
 
diff --git a/context.md b/context.md
new file mode 100644
index 000000000..b16c5d7c2
--- /dev/null
+++ b/context.md
@@ -0,0 +1,266 @@
+---
+id: context
+title: Context
+permalink: docs/context.html
+---
+
+Context provides a way to pass data through the component tree without having to pass props down manually at every level.
+
+In a typical React application, data is passed top-down (parent to child) via props, but this can be cumbersome for certain types of props (e.g. locale preference, UI theme) that are required by many components within an application. Context provides a way to share values like these between components without having to explicitly pass a prop through every level of the tree.
+
+- [When to Use Context](#when-to-use-context)
+- [Before You Use Context](#before-you-use-context)
+- [API](#api)
+  - [React.createContext](#reactcreatecontext)
+  - [Context.Provider](#contextprovider)
+  - [Class.contextType](#classcontexttype)
+  - [Context.Consumer](#contextconsumer)
+  - [Context.displayName](#contextdisplayname)
+- [Examples](#examples)
+  - [Dynamic Context](#dynamic-context)
+  - [Updating Context from a Nested Component](#updating-context-from-a-nested-component)
+  - [Consuming Multiple Contexts](#consuming-multiple-contexts)
+- [Caveats](#caveats)
+- [Legacy API](#legacy-api)
+
+## When to Use Context {#when-to-use-context}
+
+Context is designed to share data that can be considered "global" for a tree of React components, such as the current authenticated user, theme, or preferred language. For example, in the code below we manually thread through a "theme" prop in order to style the Button component:
+
+`embed:context/motivation-problem.js`
+
+Using context, we can avoid passing props through intermediate elements:
+
+`embed:context/motivation-solution.js`
+
+## Before You Use Context {#before-you-use-context}
+
+Context is primarily used when some data needs to be accessible by *many* components at different nesting levels. Apply it sparingly because it makes component reuse more difficult.
+
+**If you only want to avoid passing some props through many levels, [component composition](/docs/composition-vs-inheritance.html) is often a simpler solution than context.**
+
+For example, consider a `Page` component that passes a `user` and `avatarSize` prop several levels down so that deeply nested `Link` and `Avatar` components can read it:
+
+```js
+<Page user={user} avatarSize={avatarSize} />
+// ... which renders ...
+<PageLayout user={user} avatarSize={avatarSize} />
+// ... which renders ...
+<NavigationBar user={user} avatarSize={avatarSize} />
+// ... which renders ...
+<Link href={user.permalink}>
+  <Avatar user={user} size={avatarSize} />
+</Link>
+```
+
+It might feel redundant to pass down the `user` and `avatarSize` props through many levels if in the end only the `Avatar` component really needs it. It's also annoying that whenever the `Avatar` component needs more props from the top, you have to add them at all the intermediate levels too.
+
+One way to solve this issue **without context** is to [pass down the `Avatar` component itself](/docs/composition-vs-inheritance.html#containment) so that the intermediate components don't need to know about the `user` or `avatarSize` props:
+
+```js
+function Page(props) {
+  const user = props.user;
+  const userLink = (
+    <Link href={user.permalink}>
+      <Avatar user={user} size={props.avatarSize} />
+    </Link>
+  );
+  return <PageLayout userLink={userLink} />;
+}
+
+// Now, we have:
+<Page user={user} avatarSize={avatarSize} />
+// ... which renders ...
+<PageLayout userLink={...} />
+// ... which renders ...
+<NavigationBar userLink={...} />
+// ... which renders ...
+{props.userLink}
+```
+
+With this change, only the top-most Page component needs to know about the `Link` and `Avatar` components' use of `user` and `avatarSize`.
+
+This *inversion of control* can make your code cleaner in many cases by reducing the amount of props you need to pass through your application and giving more control to the root components. However, this isn't the right choice in every case: moving more complexity higher in the tree makes those higher-level components more complicated and forces the lower-level components to be more flexible than you may want.
+
+You're not limited to a single child for a component. You may pass multiple children, or even have multiple separate "slots" for children, [as documented here](/docs/composition-vs-inheritance.html#containment):
+
+```js
+function Page(props) {
+  const user = props.user;
+  const content = <Feed user={user} />;
+  const topBar = (
+    <NavigationBar>
+      <Link href={user.permalink}>
+        <Avatar user={user} size={props.avatarSize} />
+      </Link>
+    </NavigationBar>
+  );
+  return (
+    <PageLayout
+      topBar={topBar}
+      content={content}
+    />
+  );
+}
+```
+
+This pattern is sufficient for many cases when you need to decouple a child from its immediate parents. You can take it even further with [render props](/docs/render-props.html) if the child needs to communicate with the parent before rendering.
+
+However, sometimes the same data needs to be accessible by many components in the tree, and at different nesting levels. Context lets you "broadcast" such data, and changes to it, to all components below. Common examples where using context might be simpler than the alternatives include managing the current locale, theme, or a data cache. 
+
+## API {#api}
+
+### `React.createContext` {#reactcreatecontext}
+
+```js
+const MyContext = React.createContext(defaultValue);
+```
+
+Creates a Context object. When React renders a component that subscribes to this Context object it will read the current context value from the closest matching `Provider` above it in the tree.
+
+The `defaultValue` argument is **only** used when a component does not have a matching Provider above it in the tree. This can be helpful for testing components in isolation without wrapping them. Note: passing `undefined` as a Provider value does not cause consuming components to use `defaultValue`.
+
+### `Context.Provider` {#contextprovider}
+
+```js
+<MyContext.Provider value={/* some value */}>
+```
+
+Every Context object comes with a Provider React component that allows consuming components to subscribe to context changes.
+
+Accepts a `value` prop to be passed to consuming components that are descendants of this Provider. One Provider can be connected to many consumers. Providers can be nested to override values deeper within the tree.
+
+All consumers that are descendants of a Provider will re-render whenever the Provider's `value` prop changes. The propagation from Provider to its descendant consumers is not subject to the `shouldComponentUpdate` method, so the consumer is updated even when an ancestor component bails out of the update.
+
+Changes are determined by comparing the new and old values using the same algorithm as [`Object.is`](//developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is#Description). 
+
+> Note
+> 
+> The way changes are determined can cause some issues when passing objects as `value`: see [Caveats](#caveats).
+
+### `Class.contextType` {#classcontexttype}
+
+```js
+class MyClass extends React.Component {
+  componentDidMount() {
+    let value = this.context;
+    /* perform a side-effect at mount using the value of MyContext */
+  }
+  componentDidUpdate() {
+    let value = this.context;
+    /* ... */
+  }
+  componentWillUnmount() {
+    let value = this.context;
+    /* ... */
+  }
+  render() {
+    let value = this.context;
+    /* render something based on the value of MyContext */
+  }
+}
+MyClass.contextType = MyContext;
+```
+
+The `contextType` property on a class can be assigned a Context object created by [`React.createContext()`](#reactcreatecontext). This lets you consume the nearest current value of that Context type using `this.context`. You can reference this in any of the lifecycle methods including the render function.
+
+> Note:
+>
+> You can only subscribe to a single context using this API. If you need to read more than one see [Consuming Multiple Contexts](#consuming-multiple-contexts).
+>
+> If you are using the experimental [public class fields syntax](https://babeljs.io/docs/plugins/transform-class-properties/), you can use a **static** class field to initialize your `contextType`.
+
+
+```js
+class MyClass extends React.Component {
+  static contextType = MyContext;
+  render() {
+    let value = this.context;
+    /* render something based on the value */
+  }
+}
+```
+
+### `Context.Consumer` {#contextconsumer}
+
+```js
+<MyContext.Consumer>
+  {value => /* render something based on the context value */}
+</MyContext.Consumer>
+```
+
+A React component that subscribes to context changes. This lets you subscribe to a context within a [function component](/docs/components-and-props.html#function-and-class-components).
+
+Requires a [function as a child](/docs/render-props.html#using-props-other-than-render). The function receives the current context value and returns a React node. The `value` argument passed to the function will be equal to the `value` prop of the closest Provider for this context above in the tree. If there is no Provider for this context above, the `value` argument will be equal to the `defaultValue` that was passed to `createContext()`.
+
+> Note
+> 
+> For more information about the 'function as a child' pattern, see [render props](/docs/render-props.html).
+
+### `Context.displayName` {#contextdisplayname}
+
+Context object accepts a `displayName` string property. React DevTools uses this string to determine what to display for the context.
+
+For example, the following component will appear as MyDisplayName in the DevTools:
+
+```js{2}
+const MyContext = React.createContext(/* some value */);
+MyContext.displayName = 'MyDisplayName';
+
+<MyContext.Provider> // "MyDisplayName.Provider" in DevTools
+<MyContext.Consumer> // "MyDisplayName.Consumer" in DevTools
+```
+
+## Examples {#examples}
+
+### Dynamic Context {#dynamic-context}
+
+A more complex example with dynamic values for the theme:
+
+**theme-context.js**
+`embed:context/theme-detailed-theme-context.js`
+
+**themed-button.js**
+`embed:context/theme-detailed-themed-button.js`
+
+**app.js**
+`embed:context/theme-detailed-app.js`
+
+### Updating Context from a Nested Component {#updating-context-from-a-nested-component}
+
+It is often necessary to update the context from a component that is nested somewhere deeply in the component tree. In this case you can pass a function down through the context to allow consumers to update the context:
+
+**theme-context.js**
+`embed:context/updating-nested-context-context.js`
+
+**theme-toggler-button.js**
+`embed:context/updating-nested-context-theme-toggler-button.js`
+
+**app.js**
+`embed:context/updating-nested-context-app.js`
+
+### Consuming Multiple Contexts {#consuming-multiple-contexts}
+
+To keep context re-rendering fast, React needs to make each context consumer a separate node in the tree. 
+
+`embed:context/multiple-contexts.js`
+
+If two or more context values are often used together, you might want to consider creating your own render prop component that provides both.
+
+## Caveats {#caveats}
+
+Because context uses reference identity to determine when to re-render, there are some gotchas that could trigger unintentional renders in consumers when a provider's parent re-renders. For example, the code below will re-render all consumers every time the Provider re-renders because a new object is always created for `value`:
+
+`embed:context/reference-caveats-problem.js`
+
+
+To get around this, lift the value into the parent's state:
+
+`embed:context/reference-caveats-solution.js`
+
+## Legacy API {#legacy-api}
+
+> Note
+> 
+> React previously shipped with an experimental context API. The old API will be supported in all 16.x releases, but applications using it should migrate to the new version. The legacy API will be removed in a future major React version. Read the [legacy context docs here](/docs/legacy-context.html).
+ 
diff --git a/create-a-new-react-app.md b/create-a-new-react-app.md
new file mode 100644
index 000000000..ec1c273b4
--- /dev/null
+++ b/create-a-new-react-app.md
@@ -0,0 +1,94 @@
+---
+id: create-a-new-react-app
+title: Create a New React App
+permalink: docs/create-a-new-react-app.html
+redirect_from:
+  - "docs/add-react-to-a-new-app.html"
+prev: add-react-to-a-website.html
+next: cdn-links.html
+---
+
+Use an integrated toolchain for the best user and developer experience.
+
+This page describes a few popular React toolchains which help with tasks like:
+
+* Scaling to many files and components.
+* Using third-party libraries from npm.
+* Detecting common mistakes early.
+* Live-editing CSS and JS in development.
+* Optimizing the output for production.
+
+The toolchains recommended on this page **don't require configuration to get started**.
+
+## You Might Not Need a Toolchain {#you-might-not-need-a-toolchain}
+
+If you don't experience the problems described above or don't feel comfortable using JavaScript tools yet, consider [adding React as a plain `<script>` tag on an HTML page](/docs/add-react-to-a-website.html), optionally [with JSX](/docs/add-react-to-a-website.html#optional-try-react-with-jsx).
+
+This is also **the easiest way to integrate React into an existing website.** You can always add a larger toolchain if you find it helpful!
+
+## Recommended Toolchains {#recommended-toolchains}
+
+The React team primarily recommends these solutions:
+
+- If you're **learning React** or **creating a new [single-page](/docs/glossary.html#single-page-application) app,** use [Create React App](#create-react-app).
+- If you're building a **server-rendered website with Node.js,** try [Next.js](#nextjs).
+- If you're building a **static content-oriented website,** try [Gatsby](#gatsby).
+- If you're building a **component library** or **integrating with an existing codebase**, try [More Flexible Toolchains](#more-flexible-toolchains).
+
+### Create React App {#create-react-app}
+
+[Create React App](https://github.com/facebookincubator/create-react-app) is a comfortable environment for **learning React**, and is the best way to start building **a new [single-page](/docs/glossary.html#single-page-application) application** in React.
+
+It sets up your development environment so that you can use the latest JavaScript features, provides a nice developer experience, and optimizes your app for production. You’ll need to have Node >= 8.10 and npm >= 5.6 on your machine. To create a project, run:
+
+```bash
+npx create-react-app my-app
+cd my-app
+npm start
+```
+
+>Note
+>
+>`npx` on the first line is not a typo -- it's a [package runner tool that comes with npm 5.2+](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b).
+
+Create React App doesn't handle backend logic or databases; it just creates a frontend build pipeline, so you can use it with any backend you want. Under the hood, it uses [Babel](https://babeljs.io/) and [webpack](https://webpack.js.org/), but you don't need to know anything about them.
+
+When you're ready to deploy to production, running `npm run build` will create an optimized build of your app in the `build` folder. You can learn more about Create React App [from its README](https://github.com/facebookincubator/create-react-app#create-react-app--) and the [User Guide](https://facebook.github.io/create-react-app/).
+
+### Next.js {#nextjs}
+
+[Next.js](https://nextjs.org/) is a popular and lightweight framework for **static and server‑rendered applications** built with React. It includes **styling and routing solutions** out of the box, and assumes that you're using [Node.js](https://nodejs.org/) as the server environment.
+
+Learn Next.js from [its official guide](https://nextjs.org/learn/).
+
+### Gatsby {#gatsby}
+
+[Gatsby](https://www.gatsbyjs.org/) is the best way to create **static websites** with React. It lets you use React components, but outputs pre-rendered HTML and CSS to guarantee the fastest load time.
+
+Learn Gatsby from [its official guide](https://www.gatsbyjs.org/docs/) and a [gallery of starter kits](https://www.gatsbyjs.org/docs/gatsby-starters/).
+
+### More Flexible Toolchains {#more-flexible-toolchains}
+
+The following toolchains offer more flexibility and choice. We recommend them to more experienced users:
+
+- **[Neutrino](https://neutrinojs.org/)** combines the power of [webpack](https://webpack.js.org/) with the simplicity of presets, and includes a preset for [React apps](https://neutrinojs.org/packages/react/) and [React components](https://neutrinojs.org/packages/react-components/).
+
+- **[nwb](https://github.com/insin/nwb)** is particularly great for [publishing React components for npm](https://github.com/insin/nwb/blob/master/docs/guides/ReactComponents.md#developing-react-components-and-libraries-with-nwb). It [can be used](https://github.com/insin/nwb/blob/master/docs/guides/ReactApps.md#developing-react-apps-with-nwb) for creating React apps, too. 
+
+- **[Parcel](https://parceljs.org/)** is a fast, zero configuration web application bundler that [works with React](https://parceljs.org/recipes.html#react).
+
+- **[Razzle](https://github.com/jaredpalmer/razzle)** is a server-rendering framework that doesn't require any configuration, but offers more flexibility than Next.js.
+
+## Creating a Toolchain from Scratch {#creating-a-toolchain-from-scratch}
+
+A JavaScript build toolchain typically consists of:
+
+* A **package manager**, such as [Yarn](https://yarnpkg.com/) or [npm](https://www.npmjs.com/). It lets you take advantage of a vast ecosystem of third-party packages, and easily install or update them.
+
+* A **bundler**, such as [webpack](https://webpack.js.org/) or [Parcel](https://parceljs.org/). It lets you write modular code and bundle it together into small packages to optimize load time.
+
+* A **compiler** such as [Babel](https://babeljs.io/). It lets you write modern JavaScript code that still works in older browsers.
+
+If you prefer to set up your own JavaScript toolchain from scratch, [check out this guide](https://blog.usejournal.com/creating-a-react-app-from-scratch-f3c693b84658) that re-creates some of the Create React App functionality.
+
+Don't forget to ensure your custom toolchain [is correctly set up for production](/docs/optimizing-performance.html#use-the-production-build).
diff --git a/cross-origin-errors.md b/cross-origin-errors.md
new file mode 100644
index 000000000..915ee0d63
--- /dev/null
+++ b/cross-origin-errors.md
@@ -0,0 +1,41 @@
+---
+id: cross-origin-errors
+title: Cross-origin Errors
+permalink: docs/cross-origin-errors.html
+---
+
+> Note:
+>
+> The following section applies only to the development mode of React. Error handling in production mode is done with regular try/catch statements.
+
+In [development mode](/docs/optimizing-performance.html), React uses a global `error` event handler to preserve the "pause on exceptions" behavior of browser DevTools. It also logs errors to the developer console.
+
+If an error is thrown from a [different origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) the browser will mask its details and React will not be able to log the original error message. This is a security precaution taken by browsers to avoid leaking sensitive information.
+
+You can simplify the development/debugging process by ensuring that errors are thrown with a same-origin policy. Below are some common causes of cross-origin errors and ways to address them.
+
+### CDN {#cdn}
+
+When loading React (or other libraries that might throw errors) from a CDN, add the [`crossorigin`](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) attribute to your `<script>` tags:
+
+```html
+<script crossorigin src="..."></script>
+```
+
+Also ensure the CDN responds with the `Access-Control-Allow-Origin: *` HTTP header:
+
+![Access-Control-Allow-Origin: *](../images/docs/cdn-cors-header.png)
+
+### Webpack {#webpack}
+
+#### Source maps {#source-maps}
+
+Some JavaScript bundlers may wrap the application code with `eval` statements in development. (For example Webpack will do this if [`devtool`](https://webpack.js.org/configuration/devtool/) is set to any value containing the word "eval".) This may cause errors to be treated as cross-origin.
+
+If you use Webpack, we recommend using the `cheap-module-source-map` setting in development to avoid this problem.
+
+#### Code splitting {#code-splitting}
+
+If your application is split into multiple bundles, these bundles may be loaded using JSONP. This may cause errors thrown in the code of these bundles to be treated as cross-origin.
+
+To resolve this, use the [`crossOriginLoading`](https://webpack.js.org/configuration/output/#output-crossoriginloading) setting in development to add the `crossorigin` attribute to the `<script>` tags generated for the JSONP requests.
diff --git a/design-principles.md b/design-principles.md
new file mode 100644
index 000000000..9e10f39d5
--- /dev/null
+++ b/design-principles.md
@@ -0,0 +1,163 @@
+---
+id: design-principles
+title: Design Principles
+layout: contributing
+permalink: docs/design-principles.html
+prev: implementation-notes.html
+redirect_from:
+  - "contributing/design-principles.html"
+---
+
+We wrote this document so that you have a better idea of how we decide what React does and what React doesn't do, and what our development philosophy is like. While we are excited to see community contributions, we are not likely to choose a path that violates one or more of these principles.
+
+>**Note:**
+>
+>This document assumes a strong understanding of React. It describes the design principles of *React itself*, not React components or applications.
+>
+>For an introduction to React, check out [Thinking in React](/docs/thinking-in-react.html) instead.
+
+### Composition {#composition}
+
+The key feature of React is composition of components. Components written by different people should work well together. It is important to us that you can add functionality to a component without causing rippling changes throughout the codebase.
+
+For example, it should be possible to introduce some local state into a component without changing any of the components using it. Similarly, it should be possible to add some initialization and teardown code to any component when necessary.
+
+There is nothing "bad" about using state or lifecycle methods in components. Like any powerful feature, they should be used in moderation, but we have no intention to remove them. On the contrary, we think they are integral parts of what makes React useful. We might enable [more functional patterns](https://github.com/reactjs/react-future/tree/master/07%20-%20Returning%20State) in the future, but both local state and lifecycle methods will be a part of that model.
+
+Components are often described as "just functions" but in our view they need to be more than that to be useful. In React, components describe any composable behavior, and this includes rendering, lifecycle, and state. Some external libraries like [Relay](https://facebook.github.io/relay/) augment components with other responsibilities such as describing data dependencies. It is possible that those ideas might make it back into React too in some form.
+
+### Common Abstraction {#common-abstraction}
+
+In general we [resist adding features](https://www.youtube.com/watch?v=4anAwXYqLG8) that can be implemented in userland. We don't want to bloat your apps with useless library code. However, there are exceptions to this.
+
+For example, if React didn't provide support for local state or lifecycle methods, people would create custom abstractions for them. When there are multiple abstractions competing, React can't enforce or take advantage of the properties of either of them. It has to work with the lowest common denominator.
+
+This is why sometimes we add features to React itself. If we notice that many components implement a certain feature in incompatible or inefficient ways, we might prefer to bake it into React. We don't do it lightly. When we do it, it's because we are confident that raising the abstraction level benefits the whole ecosystem. State, lifecycle methods, cross-browser event normalization are good examples of this.
+
+We always discuss such improvement proposals with the community. You can find some of those discussions by the ["big picture"](https://github.com/facebook/react/issues?q=is:open+is:issue+label:"Type:+Big+Picture") label on the React issue tracker.
+
+### Escape Hatches {#escape-hatches}
+
+React is pragmatic. It is driven by the needs of the products written at Facebook. While it is influenced by some paradigms that are not yet fully mainstream such as functional programming, staying accessible to a wide range of developers with different skills and experience levels is an explicit goal of the project.
+
+If we want to deprecate a pattern that we don't like, it is our responsibility to consider all existing use cases for it and [educate the community about the alternatives](/blog/2016/07/13/mixins-considered-harmful.html) before we deprecate it. If some pattern that is useful for building apps is hard to express in a declarative way, we will [provide an imperative API](/docs/more-about-refs.html) for it. If we can't figure out a perfect API for something that we found necessary in many apps, we will [provide a temporary subpar working API](/docs/legacy-context.html) as long as it is possible to get rid of it later and it leaves the door open for future improvements.
+
+### Stability {#stability}
+
+We value API stability. At Facebook, we have more than 50 thousand components using React. Many other companies, including [Twitter](https://twitter.com/) and [Airbnb](https://www.airbnb.com/), are also heavy users of React. This is why we are usually reluctant to change public APIs or behavior.
+
+However we think stability in the sense of "nothing changes" is overrated. It quickly turns into stagnation. Instead, we prefer the stability in the sense of "It is heavily used in production, and when something changes, there is a clear (and preferably automated) migration path."
+
+When we deprecate a pattern, we study its internal usage at Facebook and add deprecation warnings. They let us assess the impact of the change. Sometimes we back out if we see that it is too early, and we need to think more strategically about getting the codebases to the point where they are ready for this change.
+
+If we are confident that the change is not too disruptive and the migration strategy is viable for all use cases, we release the deprecation warning to the open source community. We are closely in touch with many users of React outside of Facebook, and we monitor popular open source projects and guide them in fixing those deprecations.
+
+Given the sheer size of the Facebook React codebase, successful internal migration is often a good indicator that other companies won't have problems either. Nevertheless sometimes people point out additional use cases we haven't thought of, and we add escape hatches for them or rethink our approach.
+
+We don't deprecate anything without a good reason. We recognize that sometimes deprecations warnings cause frustration but we add them because deprecations clean up the road for the improvements and new features that we and many people in the community consider valuable.
+
+For example, we added a [warning about unknown DOM props](/warnings/unknown-prop.html) in React 15.2.0. Many projects were affected by this. However fixing this warning is important so that we can introduce the support for [custom attributes](https://github.com/facebook/react/issues/140) to React. There is a reason like this behind every deprecation that we add.
+
+When we add a deprecation warning, we keep it for the rest of the current major version, and [change the behavior in the next major version](/blog/2016/02/19/new-versioning-scheme.html). If there is a lot of repetitive manual work involved, we release a [codemod](https://www.youtube.com/watch?v=d0pOgY8__JM) script that automates most of the change. Codemods enable us to move forward without stagnation in a massive codebase, and we encourage you to use them as well.
+
+You can find the codemods that we released in the [react-codemod](https://github.com/reactjs/react-codemod) repository.
+
+### Interoperability {#interoperability}
+
+We place high value in interoperability with existing systems and gradual adoption. Facebook has a massive non-React codebase. Its website uses a mix of a server-side component system called XHP, internal UI libraries that came before React, and React itself. It is important to us that any product team can [start using React for a small feature](https://www.youtube.com/watch?v=BF58ZJ1ZQxY) rather than rewrite their code to bet on it.
+
+This is why React provides escape hatches to work with mutable models, and tries to work well together with other UI libraries. You can wrap an existing imperative UI into a declarative component, and vice versa. This is crucial for gradual adoption.
+
+### Scheduling {#scheduling}
+
+Even when your components are described as functions, when you use React you don't call them directly. Every component returns a [description of what needs to be rendered](/blog/2015/12/18/react-components-elements-and-instances.html#elements-describe-the-tree), and that description may include both user-written components like `<LikeButton>` and platform-specific components like `<div>`. It is up to React to "unroll" `<LikeButton>` at some point in the future and actually apply changes to the UI tree according to the render results of the components recursively.
+
+This is a subtle distinction but a powerful one. Since you don't call that component function but let React call it, it means React has the power to delay calling it if necessary. In its current implementation React walks the tree recursively and calls render functions of the whole updated tree during a single tick. However in the future it might start [delaying some updates to avoid dropping frames](https://github.com/facebook/react/issues/6170).
+
+This is a common theme in React design. Some popular libraries implement the "push" approach where computations are performed when the new data is available. React, however, sticks to the "pull" approach where computations can be delayed until necessary.
+
+React is not a generic data processing library. It is a library for building user interfaces. We think that it is uniquely positioned in an app to know which computations are relevant right now and which are not.
+
+If something is offscreen, we can delay any logic related to it. If data is arriving faster than the frame rate, we can coalesce and batch updates. We can prioritize work coming from user interactions (such as an animation caused by a button click) over less important background work (such as rendering new content just loaded from the network) to avoid dropping frames.
+
+To be clear, we are not taking advantage of this right now. However the freedom to do something like this is why we prefer to have control over scheduling, and why `setState()` is asynchronous. Conceptually, we think of it as "scheduling an update".
+
+The control over scheduling would be harder for us to gain if we let the user directly compose views with a "push" based paradigm common in some variations of [Functional Reactive Programming](https://en.wikipedia.org/wiki/Functional_reactive_programming). We want to own the "glue" code.
+
+It is a key goal for React that the amount of the user code that executes before yielding back into React is minimal. This ensures that React retains the capability to schedule and split work in chunks according to what it knows about the UI.
+
+There is an internal joke in the team that React should have been called "Schedule" because React does not want to be fully "reactive".
+
+### Developer Experience {#developer-experience}
+
+Providing a good developer experience is important to us.
+
+For example, we maintain [React DevTools](https://github.com/facebook/react-devtools) which let you inspect the React component tree in Chrome and Firefox. We have heard that it brings a big productivity boost both to the Facebook engineers and to the community.
+
+We also try to go an extra mile to provide helpful developer warnings. For example, React warns you in development if you nest tags in a way that the browser doesn't understand, or if you make a common typo in the API. Developer warnings and the related checks are the main reason why the development version of React is slower than the production version.
+
+The usage patterns that we see internally at Facebook help us understand what the common mistakes are, and how to prevent them early. When we add new features, we try to anticipate the common mistakes and warn about them.
+
+We are always looking out for ways to improve the developer experience. We love to hear your suggestions and accept your contributions to make it even better.
+
+### Debugging {#debugging}
+
+When something goes wrong, it is important that you have breadcrumbs to trace the mistake to its source in the codebase. In React, props and state are those breadcrumbs.
+
+If you see something wrong on the screen, you can open React DevTools, find the component responsible for rendering, and then see if the props and state are correct. If they are, you know that the problem is in the component’s `render()` function, or some function that is called by `render()`. The problem is isolated.
+
+If the state is wrong, you know that the problem is caused by one of the `setState()` calls in this file. This, too, is relatively simple to locate and fix because usually there are only a few `setState()` calls in a single file.
+
+If the props are wrong, you can traverse the tree up in the inspector, looking for the component that first "poisoned the well" by passing bad props down.
+
+This ability to trace any UI to the data that produced it in the form of current props and state is very important to React. It is an explicit design goal that state is not "trapped" in closures and combinators, and is available to React directly.
+
+While the UI is dynamic, we believe that synchronous `render()` functions of props and state turn debugging from guesswork into a boring but finite procedure. We would like to preserve this constraint in React even though it makes some use cases, like complex animations, harder.
+
+### Configuration {#configuration}
+
+We find global runtime configuration options to be problematic.
+
+For example, it is occasionally requested that we implement a function like `React.configure(options)` or `React.register(component)`. However this poses multiple problems, and we are not aware of good solutions to them.
+
+What if somebody calls such a function from a third-party component library? What if one React app embeds another React app, and their desired configurations are incompatible? How can a third-party component specify that it requires a particular configuration? We think that global configuration doesn't work well with composition. Since composition is central to React, we don't provide global configuration in code.
+
+We do, however, provide some global configuration on the build level. For example, we provide separate development and production builds. We may also [add a profiling build](https://github.com/facebook/react/issues/6627) in the future, and we are open to considering other build flags.
+
+### Beyond the DOM {#beyond-the-dom}
+
+We see the value of React in the way it allows us to write components that have fewer bugs and compose together well. DOM is the original rendering target for React but [React Native](https://facebook.github.io/react-native/) is just as important both to Facebook and the community.
+
+Being renderer-agnostic is an important design constraint of React. It adds some overhead in the internal representations. On the other hand, any improvements to the core translate across platforms.
+
+Having a single programming model lets us form engineering teams around products instead of platforms. So far the tradeoff has been worth it for us.
+
+### Implementation {#implementation}
+
+We try to provide elegant APIs where possible. We are much less concerned with the implementation being elegant. The real world is far from perfect, and to a reasonable extent we prefer to put the ugly code into the library if it means the user does not have to write it. When we evaluate new code, we are looking for an implementation that is correct, performant and affords a good developer experience. Elegance is secondary.
+
+We prefer boring code to clever code. Code is disposable and often changes. So it is important that it [doesn't introduce new internal abstractions unless absolutely necessary](https://youtu.be/4anAwXYqLG8?t=13m9s). Verbose code that is easy to move around, change and remove is preferred to elegant code that is prematurely abstracted and hard to change.
+
+### Optimized for Tooling {#optimized-for-tooling}
+
+Some commonly used APIs have verbose names. For example, we use `componentDidMount()` instead of `didMount()` or `onMount()`. This is [intentional](https://github.com/reactjs/react-future/issues/40#issuecomment-142442124). The goal is to make the points of interaction with the library highly visible.
+
+In a massive codebase like Facebook, being able to search for uses of specific APIs is very important. We value distinct verbose names, and especially for the features that should be used sparingly. For example, `dangerouslySetInnerHTML` is hard to miss in a code review.
+
+Optimizing for search is also important because of our reliance on [codemods](https://www.youtube.com/watch?v=d0pOgY8__JM) to make breaking changes. We want it to be easy and safe to apply vast automated changes across the codebase, and unique verbose names help us achieve this. Similarly, distinctive names make it easy to write custom [lint rules](https://github.com/yannickcr/eslint-plugin-react) about using React without worrying about potential false positives.
+
+[JSX](/docs/introducing-jsx.html) plays a similar role. While it is not required with React, we use it extensively at Facebook both for aesthetic and pragmatic reasons.
+
+In our codebase, JSX provides an unambiguous hint to the tools that they are dealing with a React element tree. This makes it possible to add build-time optimizations such as [hoisting constant elements](https://babeljs.io/docs/en/babel-plugin-transform-react-constant-elements/), safely lint and codemod internal component usage, and [include JSX source location](https://github.com/facebook/react/pull/6771) into the warnings.
+
+### Dogfooding {#dogfooding}
+
+We try our best to address the problems raised by the community. However we are likely to prioritize the issues that people are *also* experiencing internally at Facebook. Perhaps counter-intuitively, we think this is the main reason why the community can bet on React.
+
+Heavy internal usage gives us the confidence that React won't disappear tomorrow. React was created at Facebook to solve its problems. It brings tangible business value to the company and is used in many of its products. [Dogfooding](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) it means that our vision stays sharp and we have a focused direction going forward.
+
+This doesn't mean that we ignore the issues raised by the community. For example, we added support for [web components](/docs/webcomponents.html) and [SVG](https://github.com/facebook/react/pull/6243) to React even though we don't rely on either of them internally. We are actively [listening to your pain points](https://github.com/facebook/react/issues/2686) and [address them](/blog/2016/07/11/introducing-reacts-error-code-system.html) to the best of our ability. The community is what makes React special to us, and we are honored to contribute back.
+
+After releasing many open source projects at Facebook, we have learned that trying to make everyone happy at the same time produced projects with poor focus that didn't grow well. Instead, we found that picking a small audience and focusing on making them happy brings a positive net effect. That's exactly what we did with React, and so far solving the problems encountered by Facebook product teams has translated well to the open source community.
+
+The downside of this approach is that sometimes we fail to give enough focus to the things that Facebook teams don't have to deal with, such as the "getting started" experience. We are acutely aware of this, and we are thinking of how to improve in a way that would benefit everyone in the community without making the same mistakes we did with open source projects before.
diff --git a/error-boundaries.md b/error-boundaries.md
new file mode 100644
index 000000000..a259c0645
--- /dev/null
+++ b/error-boundaries.md
@@ -0,0 +1,166 @@
+---
+id: error-boundaries
+title: Error Boundaries
+permalink: docs/error-boundaries.html
+---
+
+In the past, JavaScript errors inside components used to corrupt React’s internal state and cause it to [emit](https://github.com/facebook/react/issues/4026) [cryptic](https://github.com/facebook/react/issues/6895) [errors](https://github.com/facebook/react/issues/8579) on next renders. These errors were always caused by an earlier error in the application code, but React did not provide a way to handle them gracefully in components, and could not recover from them.
+
+
+## Introducing Error Boundaries {#introducing-error-boundaries}
+
+A JavaScript error in a part of the UI shouldn’t break the whole app. To solve this problem for React users, React 16 introduces a new concept of an “error boundary”.
+
+Error boundaries are React components that **catch JavaScript errors anywhere in their child component tree, log those errors, and display a fallback UI** instead of the component tree that crashed. Error boundaries catch errors during rendering, in lifecycle methods, and in constructors of the whole tree below them.
+
+> Note
+>
+> Error boundaries do **not** catch errors for:
+>
+> * Event handlers ([learn more](#how-about-event-handlers))
+> * Asynchronous code (e.g. `setTimeout` or `requestAnimationFrame` callbacks)
+> * Server side rendering
+> * Errors thrown in the error boundary itself (rather than its children)
+
+A class component becomes an error boundary if it defines either (or both) of the lifecycle methods [`static getDerivedStateFromError()`](/docs/react-component.html#static-getderivedstatefromerror) or [`componentDidCatch()`](/docs/react-component.html#componentdidcatch). Use `static getDerivedStateFromError()` to render a fallback UI after an error has been thrown. Use `componentDidCatch()` to log error information.
+
+```js{7-10,12-15,18-21}
+class ErrorBoundary extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(error) {
+    // Update state so the next render will show the fallback UI.
+    return { hasError: true };
+  }
+
+  componentDidCatch(error, errorInfo) {
+    // You can also log the error to an error reporting service
+    logErrorToMyService(error, errorInfo);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      // You can render any custom fallback UI
+      return <h1>Something went wrong.</h1>;
+    }
+
+    return this.props.children; 
+  }
+}
+```
+
+Then you can use it as a regular component:
+
+```js
+<ErrorBoundary>
+  <MyWidget />
+</ErrorBoundary>
+```
+
+Error boundaries work like a JavaScript `catch {}` block, but for components. Only class components can be error boundaries. In practice, most of the time you’ll want to declare an error boundary component once and use it throughout your application.
+
+Note that **error boundaries only catch errors in the components below them in the tree**. An error boundary can’t catch an error within itself. If an error boundary fails trying to render the error message, the error will propagate to the closest error boundary above it. This, too, is similar to how catch {} block works in JavaScript.
+
+## Live Demo {#live-demo}
+
+Check out [this example of declaring and using an error boundary](https://codepen.io/gaearon/pen/wqvxGa?editors=0010) with [React 16](/blog/2017/09/26/react-v16.0.html).
+
+
+## Where to Place Error Boundaries {#where-to-place-error-boundaries}
+
+The granularity of error boundaries is up to you. You may wrap top-level route components to display a “Something went wrong” message to the user, just like server-side frameworks often handle crashes. You may also wrap individual widgets in an error boundary to protect them from crashing the rest of the application.
+
+
+## New Behavior for Uncaught Errors {#new-behavior-for-uncaught-errors}
+
+This change has an important implication. **As of React 16, errors that were not caught by any error boundary will result in unmounting of the whole React component tree.**
+
+We debated this decision, but in our experience it is worse to leave corrupted UI in place than to completely remove it. For example, in a product like Messenger leaving the broken UI visible could lead to somebody sending a message to the wrong person. Similarly, it is worse for a payments app to display a wrong amount than to render nothing.
+
+This change means that as you migrate to React 16, you will likely uncover existing crashes in your application that have been unnoticed before. Adding error boundaries lets you provide better user experience when something goes wrong.
+
+For example, Facebook Messenger wraps content of the sidebar, the info panel, the conversation log, and the message input into separate error boundaries. If some component in one of these UI areas crashes, the rest of them remain interactive.
+
+We also encourage you to use JS error reporting services (or build your own) so that you can learn about unhandled exceptions as they happen in production, and fix them.
+
+
+## Component Stack Traces {#component-stack-traces}
+
+React 16 prints all errors that occurred during rendering to the console in development, even if the application accidentally swallows them. In addition to the error message and the JavaScript stack, it also provides component stack traces. Now you can see where exactly in the component tree the failure has happened:
+
+<img src="../images/docs/error-boundaries-stack-trace.png" style="max-width:100%" alt="Error caught by Error Boundary component">
+
+You can also see the filenames and line numbers in the component stack trace. This works by default in [Create React App](https://github.com/facebookincubator/create-react-app) projects:
+
+<img src="../images/docs/error-boundaries-stack-trace-line-numbers.png" style="max-width:100%" alt="Error caught by Error Boundary component with line numbers">
+
+If you don’t use Create React App, you can add [this plugin](https://www.npmjs.com/package/babel-plugin-transform-react-jsx-source) manually to your Babel configuration. Note that it’s intended only for development and **must be disabled in production**.
+
+> Note
+>
+> Component names displayed in the stack traces depend on the [`Function.name`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name) property. If you support older browsers and devices which may not yet provide this natively (e.g. IE 11), consider including a `Function.name` polyfill in your bundled application, such as [`function.name-polyfill`](https://github.com/JamesMGreene/Function.name). Alternatively, you may explicitly set the [`displayName`](/docs/react-component.html#displayname) property on all your components.
+
+
+## How About try/catch? {#how-about-trycatch}
+
+`try` / `catch` is great but it only works for imperative code:
+
+```js
+try {
+  showButton();
+} catch (error) {
+  // ...
+}
+```
+
+However, React components are declarative and specify *what* should be rendered:
+
+```js
+<Button />
+```
+
+Error boundaries preserve the declarative nature of React, and behave as you would expect. For example, even if an error occurs in a `componentDidUpdate` method caused by a `setState` somewhere deep in the tree, it will still correctly propagate to the closest error boundary.
+
+## How About Event Handlers? {#how-about-event-handlers}
+
+Error boundaries **do not** catch errors inside event handlers.
+
+React doesn't need error boundaries to recover from errors in event handlers. Unlike the render method and lifecycle methods, the event handlers don't happen during rendering. So if they throw, React still knows what to display on the screen.
+
+If you need to catch an error inside event handler, use the regular JavaScript `try` / `catch` statement:
+
+```js{9-13,17-20}
+class MyComponent extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = { error: null };
+    this.handleClick = this.handleClick.bind(this);
+  }
+
+  handleClick() {
+    try {
+      // Do something that could throw
+    } catch (error) {
+      this.setState({ error });
+    }
+  }
+
+  render() {
+    if (this.state.error) {
+      return <h1>Caught an error.</h1>
+    }
+    return <div onClick={this.handleClick}>Click Me</div>
+  }
+}
+```
+
+Note that the above example is demonstrating regular JavaScript behavior and doesn't use error boundaries.
+
+## Naming Changes from React 15 {#naming-changes-from-react-15}
+
+React 15 included a very limited support for error boundaries under a different method name: `unstable_handleError`. This method no longer works, and you will need to change it to `componentDidCatch` in your code starting from the first 16 beta release.
+
+For this change, we’ve provided a [codemod](https://github.com/reactjs/react-codemod#error-boundaries) to automatically migrate your code.
diff --git a/error-decoder.md b/error-decoder.md
new file mode 100644
index 000000000..68191bfff
--- /dev/null
+++ b/error-decoder.md
@@ -0,0 +1,9 @@
+---
+id: error-decoder
+title: Error Decoder
+permalink: docs/error-decoder.html
+---
+
+In the minified production build of React, we avoid sending down full error messages in order to reduce the number of bytes sent over the wire.
+
+We highly recommend using the development build locally when debugging your app since it tracks additional debug info and provides helpful warnings about potential problems in your apps, but if you encounter an exception while using the production build, this page will reassemble the original text of the error.
\ No newline at end of file
diff --git a/faq-ajax.md b/faq-ajax.md
new file mode 100644
index 000000000..102e1c07e
--- /dev/null
+++ b/faq-ajax.md
@@ -0,0 +1,84 @@
+---
+id: faq-ajax
+title: AJAX and APIs
+permalink: docs/faq-ajax.html
+layout: docs
+category: FAQ
+---
+
+### How can I make an AJAX call? {#how-can-i-make-an-ajax-call}
+
+You can use any AJAX library you like with React. Some popular ones are [Axios](https://github.com/axios/axios), [jQuery AJAX](https://api.jquery.com/jQuery.ajax/), and the browser built-in [window.fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
+
+### Where in the component lifecycle should I make an AJAX call? {#where-in-the-component-lifecycle-should-i-make-an-ajax-call}
+
+You should populate data with AJAX calls in the [`componentDidMount`](/docs/react-component.html#mounting) lifecycle method. This is so you can use `setState` to update your component when the data is retrieved.
+
+### Example: Using AJAX results to set local state {#example-using-ajax-results-to-set-local-state}
+
+The component below demonstrates how to make an AJAX call in `componentDidMount` to populate local component state. 
+
+The example API returns a JSON object like this:
+
+```
+{
+  "items": [
+    { "id": 1, "name": "Apples",  "price": "$2" },
+    { "id": 2, "name": "Peaches", "price": "$5" }
+  ] 
+}
+```
+
+```jsx
+class MyComponent extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      error: null,
+      isLoaded: false,
+      items: []
+    };
+  }
+
+  componentDidMount() {
+    fetch("https://api.example.com/items")
+      .then(res => res.json())
+      .then(
+        (result) => {
+          this.setState({
+            isLoaded: true,
+            items: result.items
+          });
+        },
+        // Note: it's important to handle errors here
+        // instead of a catch() block so that we don't swallow
+        // exceptions from actual bugs in components.
+        (error) => {
+          this.setState({
+            isLoaded: true,
+            error
+          });
+        }
+      )
+  }
+
+  render() {
+    const { error, isLoaded, items } = this.state;
+    if (error) {
+      return <div>Error: {error.message}</div>;
+    } else if (!isLoaded) {
+      return <div>Loading...</div>;
+    } else {
+      return (
+        <ul>
+          {items.map(item => (
+            <li key={item.name}>
+              {item.name} {item.price}
+            </li>
+          ))}
+        </ul>
+      );
+    }
+  }
+}
+```
diff --git a/faq-build.md b/faq-build.md
new file mode 100644
index 000000000..6114433e8
--- /dev/null
+++ b/faq-build.md
@@ -0,0 +1,32 @@
+---
+id: faq-build
+title: Babel, JSX, and Build Steps
+permalink: docs/faq-build.html
+layout: docs
+category: FAQ
+---
+
+### क्या मुझे React के साथ JSX का उपयोग करने की आवश्यकता है? {#do-i-need-to-use-jsx-with-react}
+
+नहीं! अधिक जानने के लिए ["JSX के बिना React"](/docs/react-without-jsx.html) देखें ।
+
+### क्या मुझे React के साथ ES6 (+) का उपयोग करने की आवश्यकता है? {#do-i-need-to-use-es6--with-react}
+
+नहीं! अधिक जानने के लिए ["ES6 के बिना React"](/docs/react-without-es6.html) देखें ।
+
+### मैं JSX में टिप्पणियां कैसे लिख सकता हूं? {#how-can-i-write-comments-in-jsx}
+
+```jsx
+<div>
+  {/* Comment goes here */}
+  Hello, {name}!
+</div>
+```
+
+```jsx
+<div>
+  {/* It also works 
+  for multi-line comments. */}
+  Hello, {name}! 
+</div>
+```
diff --git a/faq-functions.md b/faq-functions.md
new file mode 100644
index 000000000..f03b2ba76
--- /dev/null
+++ b/faq-functions.md
@@ -0,0 +1,354 @@
+---
+id: faq-functions
+title: Passing Functions to Components
+permalink: docs/faq-functions.html
+layout: docs
+category: FAQ
+---
+
+### How do I pass an event handler (like onClick) to a component? {#how-do-i-pass-an-event-handler-like-onclick-to-a-component}
+
+Pass event handlers and other functions as props to child components:
+
+```jsx
+<button onClick={this.handleClick}>
+```
+
+If you need to have access to the parent component in the handler, you also need to bind the function to the component instance (see below).
+
+### How do I bind a function to a component instance? {#how-do-i-bind-a-function-to-a-component-instance}
+
+There are several ways to make sure functions have access to component attributes like `this.props` and `this.state`, depending on which syntax and build steps you are using.
+
+#### Bind in Constructor (ES2015) {#bind-in-constructor-es2015}
+
+```jsx
+class Foo extends Component {
+  constructor(props) {
+    super(props);
+    this.handleClick = this.handleClick.bind(this);
+  }
+  handleClick() {
+    console.log('Click happened');
+  }
+  render() {
+    return <button onClick={this.handleClick}>Click Me</button>;
+  }
+}
+```
+
+#### Class Properties (Stage 3 Proposal) {#class-properties-stage-3-proposal}
+
+```jsx
+class Foo extends Component {
+  // Note: this syntax is experimental and not standardized yet.
+  handleClick = () => {
+    console.log('Click happened');
+  }
+  render() {
+    return <button onClick={this.handleClick}>Click Me</button>;
+  }
+}
+```
+
+#### Bind in Render {#bind-in-render}
+
+```jsx
+class Foo extends Component {
+  handleClick() {
+    console.log('Click happened');
+  }
+  render() {
+    return <button onClick={this.handleClick.bind(this)}>Click Me</button>;
+  }
+}
+```
+
+>**Note:**
+>
+>Using `Function.prototype.bind` in render creates a new function each time the component renders, which may have performance implications (see below).
+
+#### Arrow Function in Render {#arrow-function-in-render}
+
+```jsx
+class Foo extends Component {
+  handleClick() {
+    console.log('Click happened');
+  }
+  render() {
+    return <button onClick={() => this.handleClick()}>Click Me</button>;
+  }
+}
+```
+
+>**Note:**
+>
+>Using an arrow function in render creates a new function each time the component renders, which may break optimizations based on strict identity comparison.
+
+### Is it OK to use arrow functions in render methods? {#is-it-ok-to-use-arrow-functions-in-render-methods}
+
+Generally speaking, yes, it is OK, and it is often the easiest way to pass parameters to callback functions.
+
+If you do have performance issues, by all means, optimize!
+
+### Why is binding necessary at all? {#why-is-binding-necessary-at-all}
+
+In JavaScript, these two code snippets are **not** equivalent:
+
+```js
+obj.method();
+```
+
+```js
+var method = obj.method;
+method();
+```
+
+Binding methods helps ensure that the second snippet works the same way as the first one.
+
+With React, typically you only need to bind the methods you *pass* to other components. For example, `<button onClick={this.handleClick}>` passes `this.handleClick` so you want to bind it. However, it is unnecessary to bind the `render` method or the lifecycle methods: we don't pass them to other components.
+
+[This post by Yehuda Katz](https://yehudakatz.com/2011/08/11/understanding-javascript-function-invocation-and-this/) explains what binding is, and how functions work in JavaScript, in detail.
+
+### Why is my function being called every time the component renders? {#why-is-my-function-being-called-every-time-the-component-renders}
+
+Make sure you aren't _calling the function_ when you pass it to the component:
+
+```jsx
+render() {
+  // Wrong: handleClick is called instead of passed as a reference!
+  return <button onClick={this.handleClick()}>Click Me</button>
+}
+```
+
+Instead, *pass the function itself* (without parens):
+
+```jsx
+render() {
+  // Correct: handleClick is passed as a reference!
+  return <button onClick={this.handleClick}>Click Me</button>
+}
+```
+
+### How do I pass a parameter to an event handler or callback? {#how-do-i-pass-a-parameter-to-an-event-handler-or-callback}
+
+You can use an arrow function to wrap around an event handler and pass parameters:
+
+```jsx
+<button onClick={() => this.handleClick(id)} />
+```
+
+This is equivalent to calling `.bind`:
+
+```jsx
+<button onClick={this.handleClick.bind(this, id)} />
+```
+
+#### Example: Passing params using arrow functions {#example-passing-params-using-arrow-functions}
+
+```jsx
+const A = 65 // ASCII character code
+
+class Alphabet extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleClick = this.handleClick.bind(this);
+    this.state = {
+      justClicked: null,
+      letters: Array.from({length: 26}, (_, i) => String.fromCharCode(A + i))
+    };
+  }
+  handleClick(letter) {
+    this.setState({ justClicked: letter });
+  }
+  render() {
+    return (
+      <div>
+        Just clicked: {this.state.justClicked}
+        <ul>
+          {this.state.letters.map(letter =>
+            <li key={letter} onClick={() => this.handleClick(letter)}>
+              {letter}
+            </li>
+          )}
+        </ul>
+      </div>
+    )
+  }
+}
+```
+
+#### Example: Passing params using data-attributes {#example-passing-params-using-data-attributes}
+
+Alternately, you can use DOM APIs to store data needed for event handlers. Consider this approach if you need to optimize a large number of elements or have a render tree that relies on React.PureComponent equality checks.
+
+```jsx
+const A = 65 // ASCII character code
+
+class Alphabet extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleClick = this.handleClick.bind(this);
+    this.state = {
+      justClicked: null,
+      letters: Array.from({length: 26}, (_, i) => String.fromCharCode(A + i))
+    };
+  }
+
+  handleClick(e) {
+    this.setState({
+      justClicked: e.target.dataset.letter
+    });
+  }
+
+  render() {
+    return (
+      <div>
+        Just clicked: {this.state.justClicked}
+        <ul>
+          {this.state.letters.map(letter =>
+            <li key={letter} data-letter={letter} onClick={this.handleClick}>
+              {letter}
+            </li>
+          )}
+        </ul>
+      </div>
+    )
+  }
+}
+```
+
+### How can I prevent a function from being called too quickly or too many times in a row? {#how-can-i-prevent-a-function-from-being-called-too-quickly-or-too-many-times-in-a-row}
+
+If you have an event handler such as `onClick` or `onScroll` and want to prevent the callback from being fired too quickly, then you can limit the rate at which callback is executed. This can be done by using:
+
+- **throttling**: sample changes based on a time based frequency (eg [`_.throttle`](https://lodash.com/docs#throttle))
+- **debouncing**: publish changes after a period of inactivity (eg [`_.debounce`](https://lodash.com/docs#debounce))
+- **`requestAnimationFrame` throttling**: sample changes based on [`requestAnimationFrame`](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame) (eg [`raf-schd`](https://github.com/alexreardon/raf-schd))
+
+See [this visualization](http://demo.nimius.net/debounce_throttle/) for a comparison of `throttle` and `debounce` functions.
+
+> Note:
+>
+> `_.debounce`, `_.throttle` and `raf-schd` provide a `cancel` method to cancel delayed callbacks. You should either call this method from `componentWillUnmount` _or_ check to ensure that the component is still mounted within the delayed function.
+
+#### Throttle {#throttle}
+
+Throttling prevents a function from being called more than once in a given window of time. The example below throttles a "click" handler to prevent calling it more than once per second.
+
+```jsx
+import throttle from 'lodash.throttle';
+
+class LoadMoreButton extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleClick = this.handleClick.bind(this);
+    this.handleClickThrottled = throttle(this.handleClick, 1000);
+  }
+
+  componentWillUnmount() {
+    this.handleClickThrottled.cancel();
+  }
+
+  render() {
+    return <button onClick={this.handleClickThrottled}>Load More</button>;
+  }
+
+  handleClick() {
+    this.props.loadMore();
+  }
+}
+```
+
+#### Debounce {#debounce}
+
+Debouncing ensures that a function will not be executed until after a certain amount of time has passed since it was last called. This can be useful when you have to perform some expensive calculation in response to an event that might dispatch rapidly (eg scroll or keyboard events). The example below debounces text input with a 250ms delay.
+
+```jsx
+import debounce from 'lodash.debounce';
+
+class Searchbox extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleChange = this.handleChange.bind(this);
+    this.emitChangeDebounced = debounce(this.emitChange, 250);
+  }
+
+  componentWillUnmount() {
+    this.emitChangeDebounced.cancel();
+  }
+
+  render() {
+    return (
+      <input
+        type="text"
+        onChange={this.handleChange}
+        placeholder="Search..."
+        defaultValue={this.props.value}
+      />
+    );
+  }
+
+  handleChange(e) {
+    // React pools events, so we read the value before debounce.
+    // Alternately we could call `event.persist()` and pass the entire event.
+    // For more info see reactjs.org/docs/events.html#event-pooling
+    this.emitChangeDebounced(e.target.value);
+  }
+
+  emitChange(value) {
+    this.props.onChange(value);
+  }
+}
+```
+
+#### `requestAnimationFrame` throttling {#requestanimationframe-throttling}
+
+[`requestAnimationFrame`](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame) is a way of queuing a function to be executed in the browser at the optimal time for rendering performance. A function that is queued with `requestAnimationFrame` will fire in the next frame. The browser will work hard to ensure that there are 60 frames per second (60 fps). However, if the browser is unable to it will naturally *limit* the amount of frames in a second. For example, a device might only be able to handle 30 fps and so you will only get 30 frames in that second. Using `requestAnimationFrame` for throttling is a useful technique in that it prevents you from doing more than 60 updates in a second. If you are doing 100 updates in a second this creates additional work for the browser that the user will not see anyway.
+
+>**Note:**
+>
+>Using this technique will only capture the last published value in a frame. You can see an example of how this optimization works on [`MDN`](https://developer.mozilla.org/en-US/docs/Web/Events/scroll)
+
+```jsx
+import rafSchedule from 'raf-schd';
+
+class ScrollListener extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.handleScroll = this.handleScroll.bind(this);
+
+    // Create a new function to schedule updates.
+    this.scheduleUpdate = rafSchedule(
+      point => this.props.onScroll(point)
+    );
+  }
+
+  handleScroll(e) {
+    // When we receive a scroll event, schedule an update.
+    // If we receive many updates within a frame, we'll only publish the latest value.
+    this.scheduleUpdate({ x: e.clientX, y: e.clientY });
+  }
+
+  componentWillUnmount() {
+    // Cancel any pending updates since we're unmounting.
+    this.scheduleUpdate.cancel();
+  }
+
+  render() {
+    return (
+      <div
+        style={{ overflow: 'scroll' }}
+        onScroll={this.handleScroll}
+      >
+        <img src="/my-huge-image.jpg" />
+      </div>
+    );
+  }
+}
+```
+
+#### Testing your rate limiting {#testing-your-rate-limiting}
+
+When testing your rate limiting code works correctly it is helpful to have the ability to fast forward time. If you are using [`jest`](https://facebook.github.io/jest/) then you can use [`mock timers`](https://facebook.github.io/jest/docs/en/timer-mocks.html) to fast forward time. If you are using `requestAnimationFrame` throttling then you may find [`raf-stub`](https://github.com/alexreardon/raf-stub) to be a useful tool to control the ticking of animation frames.
diff --git a/faq-internals.md b/faq-internals.md
new file mode 100644
index 000000000..da7f96be0
--- /dev/null
+++ b/faq-internals.md
@@ -0,0 +1,23 @@
+---
+id: faq-internals
+title: Virtual DOM and Internals
+permalink: docs/faq-internals.html
+layout: docs
+category: FAQ
+---
+
+### What is the Virtual DOM? {#what-is-the-virtual-dom}
+
+The virtual DOM (VDOM) is a programming concept where an ideal, or "virtual", representation of a UI is kept in memory and synced with the "real" DOM by a library such as ReactDOM. This process is called [reconciliation](/docs/reconciliation.html).
+
+This approach enables the declarative API of React: You tell React what state you want the UI to be in, and it makes sure the DOM matches that state. This abstracts out the attribute manipulation, event handling, and manual DOM updating that you would otherwise have to use to build your app.
+
+Since "virtual DOM" is more of a pattern than a specific technology, people sometimes say it to mean different things. In React world, the term "virtual DOM" is usually associated with [React elements](/docs/rendering-elements.html) since they are the objects representing the user interface. React, however, also uses internal objects called "fibers" to hold additional information about the component tree. They may also be considered a part of "virtual DOM" implementation in React.
+
+### Is the Shadow DOM the same as the Virtual DOM? {#is-the-shadow-dom-the-same-as-the-virtual-dom}
+
+No, they are different. The Shadow DOM is a browser technology designed primarily for scoping variables and CSS in web components. The virtual DOM is a concept implemented by libraries in JavaScript on top of browser APIs.
+
+### What is "React Fiber"? {#what-is-react-fiber}
+
+Fiber is the new reconciliation engine in React 16. Its main goal is to enable incremental rendering of the virtual DOM. [Read more](https://github.com/acdlite/react-fiber-architecture).
diff --git a/faq-state.md b/faq-state.md
new file mode 100644
index 000000000..c2b7b6657
--- /dev/null
+++ b/faq-state.md
@@ -0,0 +1,106 @@
+---
+id: faq-state
+title: Component State
+permalink: docs/faq-state.html
+layout: docs
+category: FAQ
+---
+
+### What does `setState` do? {#what-does-setstate-do}
+
+`setState()` schedules an update to a component's `state` object. When state changes, the component responds by re-rendering.
+
+### What is the difference between `state` and `props`? {#what-is-the-difference-between-state-and-props}
+
+[`props`](/docs/components-and-props.html) (short for "properties") and [`state`](/docs/state-and-lifecycle.html) are both plain JavaScript objects. While both hold information that influences the output of render, they are different in one important way: `props` get passed *to* the component (similar to function parameters) whereas `state` is managed *within* the component (similar to variables declared within a function).
+
+Here are some good resources for further reading on when to use `props` vs `state`:
+* [Props vs State](https://github.com/uberVU/react-guide/blob/master/props-vs-state.md)
+* [ReactJS: Props vs. State](https://lucybain.com/blog/2016/react-state-vs-pros/)
+
+### Why is `setState` giving me the wrong value? {#why-is-setstate-giving-me-the-wrong-value}
+
+In React, both `this.props` and `this.state` represent the *rendered* values, i.e. what's currently on the screen.
+
+Calls to `setState` are asynchronous - don't rely on `this.state` to reflect the new value immediately after calling `setState`. Pass an updater function instead of an object if you need to compute values based on the current state (see below for details).
+
+Example of code that will *not* behave as expected:
+
+```jsx
+incrementCount() {
+  // Note: this will *not* work as intended.
+  this.setState({count: this.state.count + 1});
+}
+
+handleSomething() {
+  // Let's say `this.state.count` starts at 0.
+  this.incrementCount();
+  this.incrementCount();
+  this.incrementCount();
+  // When React re-renders the component, `this.state.count` will be 1, but you expected 3.
+
+  // This is because `incrementCount()` function above reads from `this.state.count`,
+  // but React doesn't update `this.state.count` until the component is re-rendered.
+  // So `incrementCount()` ends up reading `this.state.count` as 0 every time, and sets it to 1.
+
+  // The fix is described below!
+}
+```
+
+See below for how to fix this problem.
+
+### How do I update state with values that depend on the current state? {#how-do-i-update-state-with-values-that-depend-on-the-current-state}
+
+Pass a function instead of an object to `setState` to ensure the call always uses the most updated version of state (see below). 
+
+### What is the difference between passing an object or a function in `setState`? {#what-is-the-difference-between-passing-an-object-or-a-function-in-setstate}
+
+Passing an update function allows you to access the current state value inside the updater. Since `setState` calls are batched, this lets you chain updates and ensure they build on top of each other instead of conflicting:
+
+```jsx
+incrementCount() {
+  this.setState((state) => {
+    // Important: read `state` instead of `this.state` when updating.
+    return {count: state.count + 1}
+  });
+}
+
+handleSomething() {
+  // Let's say `this.state.count` starts at 0.
+  this.incrementCount();
+  this.incrementCount();
+  this.incrementCount();
+
+  // If you read `this.state.count` now, it would still be 0.
+  // But when React re-renders the component, it will be 3.
+}
+```
+
+[Learn more about setState](/docs/react-component.html#setstate)
+
+### When is `setState` asynchronous? {#when-is-setstate-asynchronous}
+
+Currently, `setState` is asynchronous inside event handlers.
+
+This ensures, for example, that if both `Parent` and `Child` call `setState` during a click event, `Child` isn't re-rendered twice. Instead, React "flushes" the state updates at the end of the browser event. This results in significant performance improvements in larger apps.
+
+This is an implementation detail so avoid relying on it directly. In the future versions, React will batch updates by default in more cases.
+
+### Why doesn't React update `this.state` synchronously? {#why-doesnt-react-update-thisstate-synchronously}
+
+As explained in the previous section, React intentionally "waits" until all components call `setState()` in their event handlers before starting to re-render. This boosts performance by avoiding unnecessary re-renders.
+
+However, you might still be wondering why React doesn't just update `this.state` immediately without re-rendering.
+
+There are two main reasons:
+
+* This would break the consistency between `props` and `state`, causing issues that are very hard to debug.
+* This would make some of the new features we're working on impossible to implement.
+
+This [GitHub comment](https://github.com/facebook/react/issues/11527#issuecomment-360199710) dives deep into the specific examples.
+
+### Should I use a state management library like Redux or MobX? {#should-i-use-a-state-management-library-like-redux-or-mobx}
+
+[Maybe.](https://redux.js.org/faq/general#when-should-i-use-redux)
+
+It's a good idea to get to know React first, before adding in additional libraries. You can build quite complex applications using only React.
diff --git a/faq-structure.md b/faq-structure.md
new file mode 100644
index 000000000..453cc7bab
--- /dev/null
+++ b/faq-structure.md
@@ -0,0 +1,74 @@
+---
+id: faq-structure
+title: File Structure
+permalink: docs/faq-structure.html
+layout: docs
+category: FAQ
+---
+
+### क्या React प्रोजेक्ट्स की संरचना का अनुशंसित तरीका है? {#is-there-a-recommended-way-to-structure-react-projects}
+
+React को यह नहीं पता कि आप फ़ाइलों को फ़ोल्डर्स में कैसे डालते हैं। आप जिस इकोसिस्टम पर विचार करना चाहते हैं, उसमें कुछ सामान्य दृष्टिकोण लोकप्रिय हैं।
+
+#### फीचर्स या रआउट्स द्वारा समूहीकरण {#grouping-by-features-or-routes}
+
+प्रोजेक्ट्स की संरचना का एक सामान्य तरीका CSS, JS का पता लगाकर, फ़ीचर या रआउट्स द्वारा समूहीकृत फ़ोल्डर के अंदर एक साथ परीक्षण करना हैं।
+
+```
+common/
+  Avatar.js
+  Avatar.css
+  APIUtils.js
+  APIUtils.test.js
+feed/
+  index.js
+  Feed.js
+  Feed.css
+  FeedStory.js
+  FeedStory.test.js
+  FeedAPI.js
+profile/
+  index.js
+  Profile.js
+  ProfileHeader.js
+  ProfileHeader.css
+  ProfileAPI.js
+```
+
+"फीचर" की परिभाषा सार्वभौमिक नहीं है, और यह आप पर निर्भर है कि आप किस विवरण का चयन करते हैं। यदि आप शीर्ष स्तर के फ़ोल्डरों की सूची के साथ नहीं आ सकते हैं, तो आप अपने उत्पाद के उपयोगकर्ताओं से पूछ सकते हैं कि इसमें कौन से प्रमुख भाग हैं, और उनके मानसिक मॉडल का ब्लूप्रिंट के रूप में उपयोग कर सकते हैं।
+
+#### फ़ाइल प्रकार द्वारा समूहीकरण {#grouping-by-file-type}
+
+ प्रोजेक्ट्स के लिए एक और लोकप्रिय तरीका समान फ़ाइलों को एक साथ समूहित करना है, उदाहरण के लिए:
+
+```
+api/
+  APIUtils.js
+  APIUtils.test.js
+  ProfileAPI.js
+  UserAPI.js
+components/
+  Avatar.js
+  Avatar.css
+  Feed.js
+  Feed.css
+  FeedStory.js
+  FeedStory.test.js
+  Profile.js
+  ProfileHeader.js
+  ProfileHeader.css
+```
+
+कुछ लोग गहराई में जाना पसंद करते हैं, और कॉम्पोनेन्ट को उनकी भूमिका के आधार पर विभिन्न फ़ोल्डर्स में अलग अलग करते हैं। उदाहरण के लिए, [एटॉमिक डिजाइन](http://bradfrost.com/blog/post/atomic-web-design/) इस सिद्धांत पर निर्मित एक डिजाइन पद्धति है। याद रखें कि इस तरह की कार्यप्रणालियों को व्यवहार में लाने के लिए अक्सर सख्त नियमों के बजाय सहायक उदाहरणों का उपयोग करना अधिक लाभदायक होता है।
+
+#### बहुत ज्यादा नेस्टिंग से बचें {#avoid-too-much-nesting}
+
+जावास्क्रिप्ट प्रोजेक्ट्स में डीप डायरेक्टरी नेस्टिंग को लेकर काफी समस्याएं हैं। जब फाइल्स को मूव कराते हैं तब उनके बीच सापेक्ष इम्पोर्ट्स लिखना या उन इम्पोर्ट्स को अपडेट करना मुश्किल हो जाता है। जब तक आपके पास एक गहरी फ़ोल्डर संरचना का उपयोग करने के लिए एक बहुत ही सम्मोहक कारण नहीं है, तब तक अपने आप को एक ही प्रोजेक्ट के भीतर अधिकतम तीन या चार नेस्टेड फ़ोल्डरों तक सीमित करने पर विचार करें। बेशक, यह केवल एक सिफारिश है, और यह आपके प्रोजेक्ट के लिए प्रासंगिक नहीं हो सकता है।
+
+####  ज़रूरत से ज्यादा न सोचें {#dont-overthink-it}
+
+यदि आप एक प्रोजेक्ट शुरू कर रहें हैं, तो फ़ाइल संरचना चुनने के लिए [पांच मिनट से अधिक समय न लगाएं](https://en.wikipedia.org/wiki/Analysis_paralysis) । उपरोक्त किसी भी दृष्टिकोण को चुनें (या अपने स्वयं के साथ आएं) और कोड लिखना शुरू करें! आपके द्वारा कुछ वास्तविक कोड लिखे जाने के बाद, आप इसे वैसे भी पुनर्विचार करना चाहेंगे।
+
+यदि आप पूरी तरह से फंसे हुए महसूस करते हैं, तो सभी फ़ाइलों को एक फ़ोल्डर में रखकर शुरू करें। आखिरकार यह काफी बड़ा हो जाएगा कि आप कुछ फ़ाइलों को बाकी हिस्सों से अलग करना चाहेंगे। उस समय तक आपको यह पर्याप्त ज्ञान होगा कि आप यह बता सकेंगे की आप किन फ़ाइलों पर अक्सर काम करते हैं। सामान्य तौर पर, फाइलों को रखना एक अच्छा विचार है जो अक्सर एक-दूसरे के करीब बदल जाते हैं। इस सिद्धांत को "कोलोकेशन" कहा जाता है।
+
+जैसे-जैसे प्रोजेक्ट बड़े होते हैं, वे अक्सर अभ्यास में उपरोक्त दोनों दृष्टिकोणों के मिश्रण का उपयोग करते हैं। इसलिए शुरुआत में किसी एक को "सही" चुनना बहुत महत्वपूर्ण नहीं है।
diff --git a/faq-styling.md b/faq-styling.md
new file mode 100644
index 000000000..7436c3b07
--- /dev/null
+++ b/faq-styling.md
@@ -0,0 +1,51 @@
+---
+id: faq-styling
+title: Styling and CSS
+permalink: docs/faq-styling.html
+layout: docs
+category: FAQ
+---
+
+### How do I add CSS classes to components? {#how-do-i-add-css-classes-to-components}
+
+Pass a string as the `className` prop:
+
+```jsx
+render() {
+  return <span className="menu navigation-menu">Menu</span>
+}
+```
+
+It is common for CSS classes to depend on the component props or state:
+
+```jsx
+render() {
+  let className = 'menu';
+  if (this.props.isActive) {
+    className += ' menu-active';
+  }
+  return <span className={className}>Menu</span>
+}
+```
+
+>Tip
+>
+>If you often find yourself writing code like this, [classnames](https://www.npmjs.com/package/classnames#usage-with-reactjs) package can simplify it.
+
+### Can I use inline styles? {#can-i-use-inline-styles}
+
+Yes, see the docs on styling [here](/docs/dom-elements.html#style).
+
+### Are inline styles bad? {#are-inline-styles-bad}
+
+CSS classes are generally better for performance than inline styles.
+
+### What is CSS-in-JS? {#what-is-css-in-js}
+
+"CSS-in-JS" refers to a pattern where CSS is composed using JavaScript instead of defined in external files. Read a comparison of CSS-in-JS libraries [here](https://github.com/MicheleBertoli/css-in-js).
+
+_Note that this functionality is not a part of React, but provided by third-party libraries._ React does not have an opinion about how styles are defined; if in doubt, a good starting point is to define your styles in a separate `*.css` file as usual and refer to them using [`className`](/docs/dom-elements.html#classname).
+
+### Can I do animations in React? {#can-i-do-animations-in-react}
+
+React can be used to power animations. See [React Transition Group](https://reactcommunity.org/react-transition-group/) and [React Motion](https://github.com/chenglou/react-motion) or [React Spring](https://github.com/react-spring/react-spring), for example.
diff --git a/faq-versioning.md b/faq-versioning.md
new file mode 100644
index 000000000..ab45ddf74
--- /dev/null
+++ b/faq-versioning.md
@@ -0,0 +1,64 @@
+---
+id: faq-versioning
+title: Versioning Policy
+permalink: docs/faq-versioning.html
+layout: docs
+category: FAQ
+---
+
+React follows [semantic versioning (semver)](https://semver.org/) principles.
+
+That means that with a version number **x.y.z**:
+
+* When releasing **critical bug fixes**, we make a **patch release** by changing the **z** number (ex: 15.6.2 to 15.6.3).
+* When releasing **new features** or **non-critical fixes**, we make a **minor release** by changing the **y** number (ex: 15.6.2 to 15.7.0).
+* When releasing **breaking changes**, we make a **major release** by changing the **x** number (ex: 15.6.2 to 16.0.0).
+
+Major releases can also contain new features, and any release can include bug fixes.
+
+Minor releases are the most common type of release.
+
+### Breaking Changes {#breaking-changes}
+
+Breaking changes are inconvenient for everyone, so we try to minimize the number of major releases – for example, React 15 was released in April 2016 and React 16 was released in September 2017; React 17 isn't expected until 2019.
+
+Instead, we release new features in minor versions. That means that minor releases are often more interesting and compelling than majors, despite their unassuming name.
+
+### Commitment to Stability {#commitment-to-stability}
+
+As we change React over time, we try to minimize the effort required to take advantage of new features. When possible, we'll keep an older API working, even if that means putting it in a separate package. For example, [mixins have been discouraged for years](/blog/2016/07/13/mixins-considered-harmful.html) but they're supported to this day [via create-react-class](/docs/react-without-es6.html#mixins) and many codebases continue to use them in stable, legacy code.
+
+Over a million developers use React, collectively maintaining millions of components. The Facebook codebase alone has over 50,000 React components. That means we need to make it as easy as possible to upgrade to new versions of React; if we make large changes without a migration path, people will be stuck on old versions. We test these upgrade paths on Facebook itself – if our team of less than 10 people can update 50,000+ components alone, we hope the upgrade will be manageable for anyone using React. In many cases, we write [automated scripts](https://github.com/reactjs/react-codemod) to upgrade component syntax, which we then include in the open-source release for everyone to use.
+
+### Gradual Upgrades via Warnings {#gradual-upgrades-via-warnings}
+
+Development builds of React include many helpful warnings. Whenever possible, we add warnings in preparation for future breaking changes. That way, if your app has no warnings on the latest release, it will be compatible with the next major release. This allows you to upgrade your apps one component at a time.
+
+Development warnings won't affect the runtime behavior of your app. That way, you can feel confident that your app will behave the same way between the development and production builds -- the only differences are that the production build won't log the warnings and that it is more efficient. (If you ever notice otherwise, please file an issue.)
+
+### What Counts as a Breaking Change? {#what-counts-as-a-breaking-change}
+
+In general, we *don't* bump the major version number for changes to:
+
+* **Development warnings.** Since these don't affect production behavior, we may add new warnings or modify existing warnings in between major versions. In fact, this is what allows us to reliably warn about upcoming breaking changes.
+* **APIs starting with `unstable_`.** These are provided as experimental features whose APIs we are not yet confident in. By releasing these with an `unstable_` prefix, we can iterate faster and get to a stable API sooner.
+* **Alpha and canary versions of React.** We provide alpha versions of React as a way to test new features early, but we need the flexibility to make changes based on what we learn in the alpha period. If you use these versions, note that APIs may change before the stable release.
+* **Undocumented APIs and internal data structures.** If you access internal property names like `__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED` or `__reactInternalInstance$uk43rzhitjg`, there is no warranty.  You are on your own.
+
+This policy is designed to be pragmatic: certainly, we don't want to cause headaches for you. If we bumped the major version for all of these changes, we would end up releasing more major versions and ultimately causing more versioning pain for the community. It would also mean that we can't make progress in improving React as fast as we'd like.
+
+That said, if we expect that a change on this list will cause broad problems in the community, we will still do our best to provide a gradual migration path.
+
+### If a Minor Release Includes No New Features, Why Isn't It a Patch? {#minors-versus-patches}
+
+It's possible that a minor release will not include new features. [This is allowed by semver](https://semver.org/#spec-item-7), which states **"[a minor version] MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes."**
+
+However, it does raise the question of why these releases aren't versioned as patches instead.
+
+The answer is that any change to React (or other software) carries some risk of breaking in unexpected ways. Imagine a scenario where a patch release that fixes one bug accidentally introduces a different bug. This would not only be disruptive to developers, but also harm their confidence in future patch releases. It's especially regrettable if the original fix is for a bug that is rarely encountered in practice.
+
+We have a pretty good track record for keeping React releases free of bugs, but patch releases have an even higher bar for reliability because most developers assume they can be adopted without adverse consequences.
+
+For these reasons, we reserve patch releases only for the most critical bugs and security vulnerabilities.
+
+If a release includes non-essential changes — such as internal refactors, changes to implementation details, performance improvements, or minor bugfixes — we will bump the minor version even when there are no new features.
diff --git a/forms.md b/forms.md
new file mode 100644
index 000000000..1a8b599d5
--- /dev/null
+++ b/forms.md
@@ -0,0 +1,298 @@
+---
+id: forms
+title: Forms
+permalink: docs/forms.html
+prev: lists-and-keys.html
+next: lifting-state-up.html
+redirect_from:
+  - "tips/controlled-input-null-value.html"
+  - "docs/forms-zh-CN.html"
+---
+
+HTML form elements work a little bit differently from other DOM elements in React, because form elements naturally keep some internal state. For example, this form in plain HTML accepts a single name:
+
+```html
+<form>
+  <label>
+    Name:
+    <input type="text" name="name" />
+  </label>
+  <input type="submit" value="Submit" />
+</form>
+```
+
+This form has the default HTML form behavior of browsing to a new page when the user submits the form. If you want this behavior in React, it just works. But in most cases, it's convenient to have a JavaScript function that handles the submission of the form and has access to the data that the user entered into the form. The standard way to achieve this is with a technique called "controlled components".
+
+## Controlled Components {#controlled-components}
+
+In HTML, form elements such as `<input>`, `<textarea>`, and `<select>` typically maintain their own state and update it based on user input. In React, mutable state is typically kept in the state property of components, and only updated with [`setState()`](/docs/react-component.html#setstate).
+
+We can combine the two by making the React state be the "single source of truth". Then the React component that renders a form also controls what happens in that form on subsequent user input. An input form element whose value is controlled by React in this way is called a "controlled component".
+
+For example, if we want to make the previous example log the name when it is submitted, we can write the form as a controlled component:
+
+```javascript{4,10-12,24}
+class NameForm extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {value: ''};
+
+    this.handleChange = this.handleChange.bind(this);
+    this.handleSubmit = this.handleSubmit.bind(this);
+  }
+
+  handleChange(event) {
+    this.setState({value: event.target.value});
+  }
+
+  handleSubmit(event) {
+    alert('A name was submitted: ' + this.state.value);
+    event.preventDefault();
+  }
+
+  render() {
+    return (
+      <form onSubmit={this.handleSubmit}>
+        <label>
+          Name:
+          <input type="text" value={this.state.value} onChange={this.handleChange} />
+        </label>
+        <input type="submit" value="Submit" />
+      </form>
+    );
+  }
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/VmmPgp?editors=0010)
+
+Since the `value` attribute is set on our form element, the displayed value will always be `this.state.value`, making the React state the source of truth. Since `handleChange` runs on every keystroke to update the React state, the displayed value will update as the user types.
+
+With a controlled component, every state mutation will have an associated handler function. This makes it straightforward to modify or validate user input. For example, if we wanted to enforce that names are written with all uppercase letters, we could write `handleChange` as:
+
+```javascript{2}
+handleChange(event) {
+  this.setState({value: event.target.value.toUpperCase()});
+}
+```
+
+## The textarea Tag {#the-textarea-tag}
+
+In HTML, a `<textarea>` element defines its text by its children:
+
+```html
+<textarea>
+  Hello there, this is some text in a text area
+</textarea>
+```
+
+In React, a `<textarea>` uses a `value` attribute instead. This way, a form using a `<textarea>` can be written very similarly to a form that uses a single-line input:
+
+```javascript{4-6,12-14,26}
+class EssayForm extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      value: 'Please write an essay about your favorite DOM element.'
+    };
+
+    this.handleChange = this.handleChange.bind(this);
+    this.handleSubmit = this.handleSubmit.bind(this);
+  }
+
+  handleChange(event) {
+    this.setState({value: event.target.value});
+  }
+
+  handleSubmit(event) {
+    alert('An essay was submitted: ' + this.state.value);
+    event.preventDefault();
+  }
+
+  render() {
+    return (
+      <form onSubmit={this.handleSubmit}>
+        <label>
+          Essay:
+          <textarea value={this.state.value} onChange={this.handleChange} />
+        </label>
+        <input type="submit" value="Submit" />
+      </form>
+    );
+  }
+}
+```
+
+Notice that `this.state.value` is initialized in the constructor, so that the text area starts off with some text in it.
+
+## The select Tag {#the-select-tag}
+
+In HTML, `<select>` creates a drop-down list. For example, this HTML creates a drop-down list of flavors:
+
+```html
+<select>
+  <option value="grapefruit">Grapefruit</option>
+  <option value="lime">Lime</option>
+  <option selected value="coconut">Coconut</option>
+  <option value="mango">Mango</option>
+</select>
+```
+
+Note that the Coconut option is initially selected, because of the `selected` attribute. React, instead of using this `selected` attribute, uses a `value` attribute on the root `select` tag. This is more convenient in a controlled component because you only need to update it in one place. For example:
+
+```javascript{4,10-12,24}
+class FlavorForm extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {value: 'coconut'};
+
+    this.handleChange = this.handleChange.bind(this);
+    this.handleSubmit = this.handleSubmit.bind(this);
+  }
+
+  handleChange(event) {
+    this.setState({value: event.target.value});
+  }
+
+  handleSubmit(event) {
+    alert('Your favorite flavor is: ' + this.state.value);
+    event.preventDefault();
+  }
+
+  render() {
+    return (
+      <form onSubmit={this.handleSubmit}>
+        <label>
+          Pick your favorite flavor:
+          <select value={this.state.value} onChange={this.handleChange}>
+            <option value="grapefruit">Grapefruit</option>
+            <option value="lime">Lime</option>
+            <option value="coconut">Coconut</option>
+            <option value="mango">Mango</option>
+          </select>
+        </label>
+        <input type="submit" value="Submit" />
+      </form>
+    );
+  }
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/JbbEzX?editors=0010)
+
+Overall, this makes it so that `<input type="text">`, `<textarea>`, and `<select>` all work very similarly - they all accept a `value` attribute that you can use to implement a controlled component.
+
+> Note
+>
+> You can pass an array into the `value` attribute, allowing you to select multiple options in a `select` tag:
+>
+>```js
+><select multiple={true} value={['B', 'C']}>
+>```
+
+## The file input Tag {#the-file-input-tag}
+
+In HTML, an `<input type="file">` lets the user choose one or more files from their device storage to be uploaded to a server or manipulated by JavaScript via the [File API](https://developer.mozilla.org/en-US/docs/Web/API/File/Using_files_from_web_applications).
+
+```html
+<input type="file" />
+```
+
+Because its value is read-only, it is an **uncontrolled** component in React. It is discussed together with other uncontrolled components [later in the documentation](/docs/uncontrolled-components.html#the-file-input-tag).
+
+## Handling Multiple Inputs {#handling-multiple-inputs}
+
+When you need to handle multiple controlled `input` elements, you can add a `name` attribute to each element and let the handler function choose what to do based on the value of `event.target.name`.
+
+For example:
+
+```javascript{15,18,28,37}
+class Reservation extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      isGoing: true,
+      numberOfGuests: 2
+    };
+
+    this.handleInputChange = this.handleInputChange.bind(this);
+  }
+
+  handleInputChange(event) {
+    const target = event.target;
+    const value = target.type === 'checkbox' ? target.checked : target.value;
+    const name = target.name;
+
+    this.setState({
+      [name]: value
+    });
+  }
+
+  render() {
+    return (
+      <form>
+        <label>
+          Is going:
+          <input
+            name="isGoing"
+            type="checkbox"
+            checked={this.state.isGoing}
+            onChange={this.handleInputChange} />
+        </label>
+        <br />
+        <label>
+          Number of guests:
+          <input
+            name="numberOfGuests"
+            type="number"
+            value={this.state.numberOfGuests}
+            onChange={this.handleInputChange} />
+        </label>
+      </form>
+    );
+  }
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/wgedvV?editors=0010)
+
+Note how we used the ES6 [computed property name](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Operators/Object_initializer#Computed_property_names) syntax to update the state key corresponding to the given input name:
+
+```js{2}
+this.setState({
+  [name]: value
+});
+```
+
+It is equivalent to this ES5 code:
+
+```js{2}
+var partialState = {};
+partialState[name] = value;
+this.setState(partialState);
+```
+
+Also, since `setState()` automatically [merges a partial state into the current state](/docs/state-and-lifecycle.html#state-updates-are-merged), we only needed to call it with the changed parts.
+
+## Controlled Input Null Value {#controlled-input-null-value}
+
+Specifying the value prop on a [controlled component](/docs/forms.html#controlled-components) prevents the user from changing the input unless you desire so. If you've specified a `value` but the input is still editable, you may have accidentally set `value` to `undefined` or `null`.
+
+The following code demonstrates this. (The input is locked at first but becomes editable after a short delay.)
+
+```javascript
+ReactDOM.render(<input value="hi" />, mountNode);
+
+setTimeout(function() {
+  ReactDOM.render(<input value={null} />, mountNode);
+}, 1000);
+
+```
+
+## Alternatives to Controlled Components {#alternatives-to-controlled-components}
+
+It can sometimes be tedious to use controlled components, because you need to write an event handler for every way your data can change and pipe all of the input state through a React component. This can become particularly annoying when you are converting a preexisting codebase to React, or integrating a React application with a non-React library. In these situations, you might want to check out [uncontrolled components](/docs/uncontrolled-components.html), an alternative technique for implementing input forms.
+
+## Fully-Fledged Solutions {#fully-fledged-solutions}
+
+If you're looking for a complete solution including validation, keeping track of the visited fields, and handling form submission, [Formik](https://jaredpalmer.com/formik) is one of the popular choices. However, it is built on the same principles of controlled components and managing state — so don't neglect to learn them.
diff --git a/forwarding-refs.md b/forwarding-refs.md
new file mode 100644
index 000000000..3318d8499
--- /dev/null
+++ b/forwarding-refs.md
@@ -0,0 +1,76 @@
+---
+id: forwarding-refs
+title: Forwarding Refs
+permalink: docs/forwarding-refs.html
+---
+
+Ref forwarding is a technique for automatically passing a [ref](/docs/refs-and-the-dom.html) through a component to one of its children. This is typically not necessary for most components in the application. However, it can be useful for some kinds of components, especially in reusable component libraries. The most common scenarios are described below.
+
+## Forwarding refs to DOM components {#forwarding-refs-to-dom-components}
+
+Consider a `FancyButton` component that renders the native `button` DOM element:
+`embed:forwarding-refs/fancy-button-simple.js`
+
+React components hide their implementation details, including their rendered output. Other components using `FancyButton` **usually will not need to** [obtain a ref](/docs/refs-and-the-dom.html) to the inner `button` DOM element. This is good because it prevents components from relying on each other's DOM structure too much.
+
+Although such encapsulation is desirable for application-level components like `FeedStory` or `Comment`, it can be inconvenient for highly reusable "leaf" components like `FancyButton` or `MyTextInput`. These components tend to be used throughout the application in a similar manner as a regular DOM `button` and `input`, and accessing their DOM nodes may be unavoidable for managing focus, selection, or animations.
+
+**Ref forwarding is an opt-in feature that lets some components take a `ref` they receive, and pass it further down (in other words, "forward" it) to a child.**
+
+In the example below, `FancyButton` uses `React.forwardRef` to obtain the `ref` passed to it, and then forward it to the DOM `button` that it renders:
+
+`embed:forwarding-refs/fancy-button-simple-ref.js`
+
+This way, components using `FancyButton` can get a ref to the underlying `button` DOM node and access it if necessary—just like if they used a DOM `button` directly.
+
+Here is a step-by-step explanation of what happens in the above example:
+
+1. We create a [React ref](/docs/refs-and-the-dom.html) by calling `React.createRef` and assign it to a `ref` variable.
+1. We pass our `ref` down to `<FancyButton ref={ref}>` by specifying it as a JSX attribute.
+1. React passes the `ref` to the `(props, ref) => ...` function inside `forwardRef` as a second argument.
+1. We forward this `ref` argument down to `<button ref={ref}>` by specifying it as a JSX attribute.
+1. When the ref is attached, `ref.current` will point to the `<button>` DOM node.
+
+>Note
+>
+>The second `ref` argument only exists when you define a component with `React.forwardRef` call. Regular function or class components don't receive the `ref` argument, and ref is not available in props either.
+>
+>Ref forwarding is not limited to DOM components. You can forward refs to class component instances, too.
+
+## Note for component library maintainers {#note-for-component-library-maintainers}
+
+**When you start using `forwardRef` in a component library, you should treat it as a breaking change and release a new major version of your library.** This is because your library likely has an observably different behavior (such as what refs get assigned to, and what types are exported), and this can break apps and other libraries that depend on the old behavior.
+
+Conditionally applying `React.forwardRef` when it exists is also not recommended for the same reasons: it changes how your library behaves and can break your users' apps when they upgrade React itself.
+
+## Forwarding refs in higher-order components {#forwarding-refs-in-higher-order-components}
+
+This technique can also be particularly useful with [higher-order components](/docs/higher-order-components.html) (also known as HOCs). Let's start with an example HOC that logs component props to the console:
+`embed:forwarding-refs/log-props-before.js`
+
+The "logProps" HOC passes all `props` through to the component it wraps, so the rendered output will be the same. For example, we can use this HOC to log all props that get passed to our "fancy button" component:
+`embed:forwarding-refs/fancy-button.js`
+
+There is one caveat to the above example: refs will not get passed through. That's because `ref` is not a prop. Like `key`, it's handled differently by React. If you add a ref to a HOC, the ref will refer to the outermost container component, not the wrapped component.
+
+This means that refs intended for our `FancyButton` component will actually be attached to the `LogProps` component:
+`embed:forwarding-refs/fancy-button-ref.js`
+
+Fortunately, we can explicitly forward refs to the inner `FancyButton` component using the `React.forwardRef` API. `React.forwardRef` accepts a render function that receives `props` and `ref` parameters and returns a React node. For example:
+`embed:forwarding-refs/log-props-after.js`
+
+## Displaying a custom name in DevTools {#displaying-a-custom-name-in-devtools}
+
+`React.forwardRef` accepts a render function. React DevTools uses this function to determine what to display for the ref forwarding component.
+
+For example, the following component will appear as "*ForwardRef*" in the DevTools:
+
+`embed:forwarding-refs/wrapped-component.js`
+
+If you name the render function, DevTools will also include its name (e.g. "*ForwardRef(myFunction)*"):
+
+`embed:forwarding-refs/wrapped-component-with-function-name.js`
+
+You can even set the function's `displayName` property to include the component you're wrapping:
+
+`embed:forwarding-refs/customized-display-name.js`
diff --git a/fragments.md b/fragments.md
new file mode 100644
index 000000000..33619db2f
--- /dev/null
+++ b/fragments.md
@@ -0,0 +1,140 @@
+---
+id: fragments
+title: Fragments
+permalink: docs/fragments.html
+---
+
+A common pattern in React is for a component to return multiple elements. Fragments let you group a list of children without adding extra nodes to the DOM.
+
+```js
+render() {
+  return (
+    <React.Fragment>
+      <ChildA />
+      <ChildB />
+      <ChildC />
+    </React.Fragment>
+  );
+}
+```
+
+There is also a new [short syntax](#short-syntax) for declaring them.
+
+## Motivation {#motivation}
+
+A common pattern is for a component to return a list of children. Take this example React snippet:
+
+```jsx
+class Table extends React.Component {
+  render() {
+    return (
+      <table>
+        <tr>
+          <Columns />
+        </tr>
+      </table>
+    );
+  }
+}
+```
+
+`<Columns />` would need to return multiple `<td>` elements in order for the rendered HTML to be valid. If a parent div was used inside the `render()` of `<Columns />`, then the resulting HTML will be invalid.
+
+```jsx
+class Columns extends React.Component {
+  render() {
+    return (
+      <div>
+        <td>Hello</td>
+        <td>World</td>
+      </div>
+    );
+  }
+}
+```
+
+results in a `<Table />` output of:
+
+```jsx
+<table>
+  <tr>
+    <div>
+      <td>Hello</td>
+      <td>World</td>
+    </div>
+  </tr>
+</table>
+```
+
+Fragments solve this problem.
+
+## Usage {#usage}
+
+```jsx{4,7}
+class Columns extends React.Component {
+  render() {
+    return (
+      <React.Fragment>
+        <td>Hello</td>
+        <td>World</td>
+      </React.Fragment>
+    );
+  }
+}
+```
+
+which results in a correct `<Table />` output of:
+
+```jsx
+<table>
+  <tr>
+    <td>Hello</td>
+    <td>World</td>
+  </tr>
+</table>
+```
+
+### Short Syntax {#short-syntax}
+
+There is a new, shorter syntax you can use for declaring fragments. It looks like empty tags:
+
+```jsx{4,7}
+class Columns extends React.Component {
+  render() {
+    return (
+      <>
+        <td>Hello</td>
+        <td>World</td>
+      </>
+    );
+  }
+}
+```
+
+You can use `<></>` the same way you'd use any other element except that it doesn't support keys or attributes.
+
+### Keyed Fragments {#keyed-fragments}
+
+Fragments declared with the explicit `<React.Fragment>` syntax may have keys. A use case for this is mapping a collection to an array of fragments -- for example, to create a description list:
+
+```jsx
+function Glossary(props) {
+  return (
+    <dl>
+      {props.items.map(item => (
+        // Without the `key`, React will fire a key warning
+        <React.Fragment key={item.id}>
+          <dt>{item.term}</dt>
+          <dd>{item.description}</dd>
+        </React.Fragment>
+      ))}
+    </dl>
+  );
+}
+```
+
+`key` is the only attribute that can be passed to `Fragment`. In the future, we may add support for additional attributes, such as event handlers.
+
+### Live Demo {#live-demo}
+
+You can try out the new JSX fragment syntax with this [CodePen](https://codepen.io/reactjs/pen/VrEbjE?editors=1000).
diff --git a/gatsby-config.js b/gatsby-config.js
index 15ef0a53b..2637eac97 100644
--- a/gatsby-config.js
+++ b/gatsby-config.js
@@ -163,7 +163,9 @@ module.exports = {
       resolve: `gatsby-plugin-manifest`,
       options: {
         name: 'React Docs',
-        short_name: 'React',
+        short_name: 'React', // eg. React [%LANG_CODE%]
+        // Translators: please change this and two above options (see https://www.gatsbyjs.org/packages/gatsby-plugin-manifest/#feature-configuration---optional)
+        lang: 'en',
         start_url: '/',
         background_color: '#20232a',
         theme_color: '#20232a',
diff --git a/getting-started.md b/getting-started.md
new file mode 100644
index 000000000..398df45f4
--- /dev/null
+++ b/getting-started.md
@@ -0,0 +1,126 @@
+---
+id: getting-started
+title: शुरू करें 
+permalink: docs/getting-started.html
+next: add-react-to-a-website.html
+redirect_from:
+  - "docs/"
+  - "docs/index.html"
+  - "docs/getting-started-ko-KR.html"
+  - "docs/getting-started-zh-CN.html"
+  - "docs/installation.html"
+  - "download.html"
+  - "downloads.html"
+  - "docs/try-react.html"
+  - "docs/tooling-integration.html"
+  - "docs/package-management.html"
+  - "docs/language-tooling.html"
+  - "docs/environments.html"
+---
+
+यह पेज React के दस्तावेज और उससे सम्बंधित साधनो का ओवरव्यू है ।
+
+**React** उपयोगकर्ता इंटरफेस के निर्माण के लिए एक जावास्क्रिप्ट लाइब्रेरी है। React के बारे में जान्ने के लिए [हमारे होमपेज पर](/) या फिर [यह टुटोरिअल](/tutorial/tutorial.html) को देखें।
+
+ ---
+ 
+ - [React का प्रयोग करके देखें](#try-react)
+ - [React सीखे](#learn-react)
+ - [सूचित रहना](staying-informed)
+ - [वर्ज़न दस्तावेज़](#versioned-documentation)
+ - [कुछ छूट रहा है क्या?](#something-missing )
+ 
+## React का प्रयोग करके देखें {#try-react}
+
+React को धीरे-धीरे ग्रहण करने के लिए बनाया गया है, और  **आप जितनी कम और ज्यादा चाहे उतनी React इस्तेमाल कर सकते है।** यदि आप React का नमूना देखना चाहें, अपने सरल HTML पेज में कुछ इंटरएक्टिविट डालना चाहें, या एक जटिल React-संचालित ऐप बनाना चाहे, इन सभी के लिए इस अनुभाग में दी गई लिंक्स आपकी सहायता करेंगी। 
+
+### ऑनलाइन प्लेग्राउंड्स {#online-playgrounds}
+
+अगर आप React को इस्तेमाल करने में रूचि रखतें है, तो आप एक ऑनलाइन कोड प्लेग्राउंड इस्तेमाल कर सकते है। आप [CodePen](codepen://hello-world) या [CodeSandbox](https://codesandbox.io/s/new) पर एक Hello World टेम्पलेट इस्तेमाल कर सकते हैं।
+
+अगर आप अपना Text Editor इस्तमाल करना चा रहे है, आप [इस HTML फाइल को डाउनलोड](https://raw.githubusercontent.com/reactjs/reactjs.org/master/static/html/single-file-example.html) कर सकतें हैं, फिर आप उसे एडिट करके अपने लोकल फिलेसिस्टम से इसे अपने ब्राउज़र में खोल सकते हैं। यह रनटाइम कोड ट्रांसफॉर्मेशन को धीमे करता है, हम इसे खाली सरल डेमो के लिए ही इस्तेमाल करने का अनुग्रह करते हैं।
+
+### React को वेबसाइट में डालें {#add-react-to-a-website}
+
+आप [React को अपने पेज में एक मिनट में डाल सकते हैं](/docs/add-react-to-a-website.html)। इसके बाद या तो आप इसे धीमे से बड़ाह सकते है या इसे कुछ ही डायनामिक widgets तक सीमित रख सकते हैं।
+
+### नया React ऐप बनाए {#create-a-new-react-app}
+
+जब आप नया React प्रोजेक्ट शुरू करते है, [एक सरल HTML पेज स्क्रिप्ट टैग्स के साथ](/docs/add-react-to-a-website.html) एक उत्तम विकल्प हो सकता है।  इसे तैयार करने में सिर्फ एक मिनट लगता है!
+
+जैसे आपकी एप्लीकेशन बड़ी होती जाती है, आप शायद एक ज़्यादा इंटीग्रेटेड सेटअप इस्तेमाल करना चाहेंगे। ऐसी [बहुत सारी जावास्क्रिप्ट टूलचैन हैं](/docs/create-a-new-react-app.html) जिन्हे हम बड़ी एप्लिकेशनों के साथ इस्तेमाल करने के लिए अनुरोध करते हैं। ये सारे थोड़ी या बिना कॉन्फ़िगरेशन के साथ आपको React के इकोसिस्टम का पूरा इस्तेमाल करने देते है। 
+
+## React सीखें {#learn-react}
+
+लोग React सीखने अलग-अलग बैकग्राउंडस से आते हैं, उनके सिखने के ढंग भी अलग-अलग होते है। चाहे आप थेओरिटिकल ढंग से सीखना चाहे या प्रैक्टिकल से, हम आशा करते हैं कि यह अनुभाग आपके लिए मददगार साबित होगा।
+
+* अगर आप **करके** सीखना पसंद करते हैं, तो हमारे [प्रैक्टिकल टुटोरिअल](/tutorial/tutorial.html) के साथ शुरू करें। 
+* अगर आप इस **कॉन्सेप्ट्स को स्टेप बाय स्टेप** सीखना पसंद करते हैं, हमारे [मुख्य धारणा कि गाइड](/docs/hello-world.html) से शुरू करें।
+
+किसी भी अनजान टेक्नोलॉजी की तरह React की भी एक सीखने की अवस्था है। अभ्यास और धीरज के साथ आपको *जल्द ही* React समझ में आजाएगी।
+
+### पहला उदहारण {#first-examples}
+
+[React के होमपेज](/) में लाइव एडिटर के साथ React के कुछ छोटे उद्धरण हैं। अगर आप React के बारे में कुछ नहीं जानते तो कोड में कुछ बदलाव करके देखें कि वो कैसे परिणाम को बदलता है।
+
+### शुरू करने वालों के लिए React {#react-for-beginners}
+
+अगर आप को लगता है की React के दस्तावेज आपकी गति पर नहीं चल रहे तो [Tania Rascia के इस ओवरव्यू को देखें](https://www.taniarascia.com/getting-started-with-react/)। ये React के सबसे ज्यादा ज़रूरी कॉन्सेप्ट्स से आपका विस्तार और शुरुवातकर्ता-अनुकूल परिचय करता है। एक बार आप इसे पूरा करलें आप दस्तावेजों को दुबारा देख सकते हैं!
+
+### डिज़ाइनरों के लिए React {#react-for-designers}
+
+आगर आप डिज़ाइन बैकग्राउंड से आ रहे हैं, [ये साधन](https://reactfordesigners.com/) आपकी शुरुवात करने में मदद करेंगे।
+
+### जावास्क्रिप्ट के रिसोर्सेज़ {#javascript-resources}
+
+React के दस्तावेज़ मानते है की आपको जावास्क्रिप्ट लैंग्वेज की थोड़ी जानकारी है। आपको जावास्क्रिप्ट में माहिर होने कि ज़रूरत नहीं है, लेकिन जावास्क्रिप्ट और React को एक साथ सीखना मुश्किल हैं।
+
+हम अनुरोध करते है की आप [इस जावास्क्रिप्ट के ओवरव्यू को देखे](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript) ताकि आप अपने जानकारी के स्तर को आक सकें। इसमें आपको आधे से एक घंटा लगेगा लेकिन आप React सीखने में अधिक आत्मविश्वास महसूस करेंगे।
+
+>सुझाव 
+>
+>जब भी आप किसी जावास्क्रिप्ट की चीज़ की वजह से उलझन में पड जाएं तो [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript) और  [javascript.info](https://javascript.info/) जाँच करने के लिए बहुत अच्छी वेबसाइटस हैं। [कम्युनिटी सहायता मंच](/community/support.html) पे भी आप मदद माँग सकते हैं।
+
+### प्रैक्टिकल टुटोरिअल {#practical-tutorial}
+
+अगर आप **कर के** सीखना पसंद करते हैं तो हमारा [प्रैक्टिकल टुटोरिअल देखें](/tutorial/tutorial.html). इस टुटोरिअल में हम एक टिक-टैक्-टो का गेम बनाएँगे। हो सकता है आपको ऐसा लगे की हमें ये छोड़ देना चाहिए क्योकि हम कोई गेम नहीं बना रहे -- लेकिन इसे एक मौका दें। इसमें सीखी गई विधियां *किसी भी* React ऐप को बनाने में काम आएगी, और इसका अच्छा अभ्यास आपको React की गहरी समझ देगा। 
+
+### स्टेप-बाय-स्टेप गाइड {#step-by-step-guide}
+
+अगर आप React के **कांसेप्ट को स्टेप-बाय-स्टेप सीखना** पसंद करते हैं तो हमारी [मुख्य कॉन्सेप्ट्स की गाइड](/docs/hello-world.html) शुरू करने की लिए एक उत्तम जगह है। इसमें हर अगला अध्याय पिछले अध्यायों पर बना है तो इससे आप से कुछ छूटेगा नहीं।
+
+### React में सोचें {#thinking-in-react}
+
+बहुत सारे React के यूज़र्स [React में सोचे](/docs/thinking-in-react.html) पढ़ने को उनकी React की समझ बढ़ाने में मदद करने का क्रेडिट देते हैं, वह समझते हैं की इसको पढ़ने के बाद ही उन्हें React समझ में आई। ये React के सबसे पुराने वॉकथ्रू में से एक है लेकिन यह अभी भी उतना ही उचित है।
+
+### रेकमेंडेड कोर्सेज {#recommended-courses}
+
+कभी-कभी लोगों को अन्य पार्टियों कि किताबें और वीडियो कोर्सेज़ ऑफिसियल दस्तावेज़ों से ज़्यादा मददगार लगती है। हम एक [आम तौर पर इस्तेमाल करे जाने वाले साधनो की सूचि](/community/courses.html) बनाए रखते हैं, जिनमे से कुछ मुफ्त हैं।
+
+### एडवांस्ड कॉन्सेप्ट्स {#advanced-concepts}
+
+जब आप [मुख्य कॉन्सेप्ट्स](/docs/hello-world.html) के साथ सहज महसूस करना शुरू कर दें और React का थोड़ा अभ्यास करलें, हो सकता है आपको एडवांस्ड विषयों में भी दिलचस्पी हों। यह भाग आपको ताकतवर लेकिन कम इस्तेमाल किये जाने वाली React की खासियत जैसे कि [context](/docs/context.html) और [refs](/docs/refs-and-the-dom.html) से आपका परिचय करवाएगा।
+
+### API रिफरेन्स {#api-reference}
+
+अगर आप किसी विशेष React API के बारे में और जानना चाह रहें हैं यह दस्तावेज़ का भाग आपके काम आएगा। उदहारण के लिए, [`React.Component` API रिफरेन्स](/docs/react-component.html) आपको `setState()` कैसे काम करता है, और दूसरे लाइफसाइकिल मेथड्स किस काम के हैं इनपर आपको विवरण दे सखता है। 
+
+### शब्दकोष और FAQ {#glossary-and-faq}
+
+यह [शब्दकोष](/docs/glossary.html) React के दस्तावेज़ों में सबसे ज़्यादा बार आने वाले शब्दों का एक ओवरव्यू है। [AJAX रिक्वैस्ट करना](/docs/faq-ajax.html), [कॉम्पोनेन्ट state](/docs/faq-state.html), और [फाइल स्ट्रक्चर](/docs/faq-structure.html) के साथ यहाँ सामान्य विषयों के बारे में छोटे प्रशनों और उत्तरों के लिए एक FAQ सेक्शन भी है। 
+
+## जागृत रहें {#staying-informed}
+
+[React ब्लॉग](/blog/) React टीम के द्वारा अपडेट्स के लिए एक ओफ़िशिअल स्रोत है, इसमें कोई भी आवशयक सूचना जैसे की रिलीज़ नोट्स और डेप्रिसिएशन की सूचनाए सबसे पहले आती हैं।
+
+आप ट्विटर पर [@reactjs का अकाउंट](https://twitter.com/reactjs) भी फॉलो कर सकते हैं, लेकिन अगर आप हमारा ब्लॉग पढ़ते हैं तो आप कोई ज़रूरी चीज़ नहीं छोड़ेंगे। 
+
+हर React रिलीज़ अपने ब्लॉग पोस्ट के लायक नहीं होती है लेकिन हर रिलीज़ का पूरा चेंज लोग आपको [`CHANGELOG.md` फाइल जो React की रिपॉजिटरी में है](https://github.com/facebook/react/blob/master/CHANGELOG.md) या [Release](https://github.com/facebook/react/releases) पेज पर मिल जाएगा। 
+
+## वर्ज़न्ड दस्तावेज़ {#versioned-documentation}
+
+ये दस्तावेज़ हमेशा React के लेटेस्ट स्टेबल वर्ज़न पे आधारित होते हैं। आप React 16 के बाद के सारे दस्तावेज़ एक [अलग पेज पर](/versions) पा सकते हैं। ध्यान दें की सारे पिछले वर्ज़न अपने रिलीज़ के समय जैसे थे वैसे ही हैं और इनमें लगातार बदलाव नहीं किये जाते।
+
+## क्या कुछ छूट रहा है? {#something-missing}  
+
+अगर आप को लग रहा है की इन दस्तावेज़ों में कुछ छूटा है या आपको कुछ समझ नहीं आ रहा है तो कृपया अपने सुझाव के साथ [दस्तावेज़ रिपॉजिटरी में एक इशू दर्ज करें](https://github.com/reactjs/reactjs.org/issues/new) ताकि हम सुधार की ओर बढ़ सकें, या फिर आप [@reactjs के अकाउंट](https://twitter.com/reactjs) पर ट्वीट भी कर सकते हैं। हम आपसे सुन्ना बेहद पसंद करेंगे। 
diff --git a/handling-events.md b/handling-events.md
new file mode 100644
index 000000000..175303c24
--- /dev/null
+++ b/handling-events.md
@@ -0,0 +1,154 @@
+---
+id: handling-events
+title: Handling Events
+permalink: docs/handling-events.html
+prev: state-and-lifecycle.html
+next: conditional-rendering.html
+redirect_from:
+  - "docs/events-ko-KR.html"
+---
+
+Handling events with React elements is very similar to handling events on DOM elements. There are some syntactic differences:
+
+* React events are named using camelCase, rather than lowercase.
+* With JSX you pass a function as the event handler, rather than a string.
+
+For example, the HTML:
+
+```html
+<button onclick="activateLasers()">
+  Activate Lasers
+</button>
+```
+
+is slightly different in React:
+
+```js{1}
+<button onClick={activateLasers}>
+  Activate Lasers
+</button>
+```
+
+Another difference is that you cannot return `false` to prevent default behavior in React. You must call `preventDefault` explicitly. For example, with plain HTML, to prevent the default link behavior of opening a new page, you can write:
+
+```html
+<a href="#" onclick="console.log('The link was clicked.'); return false">
+  Click me
+</a>
+```
+
+In React, this could instead be:
+
+```js{2-5,8}
+function ActionLink() {
+  function handleClick(e) {
+    e.preventDefault();
+    console.log('The link was clicked.');
+  }
+
+  return (
+    <a href="#" onClick={handleClick}>
+      Click me
+    </a>
+  );
+}
+```
+
+Here, `e` is a synthetic event. React defines these synthetic events according to the [W3C spec](https://www.w3.org/TR/DOM-Level-3-Events/), so you don't need to worry about cross-browser compatibility. See the [`SyntheticEvent`](/docs/events.html) reference guide to learn more.
+
+When using React you should generally not need to call `addEventListener` to add listeners to a DOM element after it is created. Instead, just provide a listener when the element is initially rendered.
+
+When you define a component using an [ES6 class](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Classes), a common pattern is for an event handler to be a method on the class. For example, this `Toggle` component renders a button that lets the user toggle between "ON" and "OFF" states:
+
+```js{6,7,10-14,18}
+class Toggle extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {isToggleOn: true};
+
+    // This binding is necessary to make `this` work in the callback
+    this.handleClick = this.handleClick.bind(this);
+  }
+
+  handleClick() {
+    this.setState(state => ({
+      isToggleOn: !state.isToggleOn
+    }));
+  }
+
+  render() {
+    return (
+      <button onClick={this.handleClick}>
+        {this.state.isToggleOn ? 'ON' : 'OFF'}
+      </button>
+    );
+  }
+}
+
+ReactDOM.render(
+  <Toggle />,
+  document.getElementById('root')
+);
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/xEmzGg?editors=0010)
+
+You have to be careful about the meaning of `this` in JSX callbacks. In JavaScript, class methods are not [bound](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_objects/Function/bind) by default. If you forget to bind `this.handleClick` and pass it to `onClick`, `this` will be `undefined` when the function is actually called.
+
+This is not React-specific behavior; it is a part of [how functions work in JavaScript](https://www.smashingmagazine.com/2014/01/understanding-javascript-function-prototype-bind/). Generally, if you refer to a method without `()` after it, such as `onClick={this.handleClick}`, you should bind that method.
+
+If calling `bind` annoys you, there are two ways you can get around this. If you are using the experimental [public class fields syntax](https://babeljs.io/docs/plugins/transform-class-properties/), you can use class fields to correctly bind callbacks:
+
+```js{2-6}
+class LoggingButton extends React.Component {
+  // This syntax ensures `this` is bound within handleClick.
+  // Warning: this is *experimental* syntax.
+  handleClick = () => {
+    console.log('this is:', this);
+  }
+
+  render() {
+    return (
+      <button onClick={this.handleClick}>
+        Click me
+      </button>
+    );
+  }
+}
+```
+
+This syntax is enabled by default in [Create React App](https://github.com/facebookincubator/create-react-app).
+
+If you aren't using class fields syntax, you can use an [arrow function](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Functions/Arrow_functions) in the callback:
+
+```js{7-9}
+class LoggingButton extends React.Component {
+  handleClick() {
+    console.log('this is:', this);
+  }
+
+  render() {
+    // This syntax ensures `this` is bound within handleClick
+    return (
+      <button onClick={(e) => this.handleClick(e)}>
+        Click me
+      </button>
+    );
+  }
+}
+```
+
+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 {#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:
+
+```js
+<button onClick={(e) => this.deleteRow(id, e)}>Delete Row</button>
+<button onClick={this.deleteRow.bind(this, id)}>Delete Row</button>
+```
+
+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.
diff --git a/hello-world.md b/hello-world.md
new file mode 100644
index 000000000..ef36d543d
--- /dev/null
+++ b/hello-world.md
@@ -0,0 +1,49 @@
+---
+id: hello-world
+title: नमस्ते दुनिया
+permalink: docs/hello-world.html
+prev: cdn-links.html
+next: introducing-jsx.html
+---
+
+React का सबसे छोटा उदाहरण ऐसा दिखता है:
+
+```js
+ReactDOM.render(
+  <h1>नमस्ते, दुनिया!</h1>,
+  document.getElementById('root')
+);
+```
+
+यह पृष्ठ के शीर्षक पर "नमस्ते, दुनिया! दिखाएगा।
+
+[](codepen://hello-world)
+
+ऑनलाइन एडीटर खोलने के लिए ऊपर दिए गए लिंक पर क्लिक करें। अपनी और से बदलाव करने में संकोच ना करे, और देखें कि वे आउटपुट को कैसे प्रभावित करते हैं। इस गाइड के अधिकांश पृष्ठों में इस तरह के और भी उदाहरण होंगे जिन में आप बदलाव कर सकेंगे।
+
+
+## इस गाइड को कैसे पढ़ें {#how-to-read-this-guide}
+
+इस गाइड में, हम React एप्लिकेशन के बिल्डिंग ब्लॉक्स: एलिमेंट्स और कौम्पोनॅन्ट्स की जांच करेंगे। एक बार जब आप इसमे महारत हासिल कर लेते हैं, तो आप छोटे टुकड़ों को पुन: इस्तेमाल कर के कॉम्प्लेक्स एप्लिकेशन बना सकेंगे।
+
+>टिप
+>
+>यह मार्गदर्शिका ऐसे लोगों के लिए डिज़ाइन की गई है जो **कॉन्सेप्ट्स को एक एक कर के** सीखना पसंद करते हैं। यदि आप ऐसा करके सीखना पसंद करते हैं, तो हमारे [प्रैक्टिकल ट्यूटोरियल](/tutorial/tutorial.html) को देखें। आपको यह मार्गदर्शिका और ट्यूटोरियल एक-दूसरे के पूरक लग सकते हैं।
+
+मुख्य React कॉन्सेप्ट्स की इस मार्गदर्शिका में यह पहला अध्याय है। आप नेविगेशन साइडबार में इसके सभी अध्यायों की सूची देख सकते हैं। यदि आप इसे मोबाइल डिवाइस से पढ़ रहे हैं, तो आप अपनी स्क्रीन के निचले दाएं कोने में बटन दबाकर नेविगेशन का उपयोग कर सकते हैं।
+
+इस मार्गदर्शिका का प्रत्येक अध्याय पहले के अध्यायों में प्रस्तुत ज्ञान पर आधारित है। आप एडिशनल साइडबार में दिखाई देने वाले “मेन कॉन्सेप्ट्स” गाइड चैप्टर्स को क्रम में पढ़कर React के अधिकतर कॉन्सेप्ट्स को सीख सकते हैं। उदाहरण के लिए, [“JSX का परिचय”](/docs/introducing-jsx.html) इस के बाद अगला अध्याय है।
+
+## ज्ञान स्तर की मान्यताएँ {#knowledge-level-assumptions}
+
+React एक जावास्क्रिप्ट लाइब्रेरी है, और इसलिए हम ये मान कर चलेंगे की आपको जावास्क्रिप्ट भाषा की बुनियादी समझ है। **यदि आप जावास्क्रिप्ट में कॉंफिडेंट नहीं हैं, तो हम अनुशंसा करते हैं कि आप अपने ज्ञान के स्तर की जांच करने के लिए एक [जावास्क्रिप्ट ट्यूटोरियल से गुजरें](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript)** ताकि यह आपको बिना खोए इस गाइड का अनुसरण करने में सक्षम करें।  यह ट्यूटोरियल करने में आपको 30 मिनट से ले कर एक घंटे के बीच ले सकता है, लेकिन इसके परिणामस्वरूप आपको यह महसूस नहीं होगा कि आप एक ही समय में React और जावास्क्रिप्ट दोनों सीख रहे हैं।
+
+>ध्यान दें
+>
+>यदि आपने पिछले कुछ वर्षों में जावास्क्रिप्ट के साथ काम नहीं किया है, तो [इन तीन बिंदुओं](https://gist.github.com/gaearon/683e676101005de0add59e8bb345340c) को पढ़कर आप पर्याप्त जानकारी प्राप्त कर सकते है।
+
+## आइये शुरू करें! {#lets-get-started}
+
+नीचे स्क्रोल करते रहें, और आपको वेबसाइट फुटर से ठीक पहले [इस गाइड के अगले अध्याय](/docs/introducing-jsx.html) का लिंक मिल जाएगा।
+
+
diff --git a/higher-order-components.md b/higher-order-components.md
new file mode 100644
index 000000000..a7a123abe
--- /dev/null
+++ b/higher-order-components.md
@@ -0,0 +1,399 @@
+---
+id: higher-order-components
+title: Higher-Order Components
+permalink: docs/higher-order-components.html
+---
+
+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.
+
+Concretely, **a higher-order component is a function that takes a component and returns a new component.**
+
+```js
+const EnhancedComponent = higherOrderComponent(WrappedComponent);
+```
+
+Whereas a component transforms props into UI, a higher-order component transforms a component into another component.
+
+HOCs are common in third-party React libraries, such as Redux's [`connect`](https://github.com/reduxjs/react-redux/blob/master/docs/api/connect.md#connect) and Relay's [`createFragmentContainer`](http://facebook.github.io/relay/docs/en/fragment-container.html).
+
+In this document, we'll discuss why higher-order components are useful, and how to write your own.
+
+## Use HOCs For Cross-Cutting Concerns {#use-hocs-for-cross-cutting-concerns}
+
+> **Note**
+>
+> 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](/blog/2016/07/13/mixins-considered-harmful.html) about why we've moved away from mixins and how you can transition your existing components.
+
+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.
+
+For example, say you have a `CommentList` component that subscribes to an external data source to render a list of comments:
+
+```js
+class CommentList extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleChange = this.handleChange.bind(this);
+    this.state = {
+      // "DataSource" is some global data source
+      comments: DataSource.getComments()
+    };
+  }
+
+  componentDidMount() {
+    // Subscribe to changes
+    DataSource.addChangeListener(this.handleChange);
+  }
+
+  componentWillUnmount() {
+    // Clean up listener
+    DataSource.removeChangeListener(this.handleChange);
+  }
+
+  handleChange() {
+    // Update component state whenever the data source changes
+    this.setState({
+      comments: DataSource.getComments()
+    });
+  }
+
+  render() {
+    return (
+      <div>
+        {this.state.comments.map((comment) => (
+          <Comment comment={comment} key={comment.id} />
+        ))}
+      </div>
+    );
+  }
+}
+```
+
+Later, you write a component for subscribing to a single blog post, which follows a similar pattern:
+
+```js
+class BlogPost extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleChange = this.handleChange.bind(this);
+    this.state = {
+      blogPost: DataSource.getBlogPost(props.id)
+    };
+  }
+
+  componentDidMount() {
+    DataSource.addChangeListener(this.handleChange);
+  }
+
+  componentWillUnmount() {
+    DataSource.removeChangeListener(this.handleChange);
+  }
+
+  handleChange() {
+    this.setState({
+      blogPost: DataSource.getBlogPost(this.props.id)
+    });
+  }
+
+  render() {
+    return <TextBlock text={this.state.blogPost} />;
+  }
+}
+```
+
+`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:
+
+- On mount, add a change listener to `DataSource`.
+- Inside the listener, call `setState` whenever the data source changes.
+- On unmount, remove the change listener.
+
+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 it across many components. This is where higher-order components excel.
+
+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`:
+
+```js
+const CommentListWithSubscription = withSubscription(
+  CommentList,
+  (DataSource) => DataSource.getComments()
+);
+
+const BlogPostWithSubscription = withSubscription(
+  BlogPost,
+  (DataSource, props) => DataSource.getBlogPost(props.id)
+);
+```
+
+The first parameter is the wrapped component. The second parameter retrieves the data we're interested in, given a `DataSource` and the current props.
+
+When `CommentListWithSubscription` and `BlogPostWithSubscription` are rendered, `CommentList` and `BlogPost` will be passed a `data` prop with the most current data retrieved from `DataSource`:
+
+```js
+// This function takes a component...
+function withSubscription(WrappedComponent, selectData) {
+  // ...and returns another component...
+  return class extends React.Component {
+    constructor(props) {
+      super(props);
+      this.handleChange = this.handleChange.bind(this);
+      this.state = {
+        data: selectData(DataSource, props)
+      };
+    }
+
+    componentDidMount() {
+      // ... that takes care of the subscription...
+      DataSource.addChangeListener(this.handleChange);
+    }
+
+    componentWillUnmount() {
+      DataSource.removeChangeListener(this.handleChange);
+    }
+
+    handleChange() {
+      this.setState({
+        data: selectData(DataSource, this.props)
+      });
+    }
+
+    render() {
+      // ... and renders the wrapped component with the fresh data!
+      // Notice that we pass through any additional props
+      return <WrappedComponent data={this.state.data} {...this.props} />;
+    }
+  };
+}
+```
+
+Note that a HOC doesn't modify the input component, nor does it use inheritance to copy its behavior. Rather, a HOC *composes* the original component by *wrapping* it in a container component. A HOC is a pure function with zero side-effects.
+
+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.
+
+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.
+
+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.
+
+## Don't Mutate the Original Component. Use Composition. {#dont-mutate-the-original-component-use-composition}
+
+Resist the temptation to modify a component's prototype (or otherwise mutate it) inside a HOC.
+
+```js
+function logProps(InputComponent) {
+  InputComponent.prototype.componentWillReceiveProps = function(nextProps) {
+    console.log('Current props: ', this.props);
+    console.log('Next props: ', nextProps);
+  };
+  // The fact that we're returning the original input is a hint that it has
+  // been mutated.
+  return InputComponent;
+}
+
+// EnhancedComponent will log whenever props are received
+const EnhancedComponent = logProps(InputComponent);
+```
+
+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 `componentWillReceiveProps`, the first HOC's functionality will be overridden! This HOC also won't work with function components, which do not have lifecycle methods.
+
+Mutating HOCs are a leaky abstraction—the consumer must know how they are implemented in order to avoid conflicts with other HOCs.
+
+Instead of mutation, HOCs should use composition, by wrapping the input component in a container component:
+
+```js
+function logProps(WrappedComponent) {
+  return class extends React.Component {
+    componentWillReceiveProps(nextProps) {
+      console.log('Current props: ', this.props);
+      console.log('Next props: ', nextProps);
+    }
+    render() {
+      // Wraps the input component in a container, without mutating it. Good!
+      return <WrappedComponent {...this.props} />;
+    }
+  }
+}
+```
+
+This HOC has the same functionality as the mutating version while avoiding the potential for clashes. It works equally well with class and function components. And because it's a pure function, it's composable with other HOCs, or even with itself.
+
+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.
+
+## Convention: Pass Unrelated Props Through to the Wrapped Component {#convention-pass-unrelated-props-through-to-the-wrapped-component}
+
+HOCs add features to a component. They shouldn't drastically alter its contract. It's expected that the component returned from a HOC has a similar interface to the wrapped component.
+
+HOCs should pass through props that are unrelated to its specific concern. Most HOCs contain a render method that looks something like this:
+
+```js
+render() {
+  // Filter out extra props that are specific to this HOC and shouldn't be
+  // passed through
+  const { extraProp, ...passThroughProps } = this.props;
+
+  // Inject props into the wrapped component. These are usually state values or
+  // instance methods.
+  const injectedProp = someStateOrInstanceMethod;
+
+  // Pass props to wrapped component
+  return (
+    <WrappedComponent
+      injectedProp={injectedProp}
+      {...passThroughProps}
+    />
+  );
+}
+```
+
+This convention helps ensure that HOCs are as flexible and reusable as possible.
+
+## Convention: Maximizing Composability {#convention-maximizing-composability}
+
+Not all HOCs look the same. Sometimes they accept only a single argument, the wrapped component:
+
+```js
+const NavbarWithRouter = withRouter(Navbar);
+```
+
+Usually, HOCs accept additional arguments. In this example from Relay, a config object is used to specify a component's data dependencies:
+
+```js
+const CommentWithRelay = Relay.createContainer(Comment, config);
+```
+
+The most common signature for HOCs looks like this:
+
+```js
+// React Redux's `connect`
+const ConnectedComment = connect(commentSelector, commentActions)(CommentList);
+```
+
+*What?!* If you break it apart, it's easier to see what's going on.
+
+```js
+// connect is a function that returns another function
+const enhance = connect(commentListSelector, commentListActions);
+// The returned function is a HOC, which returns a component that is connected
+// to the Redux store
+const ConnectedComment = enhance(CommentList);
+```
+In other words, `connect` is a higher-order function that returns a higher-order component!
+
+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.
+
+```js
+// Instead of doing this...
+const EnhancedComponent = withRouter(connect(commentSelector)(WrappedComponent))
+
+// ... you can use a function composition utility
+// compose(f, g, h) is the same as (...args) => f(g(h(...args)))
+const enhance = compose(
+  // These are both single-argument HOCs
+  withRouter,
+  connect(commentSelector)
+)
+const EnhancedComponent = enhance(WrappedComponent)
+```
+
+(This same property also allows `connect` and other enhancer-style HOCs to be used as decorators, an experimental JavaScript proposal.)
+
+The `compose` utility function is provided by many third-party libraries including lodash (as [`lodash.flowRight`](https://lodash.com/docs/#flowRight)), [Redux](https://redux.js.org/api/compose), and [Ramda](https://ramdajs.com/docs/#compose).
+
+## Convention: Wrap the Display Name for Easy Debugging {#convention-wrap-the-display-name-for-easy-debugging}
+
+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 a HOC.
+
+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)`:
+
+```js
+function withSubscription(WrappedComponent) {
+  class WithSubscription extends React.Component {/* ... */}
+  WithSubscription.displayName = `WithSubscription(${getDisplayName(WrappedComponent)})`;
+  return WithSubscription;
+}
+
+function getDisplayName(WrappedComponent) {
+  return WrappedComponent.displayName || WrappedComponent.name || 'Component';
+}
+```
+
+
+## Caveats {#caveats}
+
+Higher-order components come with a few caveats that aren't immediately obvious if you're new to React.
+
+### Don't Use HOCs Inside the render Method {#dont-use-hocs-inside-the-render-method}
+
+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.
+
+Normally, you shouldn't need to think about this. But it matters for HOCs because it means you can't apply a HOC to a component within the render method of a component:
+
+```js
+render() {
+  // A new version of EnhancedComponent is created on every render
+  // EnhancedComponent1 !== EnhancedComponent2
+  const EnhancedComponent = enhance(MyComponent);
+  // That causes the entire subtree to unmount/remount each time!
+  return <EnhancedComponent />;
+}
+```
+
+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.
+
+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.
+
+In those rare cases where you need to apply a HOC dynamically, you can also do it inside a component's lifecycle methods or its constructor.
+
+### Static Methods Must Be Copied Over {#static-methods-must-be-copied-over}
+
+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.
+
+When you apply a 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.
+
+```js
+// Define a static method
+WrappedComponent.staticMethod = function() {/*...*/}
+// Now apply a HOC
+const EnhancedComponent = enhance(WrappedComponent);
+
+// The enhanced component has no static method
+typeof EnhancedComponent.staticMethod === 'undefined' // true
+```
+
+To solve this, you could copy the methods onto the container before returning it:
+
+```js
+function enhance(WrappedComponent) {
+  class Enhance extends React.Component {/*...*/}
+  // Must know exactly which method(s) to copy :(
+  Enhance.staticMethod = WrappedComponent.staticMethod;
+  return Enhance;
+}
+```
+
+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:
+
+```js
+import hoistNonReactStatic from 'hoist-non-react-statics';
+function enhance(WrappedComponent) {
+  class Enhance extends React.Component {/*...*/}
+  hoistNonReactStatic(Enhance, WrappedComponent);
+  return Enhance;
+}
+```
+
+Another possible solution is to export the static method separately from the component itself.
+
+```js
+// Instead of...
+MyComponent.someFunction = someFunction;
+export default MyComponent;
+
+// ...export the method separately...
+export { someFunction };
+
+// ...and in the consuming module, import both
+import MyComponent, { someFunction } from './MyComponent.js';
+```
+
+### Refs Aren't Passed Through {#refs-arent-passed-through}
+
+While the convention for higher-order components is to pass through all props to the wrapped component, this does not work for 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 a HOC, the ref refers to an instance of the outermost container component, not the wrapped component.
+
+The solution for this problem is to use the `React.forwardRef` API (introduced with React 16.3). [Learn more about it in the forwarding refs section](/docs/forwarding-refs.html).
diff --git a/hooks-custom.md b/hooks-custom.md
new file mode 100644
index 000000000..e8b8883a9
--- /dev/null
+++ b/hooks-custom.md
@@ -0,0 +1,252 @@
+---
+id: hooks-custom
+title: Building Your Own Hooks
+permalink: docs/hooks-custom.html
+next: hooks-reference.html
+prev: hooks-rules.html
+---
+
+*Hooks* are a new addition in React 16.8. They let you use state and other React features without writing a class.
+
+Building your own Hooks lets you extract component logic into reusable functions.
+
+When we were learning about [using the Effect Hook](/docs/hooks-effect.html#example-using-hooks-1), we saw this component from a chat application that displays a message indicating whether a friend is online or offline:
+
+```js{4-15}
+import React, { useState, useEffect } from 'react';
+
+function FriendStatus(props) {
+  const [isOnline, setIsOnline] = useState(null);
+
+  useEffect(() => {
+    function handleStatusChange(status) {
+      setIsOnline(status.isOnline);
+    }
+
+    ChatAPI.subscribeToFriendStatus(props.friend.id, handleStatusChange);
+    return () => {
+      ChatAPI.unsubscribeFromFriendStatus(props.friend.id, handleStatusChange);
+    };
+  });
+
+  if (isOnline === null) {
+    return 'Loading...';
+  }
+  return isOnline ? 'Online' : 'Offline';
+}
+```
+
+Now let's say that our chat application also has a contact list, and we want to render names of online users with a green color. We could copy and paste similar logic above into our `FriendListItem` component but it wouldn't be ideal:
+
+```js{4-15}
+import React, { useState, useEffect } from 'react';
+
+function FriendListItem(props) {
+  const [isOnline, setIsOnline] = useState(null);
+
+  useEffect(() => {
+    function handleStatusChange(status) {
+      setIsOnline(status.isOnline);
+    }
+
+    ChatAPI.subscribeToFriendStatus(props.friend.id, handleStatusChange);
+    return () => {
+      ChatAPI.unsubscribeFromFriendStatus(props.friend.id, handleStatusChange);
+    };
+  });
+
+  return (
+    <li style={{ color: isOnline ? 'green' : 'black' }}>
+      {props.friend.name}
+    </li>
+  );
+}
+```
+
+Instead, we'd like to share this logic between `FriendStatus` and `FriendListItem`.
+
+Traditionally in React, we've had two popular ways to share stateful logic between components: [render props](/docs/render-props.html) and [higher-order components](/docs/higher-order-components.html). We will now look at how Hooks solve many of the same problems without forcing you to add more components to the tree.
+
+## Extracting a Custom Hook {#extracting-a-custom-hook}
+
+When we want to share logic between two JavaScript functions, we extract it to a third function. Both components and Hooks are functions, so this works for them too!
+
+**A custom Hook is a JavaScript function whose name starts with "`use`" and that may call other Hooks.** For example, `useFriendStatus` below is our first custom Hook:
+
+```js{3}
+import React, { useState, useEffect } from 'react';
+
+function useFriendStatus(friendID) {
+  const [isOnline, setIsOnline] = useState(null);
+
+  useEffect(() => {
+    function handleStatusChange(status) {
+      setIsOnline(status.isOnline);
+    }
+
+    ChatAPI.subscribeToFriendStatus(friendID, handleStatusChange);
+    return () => {
+      ChatAPI.unsubscribeFromFriendStatus(friendID, handleStatusChange);
+    };
+  });
+
+  return isOnline;
+}
+```
+
+There's nothing new inside of it -- the logic is copied from the components above. Just like in a component, make sure to only call other Hooks unconditionally at the top level of your custom Hook.
+
+Unlike a React component, a custom Hook doesn't need to have a specific signature. We can decide what it takes as arguments, and what, if anything, it should return. In other words, it's just like a normal function. Its name should always start with `use` so that you can tell at a glance that the [rules of Hooks](/docs/hooks-rules.html) apply to it.
+
+The purpose of our `useFriendStatus` Hook is to subscribe us to a friend's status. This is why it takes `friendID` as an argument, and returns whether this friend is online:
+
+```js
+function useFriendStatus(friendID) {
+  const [isOnline, setIsOnline] = useState(null);
+
+  // ...
+
+  return isOnline;
+}
+```
+
+Now let's see how we can use our custom Hook.
+
+## Using a Custom Hook {#using-a-custom-hook}
+
+In the beginning, our stated goal was to remove the duplicated logic from the `FriendStatus` and `FriendListItem` components. Both of them want to know whether a friend is online.
+
+Now that we've extracted this logic to a `useFriendStatus` hook, we can *just use it:*
+
+```js{2}
+function FriendStatus(props) {
+  const isOnline = useFriendStatus(props.friend.id);
+
+  if (isOnline === null) {
+    return 'Loading...';
+  }
+  return isOnline ? 'Online' : 'Offline';
+}
+```
+
+```js{2}
+function FriendListItem(props) {
+  const isOnline = useFriendStatus(props.friend.id);
+
+  return (
+    <li style={{ color: isOnline ? 'green' : 'black' }}>
+      {props.friend.name}
+    </li>
+  );
+}
+```
+
+**Is this code equivalent to the original examples?** Yes, it works in exactly the same way. If you look closely, you'll notice we didn't make any changes to the behavior. All we did was to extract some common code between two functions into a separate function. **Custom Hooks are a convention that naturally follows from the design of Hooks, rather than a React feature.**
+
+**Do I have to name my custom Hooks starting with “`use`”?** Please do. This convention is very important. Without it, we wouldn't be able to automatically check for violations of [rules of Hooks](/docs/hooks-rules.html) because we couldn't tell if a certain function contains calls to Hooks inside of it.
+
+**Do two components using the same Hook share state?** No. Custom Hooks are a mechanism to reuse *stateful logic* (such as setting up a subscription and remembering the current value), but every time you use a custom Hook, all state and effects inside of it are fully isolated.
+
+**How does a custom Hook get isolated state?** Each *call* to a Hook gets isolated state. Because we call `useFriendStatus` directly, from React's point of view our component just calls `useState` and `useEffect`. And as we [learned](/docs/hooks-state.html#tip-using-multiple-state-variables) [earlier](/docs/hooks-effect.html#tip-use-multiple-effects-to-separate-concerns), we can call `useState` and `useEffect` many times in one component, and they will be completely independent.
+
+### Tip: Pass Information Between Hooks {#tip-pass-information-between-hooks}
+
+Since Hooks are functions, we can pass information between them.
+
+To illustrate this, we'll use another component from our hypothetical chat example. This is a chat message recipient picker that displays whether the currently selected friend is online:
+
+```js{8-9,13}
+const friendList = [
+  { id: 1, name: 'Phoebe' },
+  { id: 2, name: 'Rachel' },
+  { id: 3, name: 'Ross' },
+];
+
+function ChatRecipientPicker() {
+  const [recipientID, setRecipientID] = useState(1);
+  const isRecipientOnline = useFriendStatus(recipientID);
+
+  return (
+    <>
+      <Circle color={isRecipientOnline ? 'green' : 'red'} />
+      <select
+        value={recipientID}
+        onChange={e => setRecipientID(Number(e.target.value))}
+      >
+        {friendList.map(friend => (
+          <option key={friend.id} value={friend.id}>
+            {friend.name}
+          </option>
+        ))}
+      </select>
+    </>
+  );
+}
+```
+
+We keep the currently chosen friend ID in the `recipientID` state variable, and update it if the user chooses a different friend in the `<select>` picker.
+
+Because the `useState` Hook call gives us the latest value of the `recipientID` state variable, we can pass it to our custom `useFriendStatus` Hook as an argument:
+
+```js
+  const [recipientID, setRecipientID] = useState(1);
+  const isRecipientOnline = useFriendStatus(recipientID);
+```
+
+This lets us know whether the *currently selected* friend is online. If we pick a different friend and update the `recipientID` state variable, our `useFriendStatus` Hook will unsubscribe from the previously selected friend, and subscribe to the status of the newly selected one.
+
+## `useYourImagination()` {#useyourimagination}
+
+Custom Hooks offer the flexibility of sharing logic that wasn't possible in React components before. You can write custom Hooks that cover a wide range of use cases like form handling, animation, declarative subscriptions, timers, and probably many more we haven't considered. What's more, you can build Hooks that are just as easy to use as React's built-in features.
+
+Try to resist adding abstraction too early. Now that function components can do more, it's likely that the average function component in your codebase will become longer. This is normal -- don't feel like you *have to* immediately split it into Hooks. But we also encourage you to start spotting cases where a custom Hook could hide complex logic behind a simple interface, or help untangle a messy component.
+
+For example, maybe you have a complex component that contains a lot of local state that is managed in an ad-hoc way. `useState` doesn't make centralizing the update logic any easier so you might prefer to write it as a [Redux](https://redux.js.org/) reducer:
+
+```js
+function todosReducer(state, action) {
+  switch (action.type) {
+    case 'add':
+      return [...state, {
+        text: action.text,
+        completed: false
+      }];
+    // ... other actions ...
+    default:
+      return state;
+  }
+}
+```
+
+Reducers are very convenient to test in isolation, and scale to express complex update logic. You can further break them apart into smaller reducers if necessary. However, you might also enjoy the benefits of using React local state, or might not want to install another library.
+
+So what if we could write a `useReducer` Hook that lets us manage the *local* state of our component with a reducer? A simplified version of it might look like this:
+
+```js
+function useReducer(reducer, initialState) {
+  const [state, setState] = useState(initialState);
+
+  function dispatch(action) {
+    const nextState = reducer(state, action);
+    setState(nextState);
+  }
+
+  return [state, dispatch];
+}
+```
+
+Now we could use it in our component, and let the reducer drive its state management:
+
+```js{2}
+function Todos() {
+  const [todos, dispatch] = useReducer(todosReducer, []);
+
+  function handleAddClick(text) {
+    dispatch({ type: 'add', text });
+  }
+
+  // ...
+}
+```
+
+The need to manage local state with a reducer in a complex component is common enough that we've built the `useReducer` Hook right into React. You'll find it together with other built-in Hooks in the [Hooks API reference](/docs/hooks-reference.html).
diff --git a/hooks-effect.md b/hooks-effect.md
new file mode 100644
index 000000000..86b3b6649
--- /dev/null
+++ b/hooks-effect.md
@@ -0,0 +1,489 @@
+---
+id: hooks-state
+title: Using the Effect Hook
+permalink: docs/hooks-effect.html
+next: hooks-rules.html
+prev: hooks-state.html
+---
+
+*Hooks* are a new addition in React 16.8. They let you use state and other React features without writing a class.
+
+The *Effect Hook* lets you perform side effects in function components:
+
+```js{1,6-10}
+import React, { useState, useEffect } from 'react';
+
+function Example() {
+  const [count, setCount] = useState(0);
+
+  // Similar to componentDidMount and componentDidUpdate:
+  useEffect(() => {
+    // Update the document title using the browser API
+    document.title = `You clicked ${count} times`;
+  });
+
+  return (
+    <div>
+      <p>You clicked {count} times</p>
+      <button onClick={() => setCount(count + 1)}>
+        Click me
+      </button>
+    </div>
+  );
+}
+```
+
+This snippet is based on the [counter example from the previous page](/docs/hooks-state.html), but we added a new feature to it: we set the document title to a custom message including the number of clicks.
+
+Data fetching, setting up a subscription, and manually changing the DOM in React components are all examples of side effects. Whether or not you're used to calling these operations "side effects" (or just "effects"), you've likely performed them in your components before.
+
+>Tip
+>
+>If you're familiar with React class lifecycle methods, you can think of `useEffect` Hook as `componentDidMount`, `componentDidUpdate`, and `componentWillUnmount` combined.
+
+There are two common kinds of side effects in React components: those that don't require cleanup, and those that do. Let's look at this distinction in more detail.
+
+## Effects Without Cleanup {#effects-without-cleanup}
+
+Sometimes, we want to **run some additional code after React has updated the DOM.** Network requests, manual DOM mutations, and logging are common examples of effects that don't require a cleanup. We say that because we can run them and immediately forget about them. Let's compare how classes and Hooks let us express such side effects.
+
+### Example Using Classes {#example-using-classes}
+
+In React class components, the `render` method itself shouldn't cause side effects. It would be too early -- we typically want to perform our effects *after* React has updated the DOM.
+
+This is why in React classes, we put side effects into `componentDidMount` and `componentDidUpdate`. Coming back to our example, here is a React counter class component that updates the document title right after React makes changes to the DOM:
+
+```js{9-15}
+class Example extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      count: 0
+    };
+  }
+
+  componentDidMount() {
+    document.title = `You clicked ${this.state.count} times`;
+  }
+
+  componentDidUpdate() {
+    document.title = `You clicked ${this.state.count} times`;
+  }
+
+  render() {
+    return (
+      <div>
+        <p>You clicked {this.state.count} times</p>
+        <button onClick={() => this.setState({ count: this.state.count + 1 })}>
+          Click me
+        </button>
+      </div>
+    );
+  }
+}
+```
+
+Note how **we have to duplicate the code between these two lifecycle methods in class.**
+
+This is because in many cases we want to perform the same side effect regardless of whether the component just mounted, or if it has been updated. Conceptually, we want it to happen after every render -- but React class components don't have a method like this. We could extract a separate method but we would still have to call it in two places.
+
+Now let's see how we can do the same with the `useEffect` Hook.
+
+### Example Using Hooks {#example-using-hooks}
+
+We've already seen this example at the top of this page, but let's take a closer look at it:
+
+```js{1,6-8}
+import React, { useState, useEffect } from 'react';
+
+function Example() {
+  const [count, setCount] = useState(0);
+
+  useEffect(() => {
+    document.title = `You clicked ${count} times`;
+  });
+
+  return (
+    <div>
+      <p>You clicked {count} times</p>
+      <button onClick={() => setCount(count + 1)}>
+        Click me
+      </button>
+    </div>
+  );
+}
+```
+
+**What does `useEffect` do?** By using this Hook, you tell React that your component needs to do something after render. React will remember the function you passed (we'll refer to it as our "effect"), and call it later after performing the DOM updates. In this effect, we set the document title, but we could also perform data fetching or call some other imperative API.
+
+**Why is `useEffect` called inside a component?** Placing `useEffect` inside the component lets us access the `count` state variable (or any props) right from the effect. We don't need a special API to read it -- it's already in the function scope. Hooks embrace JavaScript closures and avoid introducing React-specific APIs where JavaScript already provides a solution.
+
+**Does `useEffect` run after every render?** Yes! By default, it runs both after the first render *and* after every update. (We will later talk about [how to customize this](#tip-optimizing-performance-by-skipping-effects).) Instead of thinking in terms of "mounting" and "updating", you might find it easier to think that effects happen "after render". React guarantees the DOM has been updated by the time it runs the effects.
+
+### Detailed Explanation {#detailed-explanation}
+
+Now that we know more about effects, these lines should make sense:
+
+```js
+function Example() {
+  const [count, setCount] = useState(0);
+
+  useEffect(() => {
+    document.title = `You clicked ${count} times`;
+  });
+}
+```
+
+We declare the `count` state variable, and then we tell React we need to use an effect. We pass a function to the `useEffect` Hook. This function we pass *is* our effect. Inside our effect, we set the document title using the `document.title` browser API. We can read the latest `count` inside the effect because it's in the scope of our function. When React renders our component, it will remember the effect we used, and then run our effect after updating the DOM. This happens for every render, including the first one.
+
+Experienced JavaScript developers might notice that the function passed to `useEffect` is going to be different on every render. This is intentional. In fact, this is what lets us read the `count` value from inside the effect without worrying about it getting stale. Every time we re-render, we schedule a _different_ effect, replacing the previous one. In a way, this makes the effects behave more like a part of the render result -- each effect "belongs" to a particular render. We will see more clearly why this is useful [later on this page](#explanation-why-effects-run-on-each-update).
+
+>Tip
+>
+>Unlike `componentDidMount` or `componentDidUpdate`, effects scheduled with `useEffect` don't block the browser from updating the screen. This makes your app feel more responsive. The majority of effects don't need to happen synchronously. In the uncommon cases where they do (such as measuring the layout), there is a separate [`useLayoutEffect`](/docs/hooks-reference.html#uselayouteffect) Hook with an API identical to `useEffect`.
+
+## Effects with Cleanup {#effects-with-cleanup}
+
+Earlier, we looked at how to express side effects that don't require any cleanup. However, some effects do. For example, **we might want to set up a subscription** to some external data source. In that case, it is important to clean up so that we don't introduce a memory leak! Let's compare how we can do it with classes and with Hooks.
+
+### Example Using Classes {#example-using-classes-1}
+
+In a React class, you would typically set up a subscription in `componentDidMount`, and clean it up in `componentWillUnmount`. For example, let's say we have a `ChatAPI` module that lets us subscribe to a friend's online status. Here's how we might subscribe and display that status using a class:
+
+```js{8-26}
+class FriendStatus extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = { isOnline: null };
+    this.handleStatusChange = this.handleStatusChange.bind(this);
+  }
+
+  componentDidMount() {
+    ChatAPI.subscribeToFriendStatus(
+      this.props.friend.id,
+      this.handleStatusChange
+    );
+  }
+
+  componentWillUnmount() {
+    ChatAPI.unsubscribeFromFriendStatus(
+      this.props.friend.id,
+      this.handleStatusChange
+    );
+  }
+
+  handleStatusChange(status) {
+    this.setState({
+      isOnline: status.isOnline
+    });
+  }
+
+  render() {
+    if (this.state.isOnline === null) {
+      return 'Loading...';
+    }
+    return this.state.isOnline ? 'Online' : 'Offline';
+  }
+}
+```
+
+Notice how `componentDidMount` and `componentWillUnmount` need to mirror each other. Lifecycle methods force us to split this logic even though conceptually code in both of them is related to the same effect.
+
+>Note
+>
+>Eagle-eyed readers may notice that this example also needs a `componentDidUpdate` method to be fully correct. We'll ignore this for now but will come back to it in a [later section](#explanation-why-effects-run-on-each-update) of this page.
+
+### Example Using Hooks {#example-using-hooks-1}
+
+Let's see how we could write this component with Hooks.
+
+You might be thinking that we'd need a separate effect to perform the cleanup. But code for adding and removing a subscription is so tightly related that `useEffect` is designed to keep it together. If your effect returns a function, React will run it when it is time to clean up:
+
+```js{6-16}
+import React, { useState, useEffect } from 'react';
+
+function FriendStatus(props) {
+  const [isOnline, setIsOnline] = useState(null);
+
+  useEffect(() => {
+    function handleStatusChange(status) {
+      setIsOnline(status.isOnline);
+    }
+
+    ChatAPI.subscribeToFriendStatus(props.friend.id, handleStatusChange);
+    // Specify how to clean up after this effect:
+    return function cleanup() {
+      ChatAPI.unsubscribeFromFriendStatus(props.friend.id, handleStatusChange);
+    };
+  });
+
+  if (isOnline === null) {
+    return 'Loading...';
+  }
+  return isOnline ? 'Online' : 'Offline';
+}
+```
+
+**Why did we return a function from our effect?** This is the optional cleanup mechanism for effects. Every effect may return a function that cleans up after it. This lets us keep the logic for adding and removing subscriptions close to each other. They're part of the same effect!
+
+**When exactly does React clean up an effect?** React performs the cleanup when the component unmounts. However, as we learned earlier, effects run for every render and not just once. This is why React *also* cleans up effects from the previous render before running the effects next time. We'll discuss [why this helps avoid bugs](#explanation-why-effects-run-on-each-update) and [how to opt out of this behavior in case it creates performance issues](#tip-optimizing-performance-by-skipping-effects) later below.
+
+>Note
+>
+>We don't have to return a named function from the effect. We called it `cleanup` here to clarify its purpose, but you could return an arrow function or call it something different.
+
+## Recap {#recap}
+
+We've learned that `useEffect` lets us express different kinds of side effects after a component renders. Some effects might require cleanup so they return a function:
+
+```js
+  useEffect(() => {
+    function handleStatusChange(status) {
+      setIsOnline(status.isOnline);
+    }
+
+    ChatAPI.subscribeToFriendStatus(props.friend.id, handleStatusChange);
+    return () => {
+      ChatAPI.unsubscribeFromFriendStatus(props.friend.id, handleStatusChange);
+    };
+  });
+```
+
+Other effects might not have a cleanup phase, and don't return anything.
+
+```js
+  useEffect(() => {
+    document.title = `You clicked ${count} times`;
+  });
+```
+
+The Effect Hook unifies both use cases with a single API.
+
+-------------
+
+**If you feel like you have a decent grasp on how the Effect Hook works, or if you feel overwhelmed, you can jump to the [next page about Rules of Hooks](/docs/hooks-rules.html) now.**
+
+-------------
+
+## Tips for Using Effects {#tips-for-using-effects}
+
+We'll continue this page with an in-depth look at some aspects of `useEffect` that experienced React users will likely be curious about. Don't feel obligated to dig into them now. You can always come back to this page to learn more details about the Effect Hook.
+
+### Tip: Use Multiple Effects to Separate Concerns {#tip-use-multiple-effects-to-separate-concerns}
+
+One of the problems we outlined in the [Motivation](/docs/hooks-intro.html#complex-components-become-hard-to-understand) for Hooks is that class lifecycle methods often contain unrelated logic, but related logic gets broken up into several methods. Here is a component that combines the counter and the friend status indicator logic from the previous examples:
+
+```js
+class FriendStatusWithCounter extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = { count: 0, isOnline: null };
+    this.handleStatusChange = this.handleStatusChange.bind(this);
+  }
+
+  componentDidMount() {
+    document.title = `You clicked ${this.state.count} times`;
+    ChatAPI.subscribeToFriendStatus(
+      this.props.friend.id,
+      this.handleStatusChange
+    );
+  }
+
+  componentDidUpdate() {
+    document.title = `You clicked ${this.state.count} times`;
+  }
+
+  componentWillUnmount() {
+    ChatAPI.unsubscribeFromFriendStatus(
+      this.props.friend.id,
+      this.handleStatusChange
+    );
+  }
+
+  handleStatusChange(status) {
+    this.setState({
+      isOnline: status.isOnline
+    });
+  }
+  // ...
+```
+
+Note how the logic that sets `document.title` is split between `componentDidMount` and `componentDidUpdate`. The subscription logic is also spread between `componentDidMount` and `componentWillUnmount`. And `componentDidMount` contains code for both tasks.
+
+So, how can Hooks solve this problem? Just like [you can use the *State* Hook more than once](/docs/hooks-state.html#tip-using-multiple-state-variables), you can also use several effects. This lets us separate unrelated logic into different effects:
+
+```js{3,8}
+function FriendStatusWithCounter(props) {
+  const [count, setCount] = useState(0);
+  useEffect(() => {
+    document.title = `You clicked ${count} times`;
+  });
+
+  const [isOnline, setIsOnline] = useState(null);
+  useEffect(() => {
+    function handleStatusChange(status) {
+      setIsOnline(status.isOnline);
+    }
+
+    ChatAPI.subscribeToFriendStatus(props.friend.id, handleStatusChange);
+    return () => {
+      ChatAPI.unsubscribeFromFriendStatus(props.friend.id, handleStatusChange);
+    };
+  });
+  // ...
+}
+```
+
+**Hooks let us split the code based on what it is doing** rather than a lifecycle method name. React will apply *every* effect used by the component, in the order they were specified.
+
+### Explanation: Why Effects Run on Each Update {#explanation-why-effects-run-on-each-update}
+
+If you're used to classes, you might be wondering why the effect cleanup phase happens after every re-render, and not just once during unmounting. Let's look at a practical example to see why this design helps us create components with fewer bugs.
+
+[Earlier on this page](#example-using-classes-1), we introduced an example `FriendStatus` component that displays whether a friend is online or not. Our class reads `friend.id` from `this.props`, subscribes to the friend status after the component mounts, and unsubscribes during unmounting:
+
+```js
+  componentDidMount() {
+    ChatAPI.subscribeToFriendStatus(
+      this.props.friend.id,
+      this.handleStatusChange
+    );
+  }
+
+  componentWillUnmount() {
+    ChatAPI.unsubscribeFromFriendStatus(
+      this.props.friend.id,
+      this.handleStatusChange
+    );
+  }
+```
+
+**But what happens if the `friend` prop changes** while the component is on the screen? Our component would continue displaying the online status of a different friend. This is a bug. We would also cause a memory leak or crash when unmounting since the unsubscribe call would use the wrong friend ID.
+
+In a class component, we would need to add `componentDidUpdate` to handle this case:
+
+```js{8-19}
+  componentDidMount() {
+    ChatAPI.subscribeToFriendStatus(
+      this.props.friend.id,
+      this.handleStatusChange
+    );
+  }
+
+  componentDidUpdate(prevProps) {
+    // Unsubscribe from the previous friend.id
+    ChatAPI.unsubscribeFromFriendStatus(
+      prevProps.friend.id,
+      this.handleStatusChange
+    );
+    // Subscribe to the next friend.id
+    ChatAPI.subscribeToFriendStatus(
+      this.props.friend.id,
+      this.handleStatusChange
+    );
+  }
+
+  componentWillUnmount() {
+    ChatAPI.unsubscribeFromFriendStatus(
+      this.props.friend.id,
+      this.handleStatusChange
+    );
+  }
+```
+
+Forgetting to handle `componentDidUpdate` properly is a common source of bugs in React applications.
+
+Now consider the version of this component that uses Hooks:
+
+```js
+function FriendStatus(props) {
+  // ...
+  useEffect(() => {
+    // ...
+    ChatAPI.subscribeToFriendStatus(props.friend.id, handleStatusChange);
+    return () => {
+      ChatAPI.unsubscribeFromFriendStatus(props.friend.id, handleStatusChange);
+    };
+  });
+```
+
+It doesn't suffer from this bug. (But we also didn't make any changes to it.)
+
+There is no special code for handling updates because `useEffect` handles them *by default*. It cleans up the previous effects before applying the next effects. To illustrate this, here is a sequence of subscribe and unsubscribe calls that this component could produce over time:
+
+```js
+// Mount with { friend: { id: 100 } } props
+ChatAPI.subscribeToFriendStatus(100, handleStatusChange);     // Run first effect
+
+// Update with { friend: { id: 200 } } props
+ChatAPI.unsubscribeFromFriendStatus(100, handleStatusChange); // Clean up previous effect
+ChatAPI.subscribeToFriendStatus(200, handleStatusChange);     // Run next effect
+
+// Update with { friend: { id: 300 } } props
+ChatAPI.unsubscribeFromFriendStatus(200, handleStatusChange); // Clean up previous effect
+ChatAPI.subscribeToFriendStatus(300, handleStatusChange);     // Run next effect
+
+// Unmount
+ChatAPI.unsubscribeFromFriendStatus(300, handleStatusChange); // Clean up last effect
+```
+
+This behavior ensures consistency by default and prevents bugs that are common in class components due to missing update logic.
+
+### Tip: Optimizing Performance by Skipping Effects {#tip-optimizing-performance-by-skipping-effects}
+
+In some cases, cleaning up or applying the effect after every render might create a performance problem. In class components, we can solve this by writing an extra comparison with `prevProps` or `prevState` inside `componentDidUpdate`:
+
+```js
+componentDidUpdate(prevProps, prevState) {
+  if (prevState.count !== this.state.count) {
+    document.title = `You clicked ${this.state.count} times`;
+  }
+}
+```
+
+This requirement is common enough that it is built into the `useEffect` Hook API. You can tell React to *skip* applying an effect if certain values haven't changed between re-renders. To do so, pass an array as an optional second argument to `useEffect`:
+
+```js{3}
+useEffect(() => {
+  document.title = `You clicked ${count} times`;
+}, [count]); // Only re-run the effect if count changes
+```
+
+In the example above, we pass `[count]` as the second argument. What does this mean? If the `count` is `5`, and then our component re-renders with `count` still equal to `5`, React will compare `[5]` from the previous render and `[5]` from the next render. Because all items in the array are the same (`5 === 5`), React would skip the effect. That's our optimization.
+
+When we render with `count` updated to `6`, React will compare the items in the `[5]` array from the previous render to items in the `[6]` array from the next render. This time, React will re-apply the effect because `5 !== 6`. If there are multiple items in the array, React will re-run the effect even if just one of them is different.
+
+This also works for effects that have a cleanup phase:
+
+```js{10}
+useEffect(() => {
+  function handleStatusChange(status) {
+    setIsOnline(status.isOnline);
+  }
+
+  ChatAPI.subscribeToFriendStatus(props.friend.id, handleStatusChange);
+  return () => {
+    ChatAPI.unsubscribeFromFriendStatus(props.friend.id, handleStatusChange);
+  };
+}, [props.friend.id]); // Only re-subscribe if props.friend.id changes
+```
+
+In the future, the second argument might get added automatically by a build-time transformation.
+
+>Note
+>
+>If you use this optimization, make sure the array includes **all values from the component scope (such as props and state) that change over time and that are used by the effect**. Otherwise, your code will reference stale values from previous renders. Learn more about [how to deal with functions](/docs/hooks-faq.html#is-it-safe-to-omit-functions-from-the-list-of-dependencies) and [what to do when the array changes too often](/docs/hooks-faq.html#what-can-i-do-if-my-effect-dependencies-change-too-often).
+>
+>If you want to run an effect and clean it up only once (on mount and unmount), you can pass an empty array (`[]`) as a second argument. This tells React that your effect doesn't depend on *any* values from props or state, so it never needs to re-run. This isn't handled as a special case -- it follows directly from how the dependencies array always works.
+>
+>If you pass an empty array (`[]`), the props and state inside the effect will always have their initial values. While passing `[]` as the second argument is closer to the familiar `componentDidMount` and `componentWillUnmount` mental model, there are usually [better](/docs/hooks-faq.html#is-it-safe-to-omit-functions-from-the-list-of-dependencies) [solutions](/docs/hooks-faq.html#what-can-i-do-if-my-effect-dependencies-change-too-often) to avoid re-running effects too often. Also, don't forget that React defers running `useEffect` until after the browser has painted, so doing extra work is less of a problem.
+>
+>We recommend using the [`exhaustive-deps`](https://github.com/facebook/react/issues/14920) rule as part of our [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks#installation) package. It warns when dependencies are specified incorrectly and suggests a fix.
+
+## Next Steps {#next-steps}
+
+Congratulations! This was a long page, but hopefully by the end most of your questions about effects were answered. You've learned both the State Hook and the Effect Hook, and there is a *lot* you can do with both of them combined. They cover most of the use cases for classes -- and where they don't, you might find the [additional Hooks](/docs/hooks-reference.html) helpful.
+
+We're also starting to see how Hooks solve problems outlined in [Motivation](/docs/hooks-intro.html#motivation). We've seen how effect cleanup avoids duplication in `componentDidUpdate` and `componentWillUnmount`, brings related code closer together, and helps us avoid bugs. We've also seen how we can separate effects by their purpose, which is something we couldn't do in classes at all.
+
+At this point you might be questioning how Hooks work. How can React know which `useState` call corresponds to which state variable between re-renders? How does React "match up" previous and next effects on every update? **On the next page we will learn about the [Rules of Hooks](/docs/hooks-rules.html) -- they're essential to making Hooks work.**
diff --git a/hooks-faq.md b/hooks-faq.md
new file mode 100644
index 000000000..9034ed817
--- /dev/null
+++ b/hooks-faq.md
@@ -0,0 +1,1000 @@
+---
+id: hooks-faq
+title: Hooks FAQ
+permalink: docs/hooks-faq.html
+prev: hooks-reference.html
+---
+
+*Hooks* are a new addition in React 16.8. They let you use state and other React features without writing a class.
+
+This page answers some of the frequently asked questions about [Hooks](/docs/hooks-overview.html).
+
+<!--
+  if you ever need to regenerate this, this snippet in the devtools console might help:
+
+  $$('.anchor').map(a =>
+    `${' '.repeat(2 * +a.parentNode.nodeName.slice(1))}` +
+    `[${a.parentNode.textContent}](${a.getAttribute('href')})`
+  ).join('\n')
+-->
+
+* **[Adoption Strategy](#adoption-strategy)**
+  * [Which versions of React include Hooks?](#which-versions-of-react-include-hooks)
+  * [Do I need to rewrite all my class components?](#do-i-need-to-rewrite-all-my-class-components)
+  * [What can I do with Hooks that I couldn't with classes?](#what-can-i-do-with-hooks-that-i-couldnt-with-classes)
+  * [How much of my React knowledge stays relevant?](#how-much-of-my-react-knowledge-stays-relevant)
+  * [Should I use Hooks, classes, or a mix of both?](#should-i-use-hooks-classes-or-a-mix-of-both)
+  * [Do Hooks cover all use cases for classes?](#do-hooks-cover-all-use-cases-for-classes)
+  * [Do Hooks replace render props and higher-order components?](#do-hooks-replace-render-props-and-higher-order-components)
+  * [What do Hooks mean for popular APIs like Redux connect() and React Router?](#what-do-hooks-mean-for-popular-apis-like-redux-connect-and-react-router)
+  * [Do Hooks work with static typing?](#do-hooks-work-with-static-typing)
+  * [How to test components that use Hooks?](#how-to-test-components-that-use-hooks)
+  * [What exactly do the lint rules enforce?](#what-exactly-do-the-lint-rules-enforce)
+* **[From Classes to Hooks](#from-classes-to-hooks)**
+  * [How do lifecycle methods correspond to Hooks?](#how-do-lifecycle-methods-correspond-to-hooks)
+  * [How can I do data fetching with Hooks?](#how-can-i-do-data-fetching-with-hooks)
+  * [Is there something like instance variables?](#is-there-something-like-instance-variables)
+  * [Should I use one or many state variables?](#should-i-use-one-or-many-state-variables)
+  * [Can I run an effect only on updates?](#can-i-run-an-effect-only-on-updates)
+  * [How to get the previous props or state?](#how-to-get-the-previous-props-or-state)
+  * [Why am I seeing stale props or state inside my function?](#why-am-i-seeing-stale-props-or-state-inside-my-function)
+  * [How do I implement getDerivedStateFromProps?](#how-do-i-implement-getderivedstatefromprops)
+  * [Is there something like forceUpdate?](#is-there-something-like-forceupdate)
+  * [Can I make a ref to a function component?](#can-i-make-a-ref-to-a-function-component)
+  * [How can I measure a DOM node?](#how-can-i-measure-a-dom-node)
+  * [What does const [thing, setThing] = useState() mean?](#what-does-const-thing-setthing--usestate-mean)
+* **[Performance Optimizations](#performance-optimizations)**
+  * [Can I skip an effect on updates?](#can-i-skip-an-effect-on-updates)
+  * [Is it safe to omit functions from the list of dependencies?](#is-it-safe-to-omit-functions-from-the-list-of-dependencies)
+  * [What can I do if my effect dependencies change too often?](#what-can-i-do-if-my-effect-dependencies-change-too-often)
+  * [How do I implement shouldComponentUpdate?](#how-do-i-implement-shouldcomponentupdate)
+  * [How to memoize calculations?](#how-to-memoize-calculations)
+  * [How to create expensive objects lazily?](#how-to-create-expensive-objects-lazily)
+  * [Are Hooks slow because of creating functions in render?](#are-hooks-slow-because-of-creating-functions-in-render)
+  * [How to avoid passing callbacks down?](#how-to-avoid-passing-callbacks-down)
+  * [How to read an often-changing value from useCallback?](#how-to-read-an-often-changing-value-from-usecallback)
+* **[Under the Hood](#under-the-hood)**
+  * [How does React associate Hook calls with components?](#how-does-react-associate-hook-calls-with-components)
+  * [What is the prior art for Hooks?](#what-is-the-prior-art-for-hooks)
+
+## Adoption Strategy {#adoption-strategy}
+
+### Which versions of React include Hooks? {#which-versions-of-react-include-hooks}
+
+Starting with 16.8.0, React includes a stable implementation of React Hooks for:
+
+* React DOM
+* React Native
+* React DOM Server
+* React Test Renderer
+* React Shallow Renderer
+
+Note that **to enable Hooks, all React packages need to be 16.8.0 or higher**. Hooks won't work if you forget to update, for example, React DOM.
+
+[React Native 0.59](https://facebook.github.io/react-native/blog/2019/03/12/releasing-react-native-059) and above support Hooks.
+
+### Do I need to rewrite all my class components? {#do-i-need-to-rewrite-all-my-class-components}
+
+No. There are [no plans](/docs/hooks-intro.html#gradual-adoption-strategy) to remove classes from React -- we all need to keep shipping products and can't afford rewrites. We recommend trying Hooks in new code.
+
+### What can I do with Hooks that I couldn't with classes? {#what-can-i-do-with-hooks-that-i-couldnt-with-classes}
+
+Hooks offer a powerful and expressive new way to reuse functionality between components. ["Building Your Own Hooks"](/docs/hooks-custom.html) provides a glimpse of what's possible. [This article](https://medium.com/@dan_abramov/making-sense-of-react-hooks-fdbde8803889) by a React core team member dives deeper into the new capabilities unlocked by Hooks.
+
+### How much of my React knowledge stays relevant? {#how-much-of-my-react-knowledge-stays-relevant}
+
+Hooks are a more direct way to use the React features you already know -- such as state, lifecycle, context, and refs. They don't fundamentally change how React works, and your knowledge of components, props, and top-down data flow is just as relevant.
+
+Hooks do have a learning curve of their own. If there's something missing in this documentation, [raise an issue](https://github.com/reactjs/reactjs.org/issues/new) and we'll try to help.
+
+### Should I use Hooks, classes, or a mix of both? {#should-i-use-hooks-classes-or-a-mix-of-both}
+
+When you're ready, we'd encourage you to start trying Hooks in new components you write. Make sure everyone on your team is on board with using them and familiar with this documentation. We don't recommend rewriting your existing classes to Hooks unless you planned to rewrite them anyway (e.g. to fix bugs).
+
+You can't use Hooks *inside* of a class component, but you can definitely mix classes and function components with Hooks in a single tree. Whether a component is a class or a function that uses Hooks is an implementation detail of that component. In the longer term, we expect Hooks to be the primary way people write React components.
+
+### Do Hooks cover all use cases for classes? {#do-hooks-cover-all-use-cases-for-classes}
+
+Our goal is for Hooks to cover all use cases for classes as soon as possible. There are no Hook equivalents to the uncommon `getSnapshotBeforeUpdate` and `componentDidCatch` lifecycles yet, but we plan to add them soon.
+
+It is an early time for Hooks, and some third-party libraries might not be compatible with Hooks at the moment.
+
+### Do Hooks replace render props and higher-order components? {#do-hooks-replace-render-props-and-higher-order-components}
+
+Often, render props and higher-order components render only a single child. We think Hooks are a simpler way to serve this use case. There is still a place for both patterns (for example, a virtual scroller component might have a `renderItem` prop, or a visual container component might have its own DOM structure). But in most cases, Hooks will be sufficient and can help reduce nesting in your tree.
+
+### What do Hooks mean for popular APIs like Redux `connect()` and React Router? {#what-do-hooks-mean-for-popular-apis-like-redux-connect-and-react-router}
+
+You can continue to use the exact same APIs as you always have; they'll continue to work.
+
+React Redux since v7.1.0 [supports Hooks API](https://react-redux.js.org/api/hooks) and exposes hooks like `useDispatch` or `useSelector`.
+
+React Router [supports hooks](https://reacttraining.com/react-router/web/api/Hooks) since v5.1.
+
+Other libraries might support hooks in the future too.
+
+### Do Hooks work with static typing? {#do-hooks-work-with-static-typing}
+
+Hooks were designed with static typing in mind. Because they're functions, they are easier to type correctly than patterns like higher-order components. The latest Flow and TypeScript React definitions include support for React Hooks.
+
+Importantly, custom Hooks give you the power to constrain React API if you'd like to type them more strictly in some way. React gives you the primitives, but you can combine them in different ways than what we provide out of the box.
+
+### How to test components that use Hooks? {#how-to-test-components-that-use-hooks}
+
+From React's point of view, a component using Hooks is just a regular component. If your testing solution doesn't rely on React internals, testing components with Hooks shouldn't be different from how you normally test components.
+
+>Note
+>
+>[Testing Recipes](/docs/testing-recipes.html) include many examples that you can copy and paste.
+
+For example, let's say we have this counter component:
+
+```js
+function Example() {
+  const [count, setCount] = useState(0);
+  useEffect(() => {
+    document.title = `You clicked ${count} times`;
+  });
+  return (
+    <div>
+      <p>You clicked {count} times</p>
+      <button onClick={() => setCount(count + 1)}>
+        Click me
+      </button>
+    </div>
+  );
+}
+```
+
+We'll test it using React DOM. To make sure that the behavior matches what happens in the browser, we'll wrap the code rendering and updating it into [`ReactTestUtils.act()`](/docs/test-utils.html#act) calls:
+
+```js{3,20-22,29-31}
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { act } from 'react-dom/test-utils';
+import Counter from './Counter';
+
+let container;
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  document.body.removeChild(container);
+  container = null;
+});
+
+it('can render and update a counter', () => {
+  // Test first render and effect
+  act(() => {
+    ReactDOM.render(<Counter />, container);
+  });
+  const button = container.querySelector('button');
+  const label = container.querySelector('p');
+  expect(label.textContent).toBe('You clicked 0 times');
+  expect(document.title).toBe('You clicked 0 times');
+
+  // Test second render and effect
+  act(() => {
+    button.dispatchEvent(new MouseEvent('click', {bubbles: true}));
+  });
+  expect(label.textContent).toBe('You clicked 1 times');
+  expect(document.title).toBe('You clicked 1 times');
+});
+```
+
+The calls to `act()` will also flush the effects inside of them.
+
+If you need to test a custom Hook, you can do so by creating a component in your test, and using your Hook from it. Then you can test the component you wrote.
+
+To reduce the boilerplate, we recommend using [React Testing Library](https://testing-library.com/react) which is designed to encourage writing tests that use your components as the end users do.
+
+For more information, check out [Testing Recipes](/docs/testing-recipes.html).
+
+### What exactly do the [lint rules](https://www.npmjs.com/package/eslint-plugin-react-hooks) enforce? {#what-exactly-do-the-lint-rules-enforce}
+
+We provide an [ESLint plugin](https://www.npmjs.com/package/eslint-plugin-react-hooks) that enforces [rules of Hooks](/docs/hooks-rules.html) to avoid bugs. It assumes that any function starting with "`use`" and a capital letter right after it is a Hook. We recognize this heuristic isn't perfect and there may be some false positives, but without an ecosystem-wide convention there is just no way to make Hooks work well -- and longer names will discourage people from either adopting Hooks or following the convention.
+
+In particular, the rule enforces that:
+
+* Calls to Hooks are either inside a `PascalCase` function (assumed to be a component) or another `useSomething` function (assumed to be a custom Hook).
+* Hooks are called in the same order on every render.
+
+There are a few more heuristics, and they might change over time as we fine-tune the rule to balance finding bugs with avoiding false positives.
+
+## From Classes to Hooks {#from-classes-to-hooks}
+
+### How do lifecycle methods correspond to Hooks? {#how-do-lifecycle-methods-correspond-to-hooks}
+
+* `constructor`: Function components don't need a constructor. You can initialize the state in the [`useState`](/docs/hooks-reference.html#usestate) call. If computing the initial state is expensive, you can pass a function to `useState`.
+
+* `getDerivedStateFromProps`: Schedule an update [while rendering](#how-do-i-implement-getderivedstatefromprops) instead.
+
+* `shouldComponentUpdate`: See `React.memo` [below](#how-do-i-implement-shouldcomponentupdate).
+
+* `render`: This is the function component body itself.
+
+* `componentDidMount`, `componentDidUpdate`, `componentWillUnmount`: The [`useEffect` Hook](/docs/hooks-reference.html#useeffect) can express all combinations of these (including [less](#can-i-skip-an-effect-on-updates) [common](#can-i-run-an-effect-only-on-updates) cases).
+
+* `componentDidCatch` and `getDerivedStateFromError`: There are no Hook equivalents for these methods yet, but they will be added soon.
+
+### How can I do data fetching with Hooks? {#how-can-i-do-data-fetching-with-hooks}
+
+Here is a [small demo](https://codesandbox.io/s/jvvkoo8pq3) to get you started. To learn more, check out [this article](https://www.robinwieruch.de/react-hooks-fetch-data/) about data fetching with Hooks.
+
+### Is there something like instance variables? {#is-there-something-like-instance-variables}
+
+Yes! The [`useRef()`](/docs/hooks-reference.html#useref) Hook isn't just for DOM refs. The "ref" object is a generic container whose `current` property is mutable and can hold any value, similar to an instance property on a class.
+
+You can write to it from inside `useEffect`:
+
+```js{2,8}
+function Timer() {
+  const intervalRef = useRef();
+
+  useEffect(() => {
+    const id = setInterval(() => {
+      // ...
+    });
+    intervalRef.current = id;
+    return () => {
+      clearInterval(intervalRef.current);
+    };
+  });
+
+  // ...
+}
+```
+
+If we just wanted to set an interval, we wouldn't need the ref (`id` could be local to the effect), but it's useful if we want to clear the interval from an event handler:
+
+```js{3}
+  // ...
+  function handleCancelClick() {
+    clearInterval(intervalRef.current);
+  }
+  // ...
+```
+
+Conceptually, you can think of refs as similar to instance variables in a class. Unless you're doing [lazy initialization](#how-to-create-expensive-objects-lazily), avoid setting refs during rendering -- this can lead to surprising behavior. Instead, typically you want to modify refs in event handlers and effects.
+
+### Should I use one or many state variables? {#should-i-use-one-or-many-state-variables}
+
+If you're coming from classes, you might be tempted to always call `useState()` once and put all state into a single object. You can do it if you'd like. Here is an example of a component that follows the mouse movement. We keep its position and size in the local state:
+
+```js
+function Box() {
+  const [state, setState] = useState({ left: 0, top: 0, width: 100, height: 100 });
+  // ...
+}
+```
+
+Now let's say we want to write some logic that changes `left` and `top` when the user moves their mouse. Note how we have to merge these fields into the previous state object manually:
+
+```js{4,5}
+  // ...
+  useEffect(() => {
+    function handleWindowMouseMove(e) {
+      // Spreading "...state" ensures we don't "lose" width and height
+      setState(state => ({ ...state, left: e.pageX, top: e.pageY }));
+    }
+    // Note: this implementation is a bit simplified
+    window.addEventListener('mousemove', handleWindowMouseMove);
+    return () => window.removeEventListener('mousemove', handleWindowMouseMove);
+  }, []);
+  // ...
+```
+
+This is because when we update a state variable, we *replace* its value. This is different from `this.setState` in a class, which *merges* the updated fields into the object.
+
+If you miss automatic merging, you can write a custom `useLegacyState` Hook that merges object state updates. However, instead **we recommend to split state into multiple state variables based on which values tend to change together.**
+
+For example, we could split our component state into `position` and `size` objects, and always replace the `position` with no need for merging:
+
+```js{2,7}
+function Box() {
+  const [position, setPosition] = useState({ left: 0, top: 0 });
+  const [size, setSize] = useState({ width: 100, height: 100 });
+
+  useEffect(() => {
+    function handleWindowMouseMove(e) {
+      setPosition({ left: e.pageX, top: e.pageY });
+    }
+    // ...
+```
+
+Separating independent state variables also has another benefit. It makes it easy to later extract some related logic into a custom Hook, for example:
+
+```js{2,7}
+function Box() {
+  const position = useWindowPosition();
+  const [size, setSize] = useState({ width: 100, height: 100 });
+  // ...
+}
+
+function useWindowPosition() {
+  const [position, setPosition] = useState({ left: 0, top: 0 });
+  useEffect(() => {
+    // ...
+  }, []);
+  return position;
+}
+```
+
+Note how we were able to move the `useState` call for the `position` state variable and the related effect into a custom Hook without changing their code. If all state was in a single object, extracting it would be more difficult.
+
+Both putting all state in a single `useState` call, and having a `useState` call per each field can work. Components tend to be most readable when you find a balance between these two extremes, and group related state into a few independent state variables. If the state logic becomes complex, we recommend [managing it with a reducer](/docs/hooks-reference.html#usereducer) or a custom Hook.
+
+### Can I run an effect only on updates? {#can-i-run-an-effect-only-on-updates}
+
+This is a rare use case. If you need it, you can [use a mutable ref](#is-there-something-like-instance-variables) to manually store a boolean value corresponding to whether you are on the first or a subsequent render, then check that flag in your effect. (If you find yourself doing this often, you could create a custom Hook for it.)
+
+### How to get the previous props or state? {#how-to-get-the-previous-props-or-state}
+
+Currently, you can do it manually [with a ref](#is-there-something-like-instance-variables):
+
+```js{6,8}
+function Counter() {
+  const [count, setCount] = useState(0);
+
+  const prevCountRef = useRef();
+  useEffect(() => {
+    prevCountRef.current = count;
+  });
+  const prevCount = prevCountRef.current;
+
+  return <h1>Now: {count}, before: {prevCount}</h1>;
+}
+```
+
+This might be a bit convoluted but you can extract it into a custom Hook:
+
+```js{3,7}
+function Counter() {
+  const [count, setCount] = useState(0);
+  const prevCount = usePrevious(count);
+  return <h1>Now: {count}, before: {prevCount}</h1>;
+}
+
+function usePrevious(value) {
+  const ref = useRef();
+  useEffect(() => {
+    ref.current = value;
+  });
+  return ref.current;
+}
+```
+
+Note how this would work for props, state, or any other calculated value.
+
+```js{5}
+function Counter() {
+  const [count, setCount] = useState(0);
+
+  const calculation = count + 100;
+  const prevCalculation = usePrevious(calculation);
+  // ...
+```
+
+It's possible that in the future React will provide a `usePrevious` Hook out of the box since it's a relatively common use case.
+
+See also [the recommended pattern for derived state](#how-do-i-implement-getderivedstatefromprops).
+
+### Why am I seeing stale props or state inside my function? {#why-am-i-seeing-stale-props-or-state-inside-my-function}
+
+Any function inside a component, including event handlers and effects, "sees" the props and state from the render it was created in. For example, consider code like this:
+
+```js
+function Example() {
+  const [count, setCount] = useState(0);
+
+  function handleAlertClick() {
+    setTimeout(() => {
+      alert('You clicked on: ' + count);
+    }, 3000);
+  }
+
+  return (
+    <div>
+      <p>You clicked {count} times</p>
+      <button onClick={() => setCount(count + 1)}>
+        Click me
+      </button>
+      <button onClick={handleAlertClick}>
+        Show alert
+      </button>
+    </div>
+  );
+}
+```
+
+If you first click "Show alert" and then increment the counter, the alert will show the `count` variable **at the time you clicked the "Show alert" button**. This prevents bugs caused by the code assuming props and state don't change.
+
+If you intentionally want to read the *latest* state from some asynchronous callback, you could keep it in [a ref](/docs/hooks-faq.html#is-there-something-like-instance-variables), mutate it, and read from it.
+
+Finally, another possible reason you're seeing stale props or state is if you use the "dependency array" optimization but didn't correctly specify all the dependencies. For example, if an effect specifies `[]` as the second argument but reads `someProp` inside, it will keep "seeing" the initial value of `someProp`. The solution is to either remove the dependency array, or to fix it. Here's [how you can deal with functions](#is-it-safe-to-omit-functions-from-the-list-of-dependencies), and here's [other common strategies](#what-can-i-do-if-my-effect-dependencies-change-too-often) to run effects less often without incorrectly skipping dependencies.
+
+>Note
+>
+>We provide an [`exhaustive-deps`](https://github.com/facebook/react/issues/14920) ESLint rule as a part of the [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks#installation) package. It warns when dependencies are specified incorrectly and suggests a fix.
+
+### How do I implement `getDerivedStateFromProps`? {#how-do-i-implement-getderivedstatefromprops}
+
+While you probably [don't need it](/blog/2018/06/07/you-probably-dont-need-derived-state.html), in rare cases that you do (such as implementing a `<Transition>` component), you can update the state right during rendering. React will re-run the component with updated state immediately after exiting the first render so it wouldn't be expensive.
+
+Here, we store the previous value of the `row` prop in a state variable so that we can compare:
+
+```js
+function ScrollView({row}) {
+  let [isScrollingDown, setIsScrollingDown] = useState(false);
+  let [prevRow, setPrevRow] = useState(null);
+
+  if (row !== prevRow) {
+    // Row changed since last render. Update isScrollingDown.
+    setIsScrollingDown(prevRow !== null && row > prevRow);
+    setPrevRow(row);
+  }
+
+  return `Scrolling down: ${isScrollingDown}`;
+}
+```
+
+This might look strange at first, but an update during rendering is exactly what `getDerivedStateFromProps` has always been like conceptually.
+
+### Is there something like forceUpdate? {#is-there-something-like-forceupdate}
+
+Both `useState` and `useReducer` Hooks [bail out of updates](/docs/hooks-reference.html#bailing-out-of-a-state-update) if the next value is the same as the previous one. Mutating state in place and calling `setState` will not cause a re-render.
+
+Normally, you shouldn't mutate local state in React. However, as an escape hatch, you can use an incrementing counter to force a re-render even if the state has not changed:
+
+```js
+  const [ignored, forceUpdate] = useReducer(x => x + 1, 0);
+
+  function handleClick() {
+    forceUpdate();
+  }
+```
+
+Try to avoid this pattern if possible.
+
+### Can I make a ref to a function component? {#can-i-make-a-ref-to-a-function-component}
+
+While you shouldn't need this often, you may expose some imperative methods to a parent component with the [`useImperativeHandle`](/docs/hooks-reference.html#useimperativehandle) Hook.
+
+### How can I measure a DOM node? {#how-can-i-measure-a-dom-node}
+
+In order to measure the position or size of a DOM node, you can use a [callback ref](/docs/refs-and-the-dom.html#callback-refs). React will call that callback whenever the ref gets attached to a different node. Here is a [small demo](https://codesandbox.io/s/l7m0v5x4v9):
+
+```js{4-8,12}
+function MeasureExample() {
+  const [height, setHeight] = useState(0);
+
+  const measuredRef = useCallback(node => {
+    if (node !== null) {
+      setHeight(node.getBoundingClientRect().height);
+    }
+  }, []);
+
+  return (
+    <>
+      <h1 ref={measuredRef}>Hello, world</h1>
+      <h2>The above header is {Math.round(height)}px tall</h2>
+    </>
+  );
+}
+```
+
+We didn't choose `useRef` in this example because an object ref doesn't notify us about *changes* to the current ref value. Using a callback ref ensures that [even if a child component displays the measured node later](https://codesandbox.io/s/818zzk8m78) (e.g. in response to a click), we still get notified about it in the parent component and can update the measurements.
+
+Note that we pass `[]` as a dependency array to `useCallback`. This ensures that our ref callback doesn't change between the re-renders, and so React won't call it unnecessarily.
+
+If you want, you can [extract this logic](https://codesandbox.io/s/m5o42082xy) into a reusable Hook:
+
+```js{2}
+function MeasureExample() {
+  const [rect, ref] = useClientRect();
+  return (
+    <>
+      <h1 ref={ref}>Hello, world</h1>
+      {rect !== null &&
+        <h2>The above header is {Math.round(rect.height)}px tall</h2>
+      }
+    </>
+  );
+}
+
+function useClientRect() {
+  const [rect, setRect] = useState(null);
+  const ref = useCallback(node => {
+    if (node !== null) {
+      setRect(node.getBoundingClientRect());
+    }
+  }, []);
+  return [rect, ref];
+}
+```
+
+
+### What does `const [thing, setThing] = useState()` mean? {#what-does-const-thing-setthing--usestate-mean}
+
+If you're not familiar with this syntax, check out the [explanation](/docs/hooks-state.html#tip-what-do-square-brackets-mean) in the State Hook documentation.
+
+
+## Performance Optimizations {#performance-optimizations}
+
+### Can I skip an effect on updates? {#can-i-skip-an-effect-on-updates}
+
+Yes. See [conditionally firing an effect](/docs/hooks-reference.html#conditionally-firing-an-effect). Note that forgetting to handle updates often [introduces bugs](/docs/hooks-effect.html#explanation-why-effects-run-on-each-update), which is why this isn't the default behavior.
+
+### Is it safe to omit functions from the list of dependencies? {#is-it-safe-to-omit-functions-from-the-list-of-dependencies}
+
+Generally speaking, no.
+
+```js{3,8}
+function Example({ someProp }) {
+  function doSomething() {
+    console.log(someProp);
+  }
+
+  useEffect(() => {
+    doSomething();
+  }, []); // 🔴 This is not safe (it calls `doSomething` which uses `someProp`)
+}
+```
+
+It's difficult to remember which props or state are used by functions outside of the effect. This is why **usually you'll want to declare functions needed by an effect *inside* of it.** Then it's easy to see what values from the component scope that effect depends on:
+
+```js{4,8}
+function Example({ someProp }) {
+  useEffect(() => {
+    function doSomething() {
+      console.log(someProp);
+    }
+
+    doSomething();
+  }, [someProp]); // ✅ OK (our effect only uses `someProp`)
+}
+```
+
+If after that we still don't use any values from the component scope, it's safe to specify `[]`:
+
+```js{7}
+useEffect(() => {
+  function doSomething() {
+    console.log('hello');
+  }
+
+  doSomething();
+}, []); // ✅ OK in this example because we don't use *any* values from component scope
+```
+
+Depending on your use case, there are a few more options described below.
+
+>Note
+>
+>We provide the [`exhaustive-deps`](https://github.com/facebook/react/issues/14920) ESLint rule as a part of the [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks#installation) package. It helps you find components that don't handle updates consistently.
+
+Let's see why this matters.
+
+If you specify a [list of dependencies](/docs/hooks-reference.html#conditionally-firing-an-effect) as the last argument to `useEffect`, `useMemo`, `useCallback`, or `useImperativeHandle`, it must include all values used inside that participate in the React data flow. That includes props, state, and anything derived from them.
+
+It is **only** safe to omit a function from the dependency list if nothing in it (or the functions called by it) references props, state, or values derived from them. This example has a bug:
+
+```js{5,12}
+function ProductPage({ productId }) {
+  const [product, setProduct] = useState(null);
+
+  async function fetchProduct() {
+    const response = await fetch('http://myapi/product' + productId); // Uses productId prop
+    const json = await response.json();
+    setProduct(json);
+  }
+
+  useEffect(() => {
+    fetchProduct();
+  }, []); // 🔴 Invalid because `fetchProduct` uses `productId`
+  // ...
+}
+```
+
+**The recommended fix is to move that function _inside_ of your effect**. That makes it easy to see which props or state your effect uses, and to ensure they're all declared:
+
+```js{5-10,13}
+function ProductPage({ productId }) {
+  const [product, setProduct] = useState(null);
+
+  useEffect(() => {
+    // By moving this function inside the effect, we can clearly see the values it uses.
+    async function fetchProduct() {
+      const response = await fetch('http://myapi/product' + productId);
+      const json = await response.json();
+      setProduct(json);
+    }
+
+    fetchProduct();
+  }, [productId]); // ✅ Valid because our effect only uses productId
+  // ...
+}
+```
+
+This also allows you to handle out-of-order responses with a local variable inside the effect:
+
+```js{2,6,10}
+  useEffect(() => {
+    let ignore = false;
+    async function fetchProduct() {
+      const response = await fetch('http://myapi/product/' + productId);
+      const json = await response.json();
+      if (!ignore) setProduct(json);
+    }
+
+    fetchProduct();
+    return () => { ignore = true };
+  }, [productId]);
+```
+
+We moved the function inside the effect so it doesn't need to be in its dependency list.
+
+>Tip
+>
+>Check out [this small demo](https://codesandbox.io/s/jvvkoo8pq3) and [this article](https://www.robinwieruch.de/react-hooks-fetch-data/) to learn more about data fetching with Hooks.
+
+**If for some reason you _can't_ move a function inside an effect, there are a few more options:**
+
+* **You can try moving that function outside of your component**. In that case, the function is guaranteed to not reference any props or state, and also doesn't need to be in the list of dependencies.
+* If the function you're calling is a pure computation and is safe to call while rendering, you may **call it outside of the effect instead,** and make the effect depend on the returned value.
+* As a last resort, you can **add a function to effect dependencies but _wrap its definition_** into the [`useCallback`](/docs/hooks-reference.html#usecallback) Hook. This ensures it doesn't change on every render unless *its own* dependencies also change:
+
+```js{2-5}
+function ProductPage({ productId }) {
+  // ✅ Wrap with useCallback to avoid change on every render
+  const fetchProduct = useCallback(() => {
+    // ... Does something with productId ...
+  }, [productId]); // ✅ All useCallback dependencies are specified
+
+  return <ProductDetails fetchProduct={fetchProduct} />;
+}
+
+function ProductDetails({ fetchProduct }) {
+  useEffect(() => {
+    fetchProduct();
+  }, [fetchProduct]); // ✅ All useEffect dependencies are specified
+  // ...
+}
+```
+
+Note that in the above example we **need** to keep the function in the dependencies list. This ensures that a change in the `productId` prop of `ProductPage` automatically triggers a refetch in the `ProductDetails` component.
+
+### What can I do if my effect dependencies change too often? {#what-can-i-do-if-my-effect-dependencies-change-too-often}
+
+Sometimes, your effect may be using state that changes too often. You might be tempted to omit that state from a list of dependencies, but that usually leads to bugs:
+
+```js{6,9}
+function Counter() {
+  const [count, setCount] = useState(0);
+
+  useEffect(() => {
+    const id = setInterval(() => {
+      setCount(count + 1); // This effect depends on the `count` state
+    }, 1000);
+    return () => clearInterval(id);
+  }, []); // 🔴 Bug: `count` is not specified as a dependency
+
+  return <h1>{count}</h1>;
+}
+```
+
+The empty set of dependencies, `[]`, means that the effect will only run once when the component mounts, and not on every re-render. The problem is that inside the `setInterval` callback, the value of `count` does not change, because we've created a closure with the value of `count` set to `0` as it was when the effect callback ran. Every second, this callback then calls `setCount(0 + 1)`, so the count never goes above 1.
+
+Specifying `[count]` as a list of dependencies would fix the bug, but would cause the interval to be reset on every change. Effectively, each `setInterval` would get one chance to execute before being cleared (similar to a `setTimeout`.) That may not be desirable. To fix this, we can use the [functional update form of `setState`](/docs/hooks-reference.html#functional-updates). It lets us specify *how* the state needs to change without referencing the *current* state:
+
+```js{6,9}
+function Counter() {
+  const [count, setCount] = useState(0);
+
+  useEffect(() => {
+    const id = setInterval(() => {
+      setCount(c => c + 1); // ✅ This doesn't depend on `count` variable outside
+    }, 1000);
+    return () => clearInterval(id);
+  }, []); // ✅ Our effect doesn't use any variables in the component scope
+
+  return <h1>{count}</h1>;
+}
+```
+
+(The identity of the `setCount` function is guaranteed to be stable so it's safe to omit.)
+
+Now, the `setInterval` callback executes once a second, but each time the inner call to `setCount` can use an up-to-date value for `count` (called `c` in the callback here.)
+
+In more complex cases (such as if one state depends on another state), try moving the state update logic outside the effect with the [`useReducer` Hook](/docs/hooks-reference.html#usereducer). [This article](https://adamrackis.dev/state-and-use-reducer/) offers an example of how you can do this. **The identity of the `dispatch` function from `useReducer` is always stable** — even if the reducer function is declared inside the component and reads its props.
+
+As a last resort, if you want something like `this` in a class, you can [use a ref](/docs/hooks-faq.html#is-there-something-like-instance-variables) to hold a mutable variable. Then you can write and read to it. For example:
+
+```js{2-6,10-11,16}
+function Example(props) {
+  // Keep latest props in a ref.
+  let latestProps = useRef(props);
+  useEffect(() => {
+    latestProps.current = props;
+  });
+
+  useEffect(() => {
+    function tick() {
+      // Read latest props at any time
+      console.log(latestProps.current);
+    }
+
+    const id = setInterval(tick, 1000);
+    return () => clearInterval(id);
+  }, []); // This effect never re-runs
+}
+```
+
+Only do this if you couldn't find a better alternative, as relying on mutation makes components less predictable. If there's a specific pattern that doesn't translate well, [file an issue](https://github.com/facebook/react/issues/new) with a runnable example code and we can try to help.
+
+### How do I implement `shouldComponentUpdate`? {#how-do-i-implement-shouldcomponentupdate}
+
+You can wrap a function component with `React.memo` to shallowly compare its props:
+
+```js
+const Button = React.memo((props) => {
+  // your component
+});
+```
+
+It's not a Hook because it doesn't compose like Hooks do. `React.memo` is equivalent to `PureComponent`, but it only compares props. (You can also add a second argument to specify a custom comparison function that takes the old and new props. If it returns true, the update is skipped.)
+
+`React.memo` doesn't compare state because there is no single state object to compare. But you can make children pure too, or even [optimize individual children with `useMemo`](/docs/hooks-faq.html#how-to-memoize-calculations).
+
+### How to memoize calculations? {#how-to-memoize-calculations}
+
+The [`useMemo`](/docs/hooks-reference.html#usememo) Hook lets you cache calculations between multiple renders by "remembering" the previous computation:
+
+```js
+const memoizedValue = useMemo(() => computeExpensiveValue(a, b), [a, b]);
+```
+
+This code calls `computeExpensiveValue(a, b)`. But if the dependencies `[a, b]` haven't changed since the last value, `useMemo` skips calling it a second time and simply reuses the last value it returned.
+
+Remember that the function passed to `useMemo` runs during rendering. Don't do anything there that you wouldn't normally do while rendering. For example, side effects belong in `useEffect`, not `useMemo`.
+
+**You may rely on `useMemo` as a performance optimization, not as a semantic guarantee.** In the future, React may choose to "forget" some previously memoized values and recalculate them on next render, e.g. to free memory for offscreen components. Write your code so that it still works without `useMemo` — and then add it to optimize performance. (For rare cases when a value must *never* be recomputed, you can [lazily initialize](#how-to-create-expensive-objects-lazily) a ref.)
+
+Conveniently, `useMemo` also lets you skip an expensive re-render of a child:
+
+```js
+function Parent({ a, b }) {
+  // Only re-rendered if `a` changes:
+  const child1 = useMemo(() => <Child1 a={a} />, [a]);
+  // Only re-rendered if `b` changes:
+  const child2 = useMemo(() => <Child2 b={b} />, [b]);
+  return (
+    <>
+      {child1}
+      {child2}
+    </>
+  )
+}
+```
+
+Note that this approach won't work in a loop because Hook calls [can't](/docs/hooks-rules.html) be placed inside loops. But you can extract a separate component for the list item, and call `useMemo` there.
+
+### How to create expensive objects lazily? {#how-to-create-expensive-objects-lazily}
+
+`useMemo` lets you [memoize an expensive calculation](#how-to-memoize-calculations) if the dependencies are the same. However, it only serves as a hint, and doesn't *guarantee* the computation won't re-run. But sometimes you need to be sure an object is only created once.
+
+**The first common use case is when creating the initial state is expensive:**
+
+```js
+function Table(props) {
+  // ⚠️ createRows() is called on every render
+  const [rows, setRows] = useState(createRows(props.count));
+  // ...
+}
+```
+
+To avoid re-creating the ignored initial state, we can pass a **function** to `useState`:
+
+```js
+function Table(props) {
+  // ✅ createRows() is only called once
+  const [rows, setRows] = useState(() => createRows(props.count));
+  // ...
+}
+```
+
+React will only call this function during the first render. See the [`useState` API reference](/docs/hooks-reference.html#usestate).
+
+**You might also occasionally want to avoid re-creating the `useRef()` initial value.** For example, maybe you want to ensure some imperative class instance only gets created once:
+
+```js
+function Image(props) {
+  // ⚠️ IntersectionObserver is created on every render
+  const ref = useRef(new IntersectionObserver(onIntersect));
+  // ...
+}
+```
+
+`useRef` **does not** accept a special function overload like `useState`. Instead, you can write your own function that creates and sets it lazily:
+
+```js
+function Image(props) {
+  const ref = useRef(null);
+
+  // ✅ IntersectionObserver is created lazily once
+  function getObserver() {
+    if (ref.current === null) {
+      ref.current = new IntersectionObserver(onIntersect);
+    }
+    return ref.current;
+  }
+
+  // When you need it, call getObserver()
+  // ...
+}
+```
+
+This avoids creating an expensive object until it's truly needed for the first time. If you use Flow or TypeScript, you can also give `getObserver()` a non-nullable type for convenience.
+
+
+### Are Hooks slow because of creating functions in render? {#are-hooks-slow-because-of-creating-functions-in-render}
+
+No. In modern browsers, the raw performance of closures compared to classes doesn't differ significantly except in extreme scenarios.
+
+In addition, consider that the design of Hooks is more efficient in a couple ways:
+
+* Hooks avoid a lot of the overhead that classes require, like the cost of creating class instances and binding event handlers in the constructor.
+
+* **Idiomatic code using Hooks doesn't need the deep component tree nesting** that is prevalent in codebases that use higher-order components, render props, and context. With smaller component trees, React has less work to do.
+
+Traditionally, performance concerns around inline functions in React have been related to how passing new callbacks on each render breaks `shouldComponentUpdate` optimizations in child components. Hooks approach this problem from three sides.
+
+* The [`useCallback`](/docs/hooks-reference.html#usecallback) Hook lets you keep the same callback reference between re-renders so that `shouldComponentUpdate` continues to work:
+
+    ```js{2}
+    // Will not change unless `a` or `b` changes
+    const memoizedCallback = useCallback(() => {
+      doSomething(a, b);
+    }, [a, b]);
+    ```
+
+* The [`useMemo`](/docs/hooks-faq.html#how-to-memoize-calculations) Hook makes it easier to control when individual children update, reducing the need for pure components.
+
+* Finally, the [`useReducer`](/docs/hooks-reference.html#usereducer) Hook reduces the need to pass callbacks deeply, as explained below.
+
+### How to avoid passing callbacks down? {#how-to-avoid-passing-callbacks-down}
+
+We've found that most people don't enjoy manually passing callbacks through every level of a component tree. Even though it is more explicit, it can feel like a lot of "plumbing".
+
+In large component trees, an alternative we recommend is to pass down a `dispatch` function from [`useReducer`](/docs/hooks-reference.html#usereducer) via context:
+
+```js{4,5}
+const TodosDispatch = React.createContext(null);
+
+function TodosApp() {
+  // Note: `dispatch` won't change between re-renders
+  const [todos, dispatch] = useReducer(todosReducer);
+
+  return (
+    <TodosDispatch.Provider value={dispatch}>
+      <DeepTree todos={todos} />
+    </TodosDispatch.Provider>
+  );
+}
+```
+
+Any child in the tree inside `TodosApp` can use the `dispatch` function to pass actions up to `TodosApp`:
+
+```js{2,3}
+function DeepChild(props) {
+  // If we want to perform an action, we can get dispatch from context.
+  const dispatch = useContext(TodosDispatch);
+
+  function handleClick() {
+    dispatch({ type: 'add', text: 'hello' });
+  }
+
+  return (
+    <button onClick={handleClick}>Add todo</button>
+  );
+}
+```
+
+This is both more convenient from the maintenance perspective (no need to keep forwarding callbacks), and avoids the callback problem altogether. Passing `dispatch` down like this is the recommended pattern for deep updates.
+
+Note that you can still choose whether to pass the application *state* down as props (more explicit) or as context (more convenient for very deep updates). If you use context to pass down the state too, use two different context types -- the `dispatch` context never changes, so components that read it don't need to rerender unless they also need the application state.
+
+### How to read an often-changing value from `useCallback`? {#how-to-read-an-often-changing-value-from-usecallback}
+
+>Note
+>
+>We recommend to [pass `dispatch` down in context](#how-to-avoid-passing-callbacks-down) rather than individual callbacks in props. The approach below is only mentioned here for completeness and as an escape hatch.
+>
+>Also note that this pattern might cause problems in the [concurrent mode](/blog/2018/03/27/update-on-async-rendering.html). We plan to provide more ergonomic alternatives in the future, but the safest solution right now is to always invalidate the callback if some value it depends on changes.
+
+In some rare cases you might need to memoize a callback with [`useCallback`](/docs/hooks-reference.html#usecallback) but the memoization doesn't work very well because the inner function has to be re-created too often. If the function you're memoizing is an event handler and isn't used during rendering, you can use [ref as an instance variable](#is-there-something-like-instance-variables), and save the last committed value into it manually:
+
+```js{6,10}
+function Form() {
+  const [text, updateText] = useState('');
+  const textRef = useRef();
+
+  useEffect(() => {
+    textRef.current = text; // Write it to the ref
+  });
+
+  const handleSubmit = useCallback(() => {
+    const currentText = textRef.current; // Read it from the ref
+    alert(currentText);
+  }, [textRef]); // Don't recreate handleSubmit like [text] would do
+
+  return (
+    <>
+      <input value={text} onChange={e => updateText(e.target.value)} />
+      <ExpensiveTree onSubmit={handleSubmit} />
+    </>
+  );
+}
+```
+
+This is a rather convoluted pattern but it shows that you can do this escape hatch optimization if you need it. It's more bearable if you extract it to a custom Hook:
+
+```js{4,16}
+function Form() {
+  const [text, updateText] = useState('');
+  // Will be memoized even if `text` changes:
+  const handleSubmit = useEventCallback(() => {
+    alert(text);
+  }, [text]);
+
+  return (
+    <>
+      <input value={text} onChange={e => updateText(e.target.value)} />
+      <ExpensiveTree onSubmit={handleSubmit} />
+    </>
+  );
+}
+
+function useEventCallback(fn, dependencies) {
+  const ref = useRef(() => {
+    throw new Error('Cannot call an event handler while rendering.');
+  });
+
+  useEffect(() => {
+    ref.current = fn;
+  }, [fn, ...dependencies]);
+
+  return useCallback(() => {
+    const fn = ref.current;
+    return fn();
+  }, [ref]);
+}
+```
+
+In either case, we **don't recommend this pattern** and only show it here for completeness. Instead, it is preferable to [avoid passing callbacks deep down](#how-to-avoid-passing-callbacks-down).
+
+
+## Under the Hood {#under-the-hood}
+
+### How does React associate Hook calls with components? {#how-does-react-associate-hook-calls-with-components}
+
+React keeps track of the currently rendering component. Thanks to the [Rules of Hooks](/docs/hooks-rules.html), we know that Hooks are only called from React components (or custom Hooks -- which are also only called from React components).
+
+There is an internal list of "memory cells" associated with each component. They're just JavaScript objects where we can put some data. When you call a Hook like `useState()`, it reads the current cell (or initializes it during the first render), and then moves the pointer to the next one. This is how multiple `useState()` calls each get independent local state.
+
+### What is the prior art for Hooks? {#what-is-the-prior-art-for-hooks}
+
+Hooks synthesize ideas from several different sources:
+
+* Our old experiments with functional APIs in the [react-future](https://github.com/reactjs/react-future/tree/master/07%20-%20Returning%20State) repository.
+* React community's experiments with render prop APIs, including [Ryan Florence](https://github.com/ryanflorence)'s [Reactions Component](https://github.com/reactions/component).
+* [Dominic Gannaway](https://github.com/trueadm)'s [`adopt` keyword](https://gist.github.com/trueadm/17beb64288e30192f3aa29cad0218067) proposal as a sugar syntax for render props.
+* State variables and state cells in [DisplayScript](http://displayscript.org/introduction.html).
+* [Reducer components](https://reasonml.github.io/reason-react/docs/en/state-actions-reducer.html) in ReasonReact.
+* [Subscriptions](http://reactivex.io/rxjs/class/es6/Subscription.js~Subscription.html) in Rx.
+* [Algebraic effects](https://github.com/ocamllabs/ocaml-effects-tutorial#2-effectful-computations-in-a-pure-setting) in Multicore OCaml.
+
+[Sebastian Markbåge](https://github.com/sebmarkbage) came up with the original design for Hooks, later refined by [Andrew Clark](https://github.com/acdlite), [Sophie Alpert](https://github.com/sophiebits), [Dominic Gannaway](https://github.com/trueadm), and other members of the React team.
diff --git a/hooks-intro.md b/hooks-intro.md
new file mode 100644
index 000000000..a58d16d9e
--- /dev/null
+++ b/hooks-intro.md
@@ -0,0 +1,111 @@
+---
+id: hooks-intro
+title: Introducing Hooks
+permalink: docs/hooks-intro.html
+next: hooks-overview.html
+---
+
+*Hooks* are a new addition in React 16.8. They let you use state and other React features without writing a class.
+
+```js{4,5}
+import React, { useState } from 'react';
+
+function Example() {
+  // Declare a new state variable, which we'll call "count"
+  const [count, setCount] = useState(0);
+
+  return (
+    <div>
+      <p>You clicked {count} times</p>
+      <button onClick={() => setCount(count + 1)}>
+        Click me
+      </button>
+    </div>
+  );
+}
+```
+
+This new function `useState` is the first "Hook" we'll learn about, but this example is just a teaser. Don't worry if it doesn't make sense yet!
+
+**You can start learning Hooks [on the next page](/docs/hooks-overview.html).** On this page, we'll continue by explaining why we're adding Hooks to React and how they can help you write great applications.
+
+>Note
+>
+>React 16.8.0 is the first release to support Hooks. When upgrading, don't forget to update all packages, including React DOM.
+>React Native supports Hooks since [the 0.59 release of React Native](https://facebook.github.io/react-native/blog/2019/03/12/releasing-react-native-059).
+
+## Video Introduction {#video-introduction}
+
+At React Conf 2018, Sophie Alpert and Dan Abramov introduced Hooks, followed by Ryan Florence demonstrating how to refactor an application to use them. Watch the video here:
+
+<br>
+
+<iframe width="650" height="366" src="//www.youtube.com/embed/dpw9EHDh2bM" frameborder="0" allowfullscreen></iframe>
+
+## No Breaking Changes {#no-breaking-changes}
+
+Before we continue, note that Hooks are:
+
+* **Completely opt-in.** You can try Hooks in a few components without rewriting any existing code. But you don't have to learn or use Hooks right now if you don't want to.
+* **100% backwards-compatible.** Hooks don't contain any breaking changes.
+* **Available now.** Hooks are now available with the release of v16.8.0.
+
+**There are no plans to remove classes from React.** You can read more about the gradual adoption strategy for Hooks in the [bottom section](#gradual-adoption-strategy) of this page.
+
+**Hooks don't replace your knowledge of React concepts.** Instead, Hooks provide a more direct API to the React concepts you already know: props, state, context, refs, and lifecycle. As we will show later, Hooks also offer a new powerful way to combine them.
+
+**If you just want to start learning Hooks, feel free to [jump directly to the next page!](/docs/hooks-overview.html)** You can also keep reading this page to learn more about why we're adding Hooks, and how we're going to start using them without rewriting our applications.
+
+## Motivation {#motivation}
+
+Hooks solve a wide variety of seemingly unconnected problems in React that we've encountered over five years of writing and maintaining tens of thousands of components. Whether you're learning React, use it daily, or even prefer a different library with a similar component model, you might recognize some of these problems.
+
+### It's hard to reuse stateful logic between components {#its-hard-to-reuse-stateful-logic-between-components}
+
+React doesn't offer a way to "attach" reusable behavior to a component (for example, connecting it to a store). If you've worked with React for a while, you may be familiar with patterns like [render props](/docs/render-props.html) and [higher-order components](/docs/higher-order-components.html) that try to solve this. But these patterns require you to restructure your components when you use them, which can be cumbersome and make code harder to follow. If you look at a typical React application in React DevTools, you will likely find a "wrapper hell" of components surrounded by layers of providers, consumers, higher-order components, render props, and other abstractions. While we could [filter them out in DevTools](https://github.com/facebook/react-devtools/pull/503), this points to a deeper underlying problem: React needs a better primitive for sharing stateful logic.
+
+With Hooks, you can extract stateful logic from a component so it can be tested independently and reused. **Hooks allow you to reuse stateful logic without changing your component hierarchy.** This makes it easy to share Hooks among many components or with the community.
+
+We'll discuss this more in [Building Your Own Hooks](/docs/hooks-custom.html).
+
+### Complex components become hard to understand {#complex-components-become-hard-to-understand}
+
+We've often had to maintain components that started out simple but grew into an unmanageable mess of stateful logic and side effects. Each lifecycle method often contains a mix of unrelated logic. For example, components might perform some data fetching in `componentDidMount` and `componentDidUpdate`. However, the same `componentDidMount` method might also contain some unrelated logic that sets up event listeners, with cleanup performed in `componentWillUnmount`. Mutually related code that changes together gets split apart, but completely unrelated code ends up combined in a single method. This makes it too easy to introduce bugs and inconsistencies.
+
+In many cases it's not possible to break these components into smaller ones because the stateful logic is all over the place. It's also difficult to test them. This is one of the reasons many people prefer to combine React with a separate state management library. However, that often introduces too much abstraction, requires you to jump between different files, and makes reusing components more difficult.
+
+To solve this, **Hooks let you split one component into smaller functions based on what pieces are related (such as setting up a subscription or fetching data)**, rather than forcing a split based on lifecycle methods. You may also opt into managing the component's local state with a reducer to make it more predictable.
+
+We'll discuss this more in [Using the Effect Hook](/docs/hooks-effect.html#tip-use-multiple-effects-to-separate-concerns).
+
+### Classes confuse both people and machines {#classes-confuse-both-people-and-machines}
+
+In addition to making code reuse and code organization more difficult, we've found that classes can be a large barrier to learning React. You have to understand how `this` works in JavaScript, which is very different from how it works in most languages. You have to remember to bind the event handlers. Without unstable [syntax proposals](https://babeljs.io/docs/en/babel-plugin-transform-class-properties/), the code is very verbose. People can understand props, state, and top-down data flow perfectly well but still struggle with classes. The distinction between function and class components in React and when to use each one leads to disagreements even between experienced React developers.
+
+Additionally, React has been out for about five years, and we want to make sure it stays relevant in the next five years. As [Svelte](https://svelte.dev/), [Angular](https://angular.io/), [Glimmer](https://glimmerjs.com/), and others show, [ahead-of-time compilation](https://en.wikipedia.org/wiki/Ahead-of-time_compilation) of components has a lot of future potential. Especially if it's not limited to templates. Recently, we've been experimenting with [component folding](https://github.com/facebook/react/issues/7323) using [Prepack](https://prepack.io/), and we've seen promising early results. However, we found that class components can encourage unintentional patterns that make these optimizations fall back to a slower path. Classes present issues for today's tools, too. For example, classes don't minify very well, and they make hot reloading flaky and unreliable. We want to present an API that makes it more likely for code to stay on the optimizable path.
+
+To solve these problems, **Hooks let you use more of React's features without classes.** Conceptually, React components have always been closer to functions. Hooks embrace functions, but without sacrificing the practical spirit of React. Hooks provide access to imperative escape hatches and don't require you to learn complex functional or reactive programming techniques.
+
+>Examples
+>
+>[Hooks at a Glance](/docs/hooks-overview.html) is a good place to start learning Hooks.
+
+## Gradual Adoption Strategy {#gradual-adoption-strategy}
+
+>**TLDR: There are no plans to remove classes from React.**
+
+We know that React developers are focused on shipping products and don't have time to look into every new API that's being released. Hooks are very new, and it might be better to wait for more examples and tutorials before considering learning or adopting them.
+
+We also understand that the bar for adding a new primitive to React is extremely high. For curious readers, we have prepared a [detailed RFC](https://github.com/reactjs/rfcs/pull/68) that dives into motivation with more details, and provides extra perspective on the specific design decisions and related prior art.
+
+**Crucially, Hooks work side-by-side with existing code so you can adopt them gradually.** There is no rush to migrate to Hooks. We recommend avoiding any "big rewrites", especially for existing, complex class components. It takes a bit of a mindshift to start "thinking in Hooks". In our experience, it's best to practice using Hooks in new and non-critical components first, and ensure that everybody on your team feels comfortable with them. After you give Hooks a try, please feel free to [send us feedback](https://github.com/facebook/react/issues/new), positive or negative.
+
+We intend for Hooks to cover all existing use cases for classes, but **we will keep supporting class components for the foreseeable future.** At Facebook, we have tens of thousands of components written as classes, and we have absolutely no plans to rewrite them. Instead, we are starting to use Hooks in the new code side by side with classes.
+
+## Frequently Asked Questions {#frequently-asked-questions}
+
+We've prepared a [Hooks FAQ page](/docs/hooks-faq.html) that answers the most common questions about Hooks.
+
+## Next Steps {#next-steps}
+
+By the end of this page, you should have a rough idea of what problems Hooks are solving, but many details are probably unclear. Don't worry! **Let's now go to [the next page](/docs/hooks-overview.html) where we start learning about Hooks by example.**
diff --git a/hooks-overview.md b/hooks-overview.md
new file mode 100644
index 000000000..df958dc6d
--- /dev/null
+++ b/hooks-overview.md
@@ -0,0 +1,272 @@
+---
+id: hooks-overview
+title: Hooks at a Glance
+permalink: docs/hooks-overview.html
+next: hooks-state.html
+prev: hooks-intro.html
+---
+
+*Hooks* are a new addition in React 16.8. They let you use state and other React features without writing a class.
+
+Hooks are [backwards-compatible](/docs/hooks-intro.html#no-breaking-changes). This page provides an overview of Hooks for experienced React users. This is a fast-paced overview. If you get confused, look for a yellow box like this:
+
+>Detailed Explanation
+>
+>Read the [Motivation](/docs/hooks-intro.html#motivation) to learn why we're introducing Hooks to React.
+
+**↑↑↑ Each section ends with a yellow box like this.** They link to detailed explanations.
+
+## 📌 State Hook {#state-hook}
+
+This example renders a counter. When you click the button, it increments the value:
+
+```js{1,4,5}
+import React, { useState } from 'react';
+
+function Example() {
+  // Declare a new state variable, which we'll call "count"
+  const [count, setCount] = useState(0);
+
+  return (
+    <div>
+      <p>You clicked {count} times</p>
+      <button onClick={() => setCount(count + 1)}>
+        Click me
+      </button>
+    </div>
+  );
+}
+```
+
+Here, `useState` is a *Hook* (we'll talk about what this means in a moment). We call it inside a function component to add some local state to it. React will preserve this state between re-renders. `useState` returns a pair: the *current* state value and a function that lets you update it. You can call this function from an event handler or somewhere else. It's similar to `this.setState` in a class, except it doesn't merge the old and new state together. (We'll show an example comparing `useState` to `this.state` in [Using the State Hook](/docs/hooks-state.html).)
+
+The only argument to `useState` is the initial state. In the example above, it is `0` because our counter starts from zero. Note that unlike `this.state`, the state here doesn't have to be an object -- although it can be if you want. The initial state argument is only used during the first render.
+
+#### Declaring multiple state variables {#declaring-multiple-state-variables}
+
+You can use the State Hook more than once in a single component:
+
+```js
+function ExampleWithManyStates() {
+  // Declare multiple state variables!
+  const [age, setAge] = useState(42);
+  const [fruit, setFruit] = useState('banana');
+  const [todos, setTodos] = useState([{ text: 'Learn Hooks' }]);
+  // ...
+}
+```
+
+The [array destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#Array_destructuring) syntax lets us give different names to the state variables we declared by calling `useState`. These names aren't a part of the `useState` API. Instead, React assumes that if you call `useState` many times, you do it in the same order during every render. We'll come back to why this works and when this is useful later.
+
+#### But what is a Hook? {#but-what-is-a-hook}
+
+Hooks are functions that let you “hook into” React state and lifecycle features from function components. Hooks don't work inside classes -- they let you use React without classes. (We [don't recommend](/docs/hooks-intro.html#gradual-adoption-strategy) rewriting your existing components overnight but you can start using Hooks in the new ones if you'd like.)
+
+React provides a few built-in Hooks like `useState`. You can also create your own Hooks to reuse stateful behavior between different components. We'll look at the built-in Hooks first.
+
+>Detailed Explanation
+>
+>You can learn more about the State Hook on a dedicated page: [Using the State Hook](/docs/hooks-state.html).
+
+## ⚡️ Effect Hook {#effect-hook}
+
+You've likely performed data fetching, subscriptions, or manually changing the DOM from React components before. We call these operations "side effects" (or "effects" for short) because they can affect other components and can't be done during rendering.
+
+The Effect Hook, `useEffect`, adds the ability to perform side effects from a function component. It serves the same purpose as `componentDidMount`, `componentDidUpdate`, and `componentWillUnmount` in React classes, but unified into a single API. (We'll show examples comparing `useEffect` to these methods in [Using the Effect Hook](/docs/hooks-effect.html).)
+
+For example, this component sets the document title after React updates the DOM:
+
+```js{1,6-10}
+import React, { useState, useEffect } from 'react';
+
+function Example() {
+  const [count, setCount] = useState(0);
+
+  // Similar to componentDidMount and componentDidUpdate:
+  useEffect(() => {
+    // Update the document title using the browser API
+    document.title = `You clicked ${count} times`;
+  });
+
+  return (
+    <div>
+      <p>You clicked {count} times</p>
+      <button onClick={() => setCount(count + 1)}>
+        Click me
+      </button>
+    </div>
+  );
+}
+```
+
+When you call `useEffect`, you're telling React to run your "effect" function after flushing changes to the DOM. Effects are declared inside the component so they have access to its props and state. By default, React runs the effects after every render -- *including* the first render. (We'll talk more about how this compares to class lifecycles in [Using the Effect Hook](/docs/hooks-effect.html).)
+
+Effects may also optionally specify how to "clean up" after them by returning a function. For example, this component uses an effect to subscribe to a friend's online status, and cleans up by unsubscribing from it:
+
+```js{10-16}
+import React, { useState, useEffect } from 'react';
+
+function FriendStatus(props) {
+  const [isOnline, setIsOnline] = useState(null);
+
+  function handleStatusChange(status) {
+    setIsOnline(status.isOnline);
+  }
+
+  useEffect(() => {
+    ChatAPI.subscribeToFriendStatus(props.friend.id, handleStatusChange);
+
+    return () => {
+      ChatAPI.unsubscribeFromFriendStatus(props.friend.id, handleStatusChange);
+    };
+  });
+
+  if (isOnline === null) {
+    return 'Loading...';
+  }
+  return isOnline ? 'Online' : 'Offline';
+}
+```
+
+In this example, React would unsubscribe from our `ChatAPI` when the component unmounts, as well as before re-running the effect due to a subsequent render. (If you want, there's a way to [tell React to skip re-subscribing](/docs/hooks-effect.html#tip-optimizing-performance-by-skipping-effects) if the `props.friend.id` we passed to `ChatAPI` didn’t change.)
+
+Just like with `useState`, you can use more than a single effect in a component:
+
+```js{3,8}
+function FriendStatusWithCounter(props) {
+  const [count, setCount] = useState(0);
+  useEffect(() => {
+    document.title = `You clicked ${count} times`;
+  });
+
+  const [isOnline, setIsOnline] = useState(null);
+  useEffect(() => {
+    ChatAPI.subscribeToFriendStatus(props.friend.id, handleStatusChange);
+    return () => {
+      ChatAPI.unsubscribeFromFriendStatus(props.friend.id, handleStatusChange);
+    };
+  });
+
+  function handleStatusChange(status) {
+    setIsOnline(status.isOnline);
+  }
+  // ...
+```
+
+Hooks let you organize side effects in a component by what pieces are related (such as adding and removing a subscription), rather than forcing a split based on lifecycle methods.
+
+>Detailed Explanation
+>
+>You can learn more about `useEffect` on a dedicated page: [Using the Effect Hook](/docs/hooks-effect.html).
+
+## ✌️ Rules of Hooks {#rules-of-hooks}
+
+Hooks are JavaScript functions, but they impose two additional rules:
+
+* Only call Hooks **at the top level**. Don’t call Hooks inside loops, conditions, or nested functions.
+* Only call Hooks **from React function components**. Don’t call Hooks from regular JavaScript functions. (There is just one other valid place to call Hooks -- your own custom Hooks. We'll learn about them in a moment.)
+
+We provide a [linter plugin](https://www.npmjs.com/package/eslint-plugin-react-hooks) to enforce these rules automatically. We understand these rules might seem limiting or confusing at first, but they are essential to making Hooks work well.
+
+>Detailed Explanation
+>
+>You can learn more about these rules on a dedicated page: [Rules of Hooks](/docs/hooks-rules.html).
+
+## 💡 Building Your Own Hooks {#building-your-own-hooks}
+
+Sometimes, we want to reuse some stateful logic between components. Traditionally, there were two popular solutions to this problem: [higher-order components](/docs/higher-order-components.html) and [render props](/docs/render-props.html). Custom Hooks let you do this, but without adding more components to your tree.
+
+Earlier on this page, we introduced a `FriendStatus` component that calls the `useState` and `useEffect` Hooks to subscribe to a friend's online status. Let's say we also want to reuse this subscription logic in another component.
+
+First, we'll extract this logic into a custom Hook called `useFriendStatus`:
+
+```js{3}
+import React, { useState, useEffect } from 'react';
+
+function useFriendStatus(friendID) {
+  const [isOnline, setIsOnline] = useState(null);
+
+  function handleStatusChange(status) {
+    setIsOnline(status.isOnline);
+  }
+
+  useEffect(() => {
+    ChatAPI.subscribeToFriendStatus(friendID, handleStatusChange);
+    return () => {
+      ChatAPI.unsubscribeFromFriendStatus(friendID, handleStatusChange);
+    };
+  });
+
+  return isOnline;
+}
+```
+
+It takes `friendID` as an argument, and returns whether our friend is online.
+
+Now we can use it from both components:
+
+
+```js{2}
+function FriendStatus(props) {
+  const isOnline = useFriendStatus(props.friend.id);
+
+  if (isOnline === null) {
+    return 'Loading...';
+  }
+  return isOnline ? 'Online' : 'Offline';
+}
+```
+
+```js{2}
+function FriendListItem(props) {
+  const isOnline = useFriendStatus(props.friend.id);
+
+  return (
+    <li style={{ color: isOnline ? 'green' : 'black' }}>
+      {props.friend.name}
+    </li>
+  );
+}
+```
+
+The state of these components is completely independent. Hooks are a way to reuse *stateful logic*, not state itself. In fact, each *call* to a Hook has a completely isolated state -- so you can even use the same custom Hook twice in one component.
+
+Custom Hooks are more of a convention than a feature. If a function's name starts with "`use`" and it calls other Hooks, we say it is a custom Hook. The `useSomething` naming convention is how our linter plugin is able to find bugs in the code using Hooks.
+
+You can write custom Hooks that cover a wide range of use cases like form handling, animation, declarative subscriptions, timers, and probably many more we haven't considered. We are excited to see what custom Hooks the React community will come up with.
+
+>Detailed Explanation
+>
+>You can learn more about custom Hooks on a dedicated page: [Building Your Own Hooks](/docs/hooks-custom.html).
+
+## 🔌 Other Hooks {#other-hooks}
+
+There are a few less commonly used built-in Hooks that you might find useful. For example, [`useContext`](/docs/hooks-reference.html#usecontext) lets you subscribe to React context without introducing nesting:
+
+```js{2,3}
+function Example() {
+  const locale = useContext(LocaleContext);
+  const theme = useContext(ThemeContext);
+  // ...
+}
+```
+
+And [`useReducer`](/docs/hooks-reference.html#usereducer) lets you manage local state of complex components with a reducer:
+
+```js{2}
+function Todos() {
+  const [todos, dispatch] = useReducer(todosReducer);
+  // ...
+```
+
+>Detailed Explanation
+>
+>You can learn more about all the built-in Hooks on a dedicated page: [Hooks API Reference](/docs/hooks-reference.html).
+
+## Next Steps {#next-steps}
+
+Phew, that was fast! If some things didn't quite make sense or you'd like to learn more in detail, you can read the next pages, starting with the [State Hook](/docs/hooks-state.html) documentation.
+
+You can also check out the [Hooks API reference](/docs/hooks-reference.html) and the [Hooks FAQ](/docs/hooks-faq.html).
+
+Finally, don't miss the [introduction page](/docs/hooks-intro.html) which explains *why* we're adding Hooks and how we'll start using them side by side with classes -- without rewriting our apps.
diff --git a/hooks-reference.md b/hooks-reference.md
new file mode 100644
index 000000000..852ae4833
--- /dev/null
+++ b/hooks-reference.md
@@ -0,0 +1,507 @@
+---
+id: hooks-reference
+title: Hooks API Reference
+permalink: docs/hooks-reference.html
+prev: hooks-custom.html
+next: hooks-faq.html
+---
+
+*Hooks* are a new addition in React 16.8. They let you use state and other React features without writing a class.
+
+This page describes the APIs for the built-in Hooks in React.
+
+If you're new to Hooks, you might want to check out [the overview](/docs/hooks-overview.html) first. You may also find useful information in the [frequently asked questions](/docs/hooks-faq.html) section.
+
+- [Basic Hooks](#basic-hooks)
+  - [`useState`](#usestate)
+  - [`useEffect`](#useeffect)
+  - [`useContext`](#usecontext)
+- [Additional Hooks](#additional-hooks)
+  - [`useReducer`](#usereducer)
+  - [`useCallback`](#usecallback)
+  - [`useMemo`](#usememo)
+  - [`useRef`](#useref)
+  - [`useImperativeHandle`](#useimperativehandle)
+  - [`useLayoutEffect`](#uselayouteffect)
+  - [`useDebugValue`](#usedebugvalue)
+
+## Basic Hooks {#basic-hooks}
+
+### `useState` {#usestate}
+
+```js
+const [state, setState] = useState(initialState);
+```
+
+Returns a stateful value, and a function to update it.
+
+During the initial render, the returned state (`state`) is the same as the value passed as the first argument (`initialState`).
+
+The `setState` function is used to update the state. It accepts a new state value and enqueues a re-render of the component.
+
+```js
+setState(newState);
+```
+
+During subsequent re-renders, the first value returned by `useState` will always be the most recent state after applying updates.
+
+>Note
+>
+>React guarantees that `setState` function identity is stable and won't change on re-renders. This is why it's safe to omit from the `useEffect` or `useCallback` dependency list.
+
+#### Functional updates {#functional-updates}
+
+If the new state is computed using the previous state, you can pass a function to `setState`. The function will receive the previous value, and return an updated value. Here's an example of a counter component that uses both forms of `setState`:
+
+```js
+function Counter({initialCount}) {
+  const [count, setCount] = useState(initialCount);
+  return (
+    <>
+      Count: {count}
+      <button onClick={() => setCount(initialCount)}>Reset</button>
+      <button onClick={() => setCount(prevCount => prevCount - 1)}>-</button>
+      <button onClick={() => setCount(prevCount => prevCount + 1)}>+</button>
+    </>
+  );
+}
+```
+
+The "+" and "-" buttons use the functional form, because the updated value is based on the previous value. But the "Reset" button uses the normal form, because it always sets the count back to the initial value.
+
+> Note
+>
+> Unlike the `setState` method found in class components, `useState` does not automatically merge update objects. You can replicate this behavior by combining the function updater form with object spread syntax:
+>
+> ```js
+> setState(prevState => {
+>   // Object.assign would also work
+>   return {...prevState, ...updatedValues};
+> });
+> ```
+>
+> Another option is `useReducer`, which is more suited for managing state objects that contain multiple sub-values.
+
+#### Lazy initial state {#lazy-initial-state}
+
+The `initialState` argument is the state used during the initial render. In subsequent renders, it is disregarded. If the initial state is the result of an expensive computation, you may provide a function instead, which will be executed only on the initial render:
+
+```js
+const [state, setState] = useState(() => {
+  const initialState = someExpensiveComputation(props);
+  return initialState;
+});
+```
+
+#### Bailing out of a state update {#bailing-out-of-a-state-update}
+
+If you update a State Hook to the same value as the current state, React will bail out without rendering the children or firing effects. (React uses the [`Object.is` comparison algorithm](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is#Description).)
+
+Note that React may still need to render that specific component again before bailing out. That shouldn't be a concern because React won't unnecessarily go "deeper" into the tree. If you're doing expensive calculations while rendering, you can optimize them with `useMemo`.
+
+### `useEffect` {#useeffect}
+
+```js
+useEffect(didUpdate);
+```
+
+Accepts a function that contains imperative, possibly effectful code.
+
+Mutations, subscriptions, timers, logging, and other side effects are not allowed inside the main body of a function component (referred to as React's _render phase_). Doing so will lead to confusing bugs and inconsistencies in the UI.
+
+Instead, use `useEffect`. The function passed to `useEffect` will run after the render is committed to the screen. Think of effects as an escape hatch from React's purely functional world into the imperative world.
+
+By default, effects run after every completed render, but you can choose to fire them [only when certain values have changed](#conditionally-firing-an-effect).
+
+#### Cleaning up an effect {#cleaning-up-an-effect}
+
+Often, effects create resources that need to be cleaned up before the component leaves the screen, such as a subscription or timer ID. To do this, the function passed to `useEffect` may return a clean-up function. For example, to create a subscription:
+
+```js
+useEffect(() => {
+  const subscription = props.source.subscribe();
+  return () => {
+    // Clean up the subscription
+    subscription.unsubscribe();
+  };
+});
+```
+
+The clean-up function runs before the component is removed from the UI to prevent memory leaks. Additionally, if a component renders multiple times (as they typically do), the **previous effect is cleaned up before executing the next effect**. In our example, this means a new subscription is created on every update. To avoid firing an effect on every update, refer to the next section.
+
+#### Timing of effects {#timing-of-effects}
+
+Unlike `componentDidMount` and `componentDidUpdate`, the function passed to `useEffect` fires **after** layout and paint, during a deferred event. This makes it suitable for the many common side effects, like setting up subscriptions and event handlers, because most types of work shouldn't block the browser from updating the screen.
+
+However, not all effects can be deferred. For example, a DOM mutation that is visible to the user must fire synchronously before the next paint so that the user does not perceive a visual inconsistency. (The distinction is conceptually similar to passive versus active event listeners.) For these types of effects, React provides one additional Hook called [`useLayoutEffect`](#uselayouteffect). It has the same signature as `useEffect`, and only differs in when it is fired.
+
+Although `useEffect` is deferred until after the browser has painted, it's guaranteed to fire before any new renders. React will always flush a previous render's effects before starting a new update.
+
+#### Conditionally firing an effect {#conditionally-firing-an-effect}
+
+The default behavior for effects is to fire the effect after every completed render. That way an effect is always recreated if one of its dependencies changes.
+
+However, this may be overkill in some cases, like the subscription example from the previous section. We don't need to create a new subscription on every update, only if the `source` props has changed.
+
+To implement this, pass a second argument to `useEffect` that is the array of values that the effect depends on. Our updated example now looks like this:
+
+```js
+useEffect(
+  () => {
+    const subscription = props.source.subscribe();
+    return () => {
+      subscription.unsubscribe();
+    };
+  },
+  [props.source],
+);
+```
+
+Now the subscription will only be recreated when `props.source` changes.
+
+>Note
+>
+>If you use this optimization, make sure the array includes **all values from the component scope (such as props and state) that change over time and that are used by the effect**. Otherwise, your code will reference stale values from previous renders. Learn more about [how to deal with functions](/docs/hooks-faq.html#is-it-safe-to-omit-functions-from-the-list-of-dependencies) and what to do when the [array values change too often](/docs/hooks-faq.html#what-can-i-do-if-my-effect-dependencies-change-too-often).
+>
+>If you want to run an effect and clean it up only once (on mount and unmount), you can pass an empty array (`[]`) as a second argument. This tells React that your effect doesn't depend on *any* values from props or state, so it never needs to re-run. This isn't handled as a special case -- it follows directly from how the dependencies array always works.
+>
+>If you pass an empty array (`[]`), the props and state inside the effect will always have their initial values. While passing `[]` as the second argument is closer to the familiar `componentDidMount` and `componentWillUnmount` mental model, there are usually [better](/docs/hooks-faq.html#is-it-safe-to-omit-functions-from-the-list-of-dependencies) [solutions](/docs/hooks-faq.html#what-can-i-do-if-my-effect-dependencies-change-too-often) to avoid re-running effects too often. Also, don't forget that React defers running `useEffect` until after the browser has painted, so doing extra work is less of a problem.
+>
+>
+>We recommend using the [`exhaustive-deps`](https://github.com/facebook/react/issues/14920) rule as part of our [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks#installation) package. It warns when dependencies are specified incorrectly and suggests a fix.
+
+The array of dependencies is not passed as arguments to the effect function. Conceptually, though, that's what they represent: every value referenced inside the effect function should also appear in the dependencies array. In the future, a sufficiently advanced compiler could create this array automatically.
+
+### `useContext` {#usecontext}
+
+```js
+const value = useContext(MyContext);
+```
+
+Accepts a context object (the value returned from `React.createContext`) and returns the current context value for that context. The current context value is determined by the `value` prop of the nearest `<MyContext.Provider>` above the calling component in the tree.
+
+When the nearest `<MyContext.Provider>` above the component updates, this Hook will trigger a rerender with the latest context `value` passed to that `MyContext` provider.
+
+Don't forget that the argument to `useContext` must be the *context object itself*:
+
+ * **Correct:** `useContext(MyContext)`
+ * **Incorrect:** `useContext(MyContext.Consumer)`
+ * **Incorrect:** `useContext(MyContext.Provider)`
+
+A component calling `useContext` will always re-render when the context value changes. If re-rendering the component is expensive, you can [optimize it by using memoization](https://github.com/facebook/react/issues/15156#issuecomment-474590693).
+
+>Tip
+>
+>If you're familiar with the context API before Hooks, `useContext(MyContext)` is equivalent to `static contextType = MyContext` in a class, or to `<MyContext.Consumer>`.
+>
+>`useContext(MyContext)` only lets you *read* the context and subscribe to its changes. You still need a `<MyContext.Provider>` above in the tree to *provide* the value for this context.
+
+**Putting it together with Context.Provider**
+```js{31-36}
+const themes = {
+  light: {
+    foreground: "#000000",
+    background: "#eeeeee"
+  },
+  dark: {
+    foreground: "#ffffff",
+    background: "#222222"
+  }
+};
+
+const ThemeContext = React.createContext(themes.light);
+
+function App() {
+  return (
+    <ThemeContext.Provider value={themes.dark}>
+      <Toolbar />
+    </ThemeContext.Provider>
+  );
+}
+
+function Toolbar(props) {
+  return (
+    <div>
+      <ThemedButton />
+    </div>
+  );
+}
+
+function ThemedButton() {
+  const theme = useContext(ThemeContext);
+
+  return (
+    <button style={{ background: theme.background, color: theme.foreground }}>
+      I am styled by theme context!
+    </button>
+  );
+}
+```
+This example is modified for hooks from a previous example in the [Context Advanced Guide](/docs/context.html), where you can find more information about when and how to use Context.
+
+
+## Additional Hooks {#additional-hooks}
+
+The following Hooks are either variants of the basic ones from the previous section, or only needed for specific edge cases. Don't stress about learning them up front.
+
+### `useReducer` {#usereducer}
+
+```js
+const [state, dispatch] = useReducer(reducer, initialArg, init);
+```
+
+An alternative to [`useState`](#usestate). Accepts a reducer of type `(state, action) => newState`, and returns the current state paired with a `dispatch` method. (If you're familiar with Redux, you already know how this works.)
+
+`useReducer` is usually preferable to `useState` when you have complex state logic that involves multiple sub-values or when the next state depends on the previous one. `useReducer` also lets you optimize performance for components that trigger deep updates because [you can pass `dispatch` down instead of callbacks](/docs/hooks-faq.html#how-to-avoid-passing-callbacks-down).
+
+Here's the counter example from the [`useState`](#usestate) section, rewritten to use a reducer:
+
+```js
+const initialState = {count: 0};
+
+function reducer(state, action) {
+  switch (action.type) {
+    case 'increment':
+      return {count: state.count + 1};
+    case 'decrement':
+      return {count: state.count - 1};
+    default:
+      throw new Error();
+  }
+}
+
+function Counter() {
+  const [state, dispatch] = useReducer(reducer, initialState);
+  return (
+    <>
+      Count: {state.count}
+      <button onClick={() => dispatch({type: 'decrement'})}>-</button>
+      <button onClick={() => dispatch({type: 'increment'})}>+</button>
+    </>
+  );
+}
+```
+
+>Note
+>
+>React guarantees that `dispatch` function identity is stable and won't change on re-renders. This is why it's safe to omit from the `useEffect` or `useCallback` dependency list.
+
+#### Specifying the initial state {#specifying-the-initial-state}
+
+There are two different ways to initialize `useReducer` state. You may choose either one depending on the use case. The simplest way is to pass the initial state as a second argument:
+
+```js{3}
+  const [state, dispatch] = useReducer(
+    reducer,
+    {count: initialCount}
+  );
+```
+
+>Note
+>
+>React doesn’t use the `state = initialState` argument convention popularized by Redux. The initial value sometimes needs to depend on props and so is specified from the Hook call instead. If you feel strongly about this, you can call `useReducer(reducer, undefined, reducer)` to emulate the Redux behavior, but it's not encouraged.
+
+#### Lazy initialization {#lazy-initialization}
+
+You can also create the initial state lazily. To do this, you can pass an `init` function as the third argument. The initial state will be set to `init(initialArg)`.
+
+It lets you extract the logic for calculating the initial state outside the reducer. This is also handy for resetting the state later in response to an action:
+
+```js{1-3,11-12,19,24}
+function init(initialCount) {
+  return {count: initialCount};
+}
+
+function reducer(state, action) {
+  switch (action.type) {
+    case 'increment':
+      return {count: state.count + 1};
+    case 'decrement':
+      return {count: state.count - 1};
+    case 'reset':
+      return init(action.payload);
+    default:
+      throw new Error();
+  }
+}
+
+function Counter({initialCount}) {
+  const [state, dispatch] = useReducer(reducer, initialCount, init);
+  return (
+    <>
+      Count: {state.count}
+      <button
+        onClick={() => dispatch({type: 'reset', payload: initialCount})}>
+        Reset
+      </button>
+      <button onClick={() => dispatch({type: 'decrement'})}>-</button>
+      <button onClick={() => dispatch({type: 'increment'})}>+</button>
+    </>
+  );
+}
+```
+
+#### Bailing out of a dispatch {#bailing-out-of-a-dispatch}
+
+If you return the same value from a Reducer Hook as the current state, React will bail out without rendering the children or firing effects. (React uses the [`Object.is` comparison algorithm](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is#Description).)
+
+Note that React may still need to render that specific component again before bailing out. That shouldn't be a concern because React won't unnecessarily go "deeper" into the tree. If you're doing expensive calculations while rendering, you can optimize them with `useMemo`.
+
+### `useCallback` {#usecallback}
+
+```js
+const memoizedCallback = useCallback(
+  () => {
+    doSomething(a, b);
+  },
+  [a, b],
+);
+```
+
+Returns a [memoized](https://en.wikipedia.org/wiki/Memoization) callback.
+
+Pass an inline callback and an array of dependencies. `useCallback` will return a memoized version of the callback that only changes if one of the dependencies has changed. This is useful when passing callbacks to optimized child components that rely on reference equality to prevent unnecessary renders (e.g. `shouldComponentUpdate`).
+
+`useCallback(fn, deps)` is equivalent to `useMemo(() => fn, deps)`.
+
+> Note
+>
+> The array of dependencies is not passed as arguments to the callback. Conceptually, though, that's what they represent: every value referenced inside the callback should also appear in the dependencies array. In the future, a sufficiently advanced compiler could create this array automatically.
+>
+> We recommend using the [`exhaustive-deps`](https://github.com/facebook/react/issues/14920) rule as part of our [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks#installation) package. It warns when dependencies are specified incorrectly and suggests a fix.
+
+### `useMemo` {#usememo}
+
+```js
+const memoizedValue = useMemo(() => computeExpensiveValue(a, b), [a, b]);
+```
+
+Returns a [memoized](https://en.wikipedia.org/wiki/Memoization) value.
+
+Pass a "create" function and an array of dependencies. `useMemo` will only recompute the memoized value when one of the dependencies has changed. This optimization helps to avoid expensive calculations on every render.
+
+Remember that the function passed to `useMemo` runs during rendering. Don't do anything there that you wouldn't normally do while rendering. For example, side effects belong in `useEffect`, not `useMemo`.
+
+If no array is provided, a new value will be computed on every render.
+
+**You may rely on `useMemo` as a performance optimization, not as a semantic guarantee.** In the future, React may choose to "forget" some previously memoized values and recalculate them on next render, e.g. to free memory for offscreen components. Write your code so that it still works without `useMemo` — and then add it to optimize performance.
+
+> Note
+>
+> The array of dependencies is not passed as arguments to the function. Conceptually, though, that's what they represent: every value referenced inside the function should also appear in the dependencies array. In the future, a sufficiently advanced compiler could create this array automatically.
+>
+> We recommend using the [`exhaustive-deps`](https://github.com/facebook/react/issues/14920) rule as part of our [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks#installation) package. It warns when dependencies are specified incorrectly and suggests a fix.
+
+### `useRef` {#useref}
+
+```js
+const refContainer = useRef(initialValue);
+```
+
+`useRef` returns a mutable ref object whose `.current` property is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component.
+
+A common use case is to access a child imperatively:
+
+```js
+function TextInputWithFocusButton() {
+  const inputEl = useRef(null);
+  const onButtonClick = () => {
+    // `current` points to the mounted text input element
+    inputEl.current.focus();
+  };
+  return (
+    <>
+      <input ref={inputEl} type="text" />
+      <button onClick={onButtonClick}>Focus the input</button>
+    </>
+  );
+}
+```
+
+Essentially, `useRef` is like a "box" that can hold a mutable value in its `.current` property.
+
+You might be familiar with refs primarily as a way to [access the DOM](/docs/refs-and-the-dom.html). If you pass a ref object to React with `<div ref={myRef} />`, React will set its `.current` property to the corresponding DOM node whenever that node changes.
+
+However, `useRef()` is useful for more than the `ref` attribute. It's [handy for keeping any mutable value around](/docs/hooks-faq.html#is-there-something-like-instance-variables) similar to how you'd use instance fields in classes.
+
+This works because `useRef()` creates a plain JavaScript object. The only difference between `useRef()` and creating a `{current: ...}` object yourself is that `useRef` will give you the same ref object on every render.
+
+Keep in mind that `useRef` *doesn't* notify you when its content changes. Mutating the `.current` property doesn't cause a re-render. If you want to run some code when React attaches or detaches a ref to a DOM node, you may want to use a [callback ref](/docs/hooks-faq.html#how-can-i-measure-a-dom-node) instead.
+
+
+### `useImperativeHandle` {#useimperativehandle}
+
+```js
+useImperativeHandle(ref, createHandle, [deps])
+```
+
+`useImperativeHandle` customizes the instance value that is exposed to parent components when using `ref`. As always, imperative code using refs should be avoided in most cases. `useImperativeHandle` should be used with `forwardRef`:
+
+```js
+function FancyInput(props, ref) {
+  const inputRef = useRef();
+  useImperativeHandle(ref, () => ({
+    focus: () => {
+      inputRef.current.focus();
+    }
+  }));
+  return <input ref={inputRef} ... />;
+}
+FancyInput = forwardRef(FancyInput);
+```
+
+In this example, a parent component that renders `<FancyInput ref={fancyInputRef} />` would be able to call `fancyInputRef.current.focus()`.
+
+### `useLayoutEffect` {#uselayouteffect}
+
+The signature is identical to `useEffect`, but it fires synchronously after all DOM mutations. Use this to read layout from the DOM and synchronously re-render. Updates scheduled inside `useLayoutEffect` will be flushed synchronously, before the browser has a chance to paint.
+
+Prefer the standard `useEffect` when possible to avoid blocking visual updates.
+
+> Tip
+>
+> If you're migrating code from a class component, note `useLayoutEffect` fires in the same phase as `componentDidMount` and `componentDidUpdate`. However, **we recommend starting with `useEffect` first** and only trying `useLayoutEffect` if that causes a problem.
+>
+>If you use server rendering, keep in mind that *neither* `useLayoutEffect` nor `useEffect` can run until the JavaScript is downloaded. This is why React warns when a server-rendered component contains `useLayoutEffect`. To fix this, either move that logic to `useEffect` (if it isn't necessary for the first render), or delay showing that component until after the client renders (if the HTML looks broken until `useLayoutEffect` runs).
+>
+>To exclude a component that needs layout effects from the server-rendered HTML, render it conditionally with `showChild && <Child />` and defer showing it with `useEffect(() => { setShowChild(true); }, [])`. This way, the UI doesn't appear broken before hydration.
+
+### `useDebugValue` {#usedebugvalue}
+
+```js
+useDebugValue(value)
+```
+
+`useDebugValue` can be used to display a label for custom hooks in React DevTools.
+
+For example, consider the `useFriendStatus` custom Hook described in ["Building Your Own Hooks"](/docs/hooks-custom.html):
+
+```js{6-8}
+function useFriendStatus(friendID) {
+  const [isOnline, setIsOnline] = useState(null);
+
+  // ...
+
+  // Show a label in DevTools next to this Hook
+  // e.g. "FriendStatus: Online"
+  useDebugValue(isOnline ? 'Online' : 'Offline');
+
+  return isOnline;
+}
+```
+
+> Tip
+>
+> We don't recommend adding debug values to every custom Hook. It's most valuable for custom Hooks that are part of shared libraries.
+
+#### Defer formatting debug values {#defer-formatting-debug-values}
+
+In some cases formatting a value for display might be an expensive operation. It's also unnecessary unless a Hook is actually inspected.
+
+For this reason `useDebugValue` accepts a formatting function as an optional second parameter. This function is only called if the Hooks are inspected. It receives the debug value as a parameter and should return a formatted display value.
+
+For example a custom Hook that returned a `Date` value could avoid calling the `toDateString` function unnecessarily by passing the following formatter:
+
+```js
+useDebugValue(date, date => date.toDateString());
+```
diff --git a/hooks-rules.md b/hooks-rules.md
new file mode 100644
index 000000000..625d1e4d5
--- /dev/null
+++ b/hooks-rules.md
@@ -0,0 +1,138 @@
+---
+id: hooks-rules
+title: Rules of Hooks
+permalink: docs/hooks-rules.html
+next: hooks-custom.html
+prev: hooks-effect.html
+---
+
+*Hooks* are a new addition in React 16.8. They let you use state and other React features without writing a class.
+
+Hooks are JavaScript functions, but you need to follow two rules when using them. We provide a [linter plugin](https://www.npmjs.com/package/eslint-plugin-react-hooks) to enforce these rules automatically:
+
+### Only Call Hooks at the Top Level {#only-call-hooks-at-the-top-level}
+
+**Don't call Hooks inside loops, conditions, or nested functions.** Instead, always use Hooks at the top level of your React function. By following this rule, you ensure that Hooks are called in the same order each time a component renders. That's what allows React to correctly preserve the state of Hooks between multiple `useState` and `useEffect` calls. (If you're curious, we'll explain this in depth [below](#explanation).)
+
+### Only Call Hooks from React Functions {#only-call-hooks-from-react-functions}
+
+**Don't call Hooks from regular JavaScript functions.** Instead, you can:
+
+* ✅ Call Hooks from React function components.
+* ✅ Call Hooks from custom Hooks (we'll learn about them [on the next page](/docs/hooks-custom.html)).
+
+By following this rule, you ensure that all stateful logic in a component is clearly visible from its source code.
+
+## ESLint Plugin {#eslint-plugin}
+
+We released an ESLint plugin called [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks) that enforces these two rules. You can add this plugin to your project if you'd like to try it:
+
+```bash
+npm install eslint-plugin-react-hooks --save-dev
+```
+
+```js
+// Your ESLint configuration
+{
+  "plugins": [
+    // ...
+    "react-hooks"
+  ],
+  "rules": {
+    // ...
+    "react-hooks/rules-of-hooks": "error", // Checks rules of Hooks
+    "react-hooks/exhaustive-deps": "warn" // Checks effect dependencies
+  }
+}
+```
+
+In the future, we intend to include this plugin by default into Create React App and similar toolkits.
+
+**You can skip to the next page explaining how to write [your own Hooks](/docs/hooks-custom.html) now.** On this page, we'll continue by explaining the reasoning behind these rules.
+
+## Explanation {#explanation}
+
+As we [learned earlier](/docs/hooks-state.html#tip-using-multiple-state-variables), we can use multiple State or Effect Hooks in a single component:
+
+```js
+function Form() {
+  // 1. Use the name state variable
+  const [name, setName] = useState('Mary');
+
+  // 2. Use an effect for persisting the form
+  useEffect(function persistForm() {
+    localStorage.setItem('formData', name);
+  });
+
+  // 3. Use the surname state variable
+  const [surname, setSurname] = useState('Poppins');
+
+  // 4. Use an effect for updating the title
+  useEffect(function updateTitle() {
+    document.title = name + ' ' + surname;
+  });
+
+  // ...
+}
+```
+
+So how does React know which state corresponds to which `useState` call? The answer is that **React relies on the order in which Hooks are called**. Our example works because the order of the Hook calls is the same on every render:
+
+```js
+// ------------
+// First render
+// ------------
+useState('Mary')           // 1. Initialize the name state variable with 'Mary'
+useEffect(persistForm)     // 2. Add an effect for persisting the form
+useState('Poppins')        // 3. Initialize the surname state variable with 'Poppins'
+useEffect(updateTitle)     // 4. Add an effect for updating the title
+
+// -------------
+// Second render
+// -------------
+useState('Mary')           // 1. Read the name state variable (argument is ignored)
+useEffect(persistForm)     // 2. Replace the effect for persisting the form
+useState('Poppins')        // 3. Read the surname state variable (argument is ignored)
+useEffect(updateTitle)     // 4. Replace the effect for updating the title
+
+// ...
+```
+
+As long as the order of the Hook calls is the same between renders, React can associate some local state with each of them. But what happens if we put a Hook call (for example, the `persistForm` effect) inside a condition?
+
+```js
+  // 🔴 We're breaking the first rule by using a Hook in a condition
+  if (name !== '') {
+    useEffect(function persistForm() {
+      localStorage.setItem('formData', name);
+    });
+  }
+```
+
+The `name !== ''` condition is `true` on the first render, so we run this Hook. However, on the next render the user might clear the form, making the condition `false`. Now that we skip this Hook during rendering, the order of the Hook calls becomes different:
+
+```js
+useState('Mary')           // 1. Read the name state variable (argument is ignored)
+// useEffect(persistForm)  // 🔴 This Hook was skipped!
+useState('Poppins')        // 🔴 2 (but was 3). Fail to read the surname state variable
+useEffect(updateTitle)     // 🔴 3 (but was 4). Fail to replace the effect
+```
+
+React wouldn't know what to return for the second `useState` Hook call. React expected that the second Hook call in this component corresponds to the `persistForm` effect, just like during the previous render, but it doesn't anymore. From that point, every next Hook call after the one we skipped would also shift by one, leading to bugs.
+
+**This is why Hooks must be called on the top level of our components.** If we want to run an effect conditionally, we can put that condition *inside* our Hook:
+
+```js
+  useEffect(function persistForm() {
+    // 👍 We're not breaking the first rule anymore
+    if (name !== '') {
+      localStorage.setItem('formData', name);
+    }
+  });
+```
+
+**Note that you don't need to worry about this problem if you use the [provided lint rule](https://www.npmjs.com/package/eslint-plugin-react-hooks).** But now you also know *why* Hooks work this way, and which issues the rule is preventing.
+
+## Next Steps {#next-steps}
+
+Finally, we're ready to learn about [writing your own Hooks](/docs/hooks-custom.html)! Custom Hooks let you combine Hooks provided by React into your own abstractions, and reuse common stateful logic between different components.
diff --git a/hooks-state.md b/hooks-state.md
new file mode 100644
index 000000000..0b4d15b65
--- /dev/null
+++ b/hooks-state.md
@@ -0,0 +1,280 @@
+---
+id: hooks-state
+title: Using the State Hook
+permalink: docs/hooks-state.html
+next: hooks-effect.html
+prev: hooks-overview.html
+---
+
+*Hooks* are a new addition in React 16.8. They let you use state and other React features without writing a class.
+
+The [introduction page](/docs/hooks-intro.html) used this example to get familiar with Hooks:
+
+```js{4-5}
+import React, { useState } from 'react';
+
+function Example() {
+  // Declare a new state variable, which we'll call "count"
+  const [count, setCount] = useState(0);
+
+  return (
+    <div>
+      <p>You clicked {count} times</p>
+      <button onClick={() => setCount(count + 1)}>
+        Click me
+      </button>
+    </div>
+  );
+}
+```
+
+We'll start learning about Hooks by comparing this code to an equivalent class example.
+
+## Equivalent Class Example {#equivalent-class-example}
+
+If you used classes in React before, this code should look familiar:
+
+```js
+class Example extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      count: 0
+    };
+  }
+
+  render() {
+    return (
+      <div>
+        <p>You clicked {this.state.count} times</p>
+        <button onClick={() => this.setState({ count: this.state.count + 1 })}>
+          Click me
+        </button>
+      </div>
+    );
+  }
+}
+```
+
+The state starts as `{ count: 0 }`, and we increment `state.count` when the user clicks a button by calling `this.setState()`. We'll use snippets from this class throughout the page.
+
+>Note
+>
+>You might be wondering why we're using a counter here instead of a more realistic example. This is to help us focus on the API while we're still making our first steps with Hooks.
+
+## Hooks and Function Components {#hooks-and-function-components}
+
+As a reminder, function components in React look like this:
+
+```js
+const Example = (props) => {
+  // You can use Hooks here!
+  return <div />;
+}
+```
+
+or this:
+
+```js
+function Example(props) {
+  // You can use Hooks here!
+  return <div />;
+}
+```
+
+You might have previously known these as "stateless components". We're now introducing the ability to use React state from these, so we prefer the name "function components".
+
+Hooks **don't** work inside classes. But you can use them instead of writing classes.
+
+## What's a Hook? {#whats-a-hook}
+
+Our new example starts by importing the `useState` Hook from React:
+
+```js{1}
+import React, { useState } from 'react';
+
+function Example() {
+  // ...
+}
+```
+
+**What is a Hook?** A Hook is a special function that lets you "hook into" React features. For example, `useState` is a Hook that lets you add React state to function components. We'll learn other Hooks later.
+
+**When would I use a Hook?** If you write a function component and realize you need to add some state to it, previously you had to convert it to a class. Now you can use a Hook inside the existing function component. We're going to do that right now!
+
+>Note:
+>
+>There are some special rules about where you can and can't use Hooks within a component. We'll learn them in [Rules of Hooks](/docs/hooks-rules.html).
+
+## Declaring a State Variable {#declaring-a-state-variable}
+
+In a class, we initialize the `count` state to `0` by setting `this.state` to `{ count: 0 }` in the constructor:
+
+```js{4-6}
+class Example extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      count: 0
+    };
+  }
+```
+
+In a function component, we have no `this`, so we can't assign or read `this.state`. Instead, we call the `useState` Hook directly inside our component:
+
+```js{4,5}
+import React, { useState } from 'react';
+
+function Example() {
+  // Declare a new state variable, which we'll call "count"
+  const [count, setCount] = useState(0);
+```
+
+**What does calling `useState` do?** It declares a "state variable". Our variable is called `count` but we could call it anything else, like `banana`. This is a way to "preserve" some values between the function calls — `useState` is a new way to use the exact same capabilities that `this.state` provides in a class. Normally, variables "disappear" when the function exits but state variables are preserved by React.
+
+**What do we pass to `useState` as an argument?** The only argument to the `useState()` Hook is the initial state. Unlike with classes, the state doesn't have to be an object. We can keep a number or a string if that's all we need. In our example, we just want a number for how many times the user clicked, so pass `0` as initial state for our variable. (If we wanted to store two different values in state, we would call `useState()` twice.)
+
+**What does `useState` return?** It returns a pair of values: the current state and a function that updates it. This is why we write `const [count, setCount] = useState()`. This is similar to `this.state.count` and `this.setState` in a class, except you get them in a pair. If you're not familiar with the syntax we used, we'll come back to it [at the bottom of this page](/docs/hooks-state.html#tip-what-do-square-brackets-mean).
+
+Now that we know what the `useState` Hook does, our example should make more sense:
+
+```js{4,5}
+import React, { useState } from 'react';
+
+function Example() {
+  // Declare a new state variable, which we'll call "count"
+  const [count, setCount] = useState(0);
+```
+
+We declare a state variable called `count`, and set it to `0`. React will remember its current value between re-renders, and provide the most recent one to our function. If we want to update the current `count`, we can call `setCount`.
+
+>Note
+>
+>You might be wondering: why is `useState` not named `createState` instead?
+>
+>"Create" wouldn't be quite accurate because the state is only created the first time our component renders. During the next renders, `useState` gives us the current state. Otherwise it wouldn't be "state" at all! There's also a reason why Hook names *always* start with `use`. We'll learn why later in the [Rules of Hooks](/docs/hooks-rules.html).
+
+## Reading State {#reading-state}
+
+When we want to display the current count in a class, we read `this.state.count`:
+
+```js
+  <p>You clicked {this.state.count} times</p>
+```
+
+In a function, we can use `count` directly:
+
+
+```js
+  <p>You clicked {count} times</p>
+```
+
+## Updating State {#updating-state}
+
+In a class, we need to call `this.setState()` to update the `count` state:
+
+```js{1}
+  <button onClick={() => this.setState({ count: this.state.count + 1 })}>
+    Click me
+  </button>
+```
+
+In a function, we already have `setCount` and `count` as variables so we don't need `this`:
+
+```js{1}
+  <button onClick={() => setCount(count + 1)}>
+    Click me
+  </button>
+```
+
+## Recap {#recap}
+
+Let's now **recap what we learned line by line** and check our understanding.
+
+<!--
+  I'm not proud of this line markup. Please somebody fix this.
+  But if GitHub got away with it for years we can cheat.
+-->
+```js{1,4,9}
+ 1:  import React, { useState } from 'react';
+ 2:
+ 3:  function Example() {
+ 4:    const [count, setCount] = useState(0);
+ 5:
+ 6:    return (
+ 7:      <div>
+ 8:        <p>You clicked {count} times</p>
+ 9:        <button onClick={() => setCount(count + 1)}>
+10:         Click me
+11:        </button>
+12:      </div>
+13:    );
+14:  }
+```
+
+* **Line 1:** We import the `useState` Hook from React. It lets us keep local state in a function component.
+* **Line 4:** Inside the `Example` component, we declare a new state variable by calling the `useState` Hook. It returns a pair of values, to which we give names. We're calling our variable `count` because it holds the number of button clicks. We initialize it to zero by passing `0` as the only `useState` argument. The second returned item is itself a function. It lets us update the `count` so we'll name it `setCount`.
+* **Line 9:** When the user clicks, we call `setCount` with a new value. React will then re-render the `Example` component, passing the new `count` value to it.
+
+This might seem like a lot to take in at first. Don't rush it! If you're lost in the explanation, look at the code above again and try to read it from top to bottom. We promise that once you try to "forget" how state works in classes, and look at this code with fresh eyes, it will make sense.
+
+### Tip: What Do Square Brackets Mean? {#tip-what-do-square-brackets-mean}
+
+You might have noticed the square brackets when we declare a state variable:
+
+```js
+  const [count, setCount] = useState(0);
+```
+
+The names on the left aren't a part of the React API. You can name your own state variables:
+
+```js
+  const [fruit, setFruit] = useState('banana');
+```
+
+This JavaScript syntax is called ["array destructuring"](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#Array_destructuring). It means that we're making two new variables `fruit` and `setFruit`, where `fruit` is set to the first value returned by `useState`, and `setFruit` is the second. It is equivalent to this code:
+
+```js
+  var fruitStateVariable = useState('banana'); // Returns a pair
+  var fruit = fruitStateVariable[0]; // First item in a pair
+  var setFruit = fruitStateVariable[1]; // Second item in a pair
+```
+
+When we declare a state variable with `useState`, it returns a pair — an array with two items. The first item is the current value, and the second is a function that lets us update it. Using `[0]` and `[1]` to access them is a bit confusing because they have a specific meaning. This is why we use array destructuring instead.
+
+>Note
+>
+>You might be curious how React knows which component `useState` corresponds to since we're not passing anything like `this` back to React. We'll answer [this question](/docs/hooks-faq.html#how-does-react-associate-hook-calls-with-components) and many others in the FAQ section.
+
+### Tip: Using Multiple State Variables {#tip-using-multiple-state-variables}
+
+Declaring state variables as a pair of `[something, setSomething]` is also handy because it lets us give *different* names to different state variables if we want to use more than one:
+
+```js
+function ExampleWithManyStates() {
+  // Declare multiple state variables!
+  const [age, setAge] = useState(42);
+  const [fruit, setFruit] = useState('banana');
+  const [todos, setTodos] = useState([{ text: 'Learn Hooks' }]);
+```
+
+In the above component, we have `age`, `fruit`, and `todos` as local variables, and we can update them individually:
+
+```js
+  function handleOrangeClick() {
+    // Similar to this.setState({ fruit: 'orange' })
+    setFruit('orange');
+  }
+```
+
+You **don't have to** use many state variables. State variables can hold objects and arrays just fine, so you can still group related data together. However, unlike `this.setState` in a class, updating a state variable always *replaces* it instead of merging it.
+
+We provide more recommendations on splitting independent state variables [in the FAQ](/docs/hooks-faq.html#should-i-use-one-or-many-state-variables).
+
+## Next Steps {#next-steps}
+
+On this page we've learned about one of the Hooks provided by React, called `useState`. We're also sometimes going to refer to it as the "State Hook". It lets us add local state to React function components -- which we did for the first time ever!
+
+We also learned a little bit more about what Hooks are. Hooks are functions that let you "hook into" React features from function components. Their names always start with `use`, and there are more Hooks we haven't seen yet.
+
+**Now let's continue by [learning the next Hook: `useEffect`.](/docs/hooks-effect.html)** It lets you perform side effects in components, and is similar to lifecycle methods in classes.
diff --git a/how-to-contribute.md b/how-to-contribute.md
new file mode 100644
index 000000000..cd5bd0c55
--- /dev/null
+++ b/how-to-contribute.md
@@ -0,0 +1,184 @@
+---
+id: how-to-contribute
+title: How to Contribute
+layout: contributing
+permalink: docs/how-to-contribute.html
+next: codebase-overview.html
+redirect_from:
+  - "contributing/how-to-contribute.html"
+  - "tips/introduction.html"
+---
+
+React is one of Facebook's first open source projects that is both under very active development and is also being used to ship code to everybody on [facebook.com](https://www.facebook.com). We're still working out the kinks to make contributing to this project as easy and transparent as possible, but we're not quite there yet. Hopefully this document makes the process for contributing clear and answers some questions that you may have.
+
+### [Code of Conduct](https://github.com/facebook/react/blob/master/CODE_OF_CONDUCT.md) {#code-of-conduct}
+
+Facebook has adopted the [Contributor Covenant](https://www.contributor-covenant.org/) as its Code of Conduct, and we expect project participants to adhere to it. Please read [the full text](https://github.com/facebook/react/blob/master/CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated.
+
+### Open Development {#open-development}
+
+All work on React happens directly on [GitHub](https://github.com/facebook/react). Both core team members and external contributors send pull requests which go through the same review process.
+
+### Semantic Versioning {#semantic-versioning}
+
+React follows [semantic versioning](https://semver.org/). We release patch versions for critical bugfixes, minor versions for new features or non-essential changes, and major versions for any breaking changes. When we make breaking changes, we also introduce deprecation warnings in a minor version so that our users learn about the upcoming changes and migrate their code in advance. Learn more about our commitment to stability and incremental migration in [our versioning policy](https://reactjs.org/docs/faq-versioning.html).
+
+Every significant change is documented in the [changelog file](https://github.com/facebook/react/blob/master/CHANGELOG.md).
+
+### Branch Organization {#branch-organization}
+
+Submit all changes directly to the [`master branch`](https://github.com/facebook/react/tree/master). We don't use separate branches for development or for upcoming releases. We do our best to keep `master` in good shape, with all tests passing.
+
+Code that lands in `master` must be compatible with the latest stable release. It may contain additional features, but no breaking changes. We should be able to release a new minor version from the tip of `master` at any time.
+
+### Feature Flags {#feature-flags}
+
+To keep the `master` branch in a releasable state, breaking changes and experimental features must be gated behind a feature flag.
+
+Feature flags are defined in [`packages/shared/ReactFeatureFlags.js`](https://github.com/facebook/react/blob/master/packages/shared/ReactFeatureFlags.js). Some builds of React may enable different sets of feature flags; for example, the React Native build may be configured differently than React DOM. These flags are found in [`packages/shared/forks`](https://github.com/facebook/react/tree/master/packages/shared/forks). Feature flags are statically typed by Flow, so you can run `yarn flow` to confirm that you've updated all the necessary files.
+
+React's build system will strip out disabled feature branches before publishing. A continuous integration job runs on every commit to check for changes in bundle size. You can use the change in size as a signal that a feature was gated correctly.
+
+### Bugs {#bugs}
+
+#### Where to Find Known Issues {#where-to-find-known-issues}
+
+We are using [GitHub Issues](https://github.com/facebook/react/issues) for our public bugs. We keep a close eye on this and try to make it clear when we have an internal fix in progress. Before filing a new task, try to make sure your problem doesn't already exist.
+
+#### Reporting New Issues {#reporting-new-issues}
+
+The best way to get your bug fixed is to provide a reduced test case. This [JSFiddle template](https://jsfiddle.net/Luktwrdm/) is a great starting point.
+
+#### Security Bugs {#security-bugs}
+
+Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page.
+
+### How to Get in Touch {#how-to-get-in-touch}
+
+* IRC: [#reactjs on freenode](https://webchat.freenode.net/?channels=reactjs)
+* [Discussion forums](https://reactjs.org/community/support.html#popular-discussion-forums)
+
+There is also [an active community of React users on the Discord chat platform](https://www.reactiflux.com/) in case you need help with React.
+
+### Proposing a Change {#proposing-a-change}
+
+If you intend to change the public API, or make any non-trivial changes to the implementation, we recommend [filing an issue](https://github.com/facebook/react/issues/new). This lets us reach an agreement on your proposal before you put significant effort into it.
+
+If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.
+
+### Your First Pull Request {#your-first-pull-request}
+
+Working on your first Pull Request? You can learn how from this free video series:
+
+**[How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)**
+
+To help you get your feet wet and get you familiar with our contribution process, we have a list of **[good first issues](https://github.com/facebook/react/issues?q=is:open+is:issue+label:"good+first+issue")** that contain bugs that have a relatively limited scope. This is a great place to get started.
+
+If you decide to fix an issue, please be sure to check the comment thread in case somebody is already working on a fix. If nobody is working on it at the moment, please leave a comment stating that you intend to work on it so other people don't accidentally duplicate your effort.
+
+If somebody claims an issue but doesn't follow up for more than two weeks, it's fine to take it over but you should still leave a comment.
+
+### Sending a Pull Request {#sending-a-pull-request}
+
+The core team is monitoring for pull requests. We will review your pull request and either merge it, request changes to it, or close it with an explanation. For API changes we may need to fix our internal uses at Facebook.com, which could cause some delay. We'll do our best to provide updates and feedback throughout the process.
+
+**Before submitting a pull request,** please make sure the following is done:
+
+1. Fork [the repository](https://github.com/facebook/react) and create your branch from `master`.
+2. Run `yarn` in the repository root.
+3. If you've fixed a bug or added code that should be tested, add tests!
+4. Ensure the test suite passes (`yarn test`). Tip: `yarn test --watch TestName` is helpful in development.
+5. Run `yarn test-prod` to test in the production environment. It supports the same options as `yarn test`.
+6. If you need a debugger, run `yarn debug-test --watch TestName`, open `chrome://inspect`, and press "Inspect".
+7. Format your code with [prettier](https://github.com/prettier/prettier) (`yarn prettier`).
+8. Make sure your code lints (`yarn lint`). Tip: `yarn linc` to only check changed files.
+9. Run the [Flow](https://flowtype.org/) typechecks (`yarn flow`).
+10. If you haven't already, complete the CLA.
+
+### Contributor License Agreement (CLA) {#contributor-license-agreement-cla}
+
+In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, just let us know that you have completed the CLA and we can cross-check with your GitHub username.
+
+**[Complete your CLA here.](https://code.facebook.com/cla)**
+
+### Contribution Prerequisites {#contribution-prerequisites}
+
+* You have [Node](https://nodejs.org) installed at v8.0.0+ and [Yarn](https://yarnpkg.com/en/) at v1.2.0+.
+* You have `gcc` installed or are comfortable installing a compiler if needed. Some of our 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 Git.
+
+### Development Workflow {#development-workflow}
+
+After cloning React, run `yarn` to fetch its dependencies.
+Then, you can run several commands:
+
+* `yarn lint` checks the code style.
+* `yarn linc` is like `yarn lint` but faster because it only checks files that differ in your branch.
+* `yarn test` runs the complete test suite.
+* `yarn test --watch` runs an interactive test watcher.
+* `yarn test <pattern>` runs tests with matching filenames.
+* `yarn test-prod` runs tests in the production environment. It supports all the same options as `yarn test`.
+* `yarn debug-test` is just like `yarn test` but with a debugger. Open `chrome://inspect` and press "Inspect".
+* `yarn flow` runs the [Flow](https://flowtype.org/) typechecks.
+* `yarn build` creates a `build` folder with all the packages.
+* `yarn build react/index,react-dom/index --type=UMD` creates UMD builds of just React and ReactDOM.
+
+We recommend running `yarn test` (or its variations above) to make sure you don't introduce any regressions as you work on your change. However it can be handy to try your build of React in a real project.
+
+First, run `yarn build`. This will produce pre-built bundles in `build` folder, as well as prepare npm packages inside `build/packages`.
+
+The easiest way to try your changes is to run `yarn build react/index,react-dom/index --type=UMD` and then open `fixtures/packaging/babel-standalone/dev.html`. This file already uses `react.development.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/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 `yarn link` to point them to your local `build` folder:
+
+```sh
+cd ~/path_to_your_react_clone/build/node_modules/react
+yarn link
+cd ~/path_to_your_react_clone/build/node_modules/react-dom
+yarn link
+cd /path/to/your/project
+yarn link react react-dom
+```
+
+Every time you run `yarn build` in the React folder, the updated versions will appear in your project's `node_modules`. You can then rebuild your project to try your changes.
+
+We still require that your pull request contains unit tests for any new functionality. This way we can ensure that we don't break your code in the future.
+
+### Style Guide {#style-guide}
+
+We use an automatic code formatter called [Prettier](https://prettier.io/).
+Run `yarn prettier` after making any changes to the code.
+
+Then, our linter will catch most issues that may exist in your code.
+You can check the status of your code styling by simply running `yarn linc`.
+
+However, there are still some styles that the linter cannot pick up. If you are unsure about something, looking at [Airbnb's Style Guide](https://github.com/airbnb/javascript) will guide you in the right direction.
+
+### Introductory Video {#introductory-video}
+
+You may be interested in watching [this short video](https://www.youtube.com/watch?v=wUpPsEcGsg8) (26 mins) which gives an introduction on how to contribute to React.
+
+#### Video highlights: {#video-highlights}
+- [4:12](https://youtu.be/wUpPsEcGsg8?t=4m12s) - Building and testing React locally
+- [6:07](https://youtu.be/wUpPsEcGsg8?t=6m7s) - Creating and sending pull requests
+- [8:25](https://youtu.be/wUpPsEcGsg8?t=8m25s) - Organizing code
+- [14:43](https://youtu.be/wUpPsEcGsg8?t=14m43s) - React npm registry
+- [19:15](https://youtu.be/wUpPsEcGsg8?t=19m15s) - Adding new React features
+
+For a realistic overview of what it _feels_ like to contribute to React for the first time, check out [this entertaining ReactNYC talk](https://www.youtube.com/watch?v=GWCcZ6fnpn4).
+
+### Request for Comments (RFC) {#request-for-comments-rfc}
+
+Many changes, including bug fixes and documentation improvements can be implemented and reviewed via the normal GitHub pull request workflow.
+
+Some changes though are "substantial", and we ask that these be put through a bit of a design process and produce a consensus among the React core team.
+
+The "RFC" (request for comments) process is intended to provide a consistent and controlled path for new features to enter the project. You can contribute by visiting the [rfcs repository](https://github.com/reactjs/rfcs).
+
+### License {#license}
+
+By contributing to React, you agree that your contributions will be licensed under its MIT license.
+
+### What Next? {#what-next}
+
+Read the [next section](/docs/codebase-overview.html) to learn how the codebase is organized.
diff --git a/implementation-notes.md b/implementation-notes.md
new file mode 100644
index 000000000..a035a5edf
--- /dev/null
+++ b/implementation-notes.md
@@ -0,0 +1,898 @@
+---
+id: implementation-notes
+title: Implementation Notes
+layout: contributing
+permalink: docs/implementation-notes.html
+prev: codebase-overview.html
+next: design-principles.html
+redirect_from:
+  - "contributing/implementation-notes.html"
+---
+
+This section is a collection of implementation notes for the [stack reconciler](/docs/codebase-overview.html#stack-reconciler).
+
+It is very technical and assumes a strong understanding of React public API as well as how it's divided into core, renderers, and the reconciler. If you're not very familiar with the React codebase, read [the codebase overview](/docs/codebase-overview.html) first.
+
+It also assumes an understanding of the [differences between React components, their instances, and elements](/blog/2015/12/18/react-components-elements-and-instances.html).
+
+The stack reconciler was used in React 15 and earlier. It is located at [src/renderers/shared/stack/reconciler](https://github.com/facebook/react/tree/15-stable/src/renderers/shared/stack/reconciler).
+
+### Video: Building React from Scratch {#video-building-react-from-scratch}
+
+[Paul O'Shannessy](https://twitter.com/zpao) gave a talk about [building React from scratch](https://www.youtube.com/watch?v=_MAD4Oly9yg) that largely inspired this document.
+
+Both this document and his talk are simplifications of the real codebase so you might get a better understanding by getting familiar with both of them.
+
+### Overview {#overview}
+
+The reconciler itself doesn't have a public API. [Renderers](/docs/codebase-overview.html#stack-renderers) like React DOM and React Native use it to efficiently update the user interface according to the React components written by the user.
+
+### Mounting as a Recursive Process {#mounting-as-a-recursive-process}
+
+Let's consider the first time you mount a component:
+
+```js
+ReactDOM.render(<App />, rootEl);
+```
+
+React DOM will pass `<App />` along to the reconciler. Remember that `<App />` is a React element, that is, a description of *what* to render. You can think about it as a plain object:
+
+```js
+console.log(<App />);
+// { type: App, props: {} }
+```
+
+The reconciler will check if `App` is a class or a function.
+
+If `App` is a function, the reconciler will call `App(props)` to get the rendered element.
+
+If `App` is a class, the reconciler will instantiate an `App` with `new App(props)`, call the `componentWillMount()` lifecycle method, and then will call the `render()` method to get the rendered element.
+
+Either way, the reconciler will learn the element `App` "rendered to".
+
+This process is recursive. `App` may render to a `<Greeting />`, `Greeting` may render to a `<Button />`, and so on. The reconciler will "drill down" through user-defined components recursively as it learns what each component renders to.
+
+You can imagine this process as a pseudocode:
+
+```js
+function isClass(type) {
+  // React.Component subclasses have this flag
+  return (
+    Boolean(type.prototype) &&
+    Boolean(type.prototype.isReactComponent)
+  );
+}
+
+// This function takes a React element (e.g. <App />)
+// and returns a DOM or Native node representing the mounted tree.
+function mount(element) {
+  var type = element.type;
+  var props = element.props;
+
+  // We will determine the rendered element
+  // by either running the type as function
+  // or creating an instance and calling render().
+  var renderedElement;
+  if (isClass(type)) {
+    // Component class
+    var publicInstance = new type(props);
+    // Set the props
+    publicInstance.props = props;
+    // Call the lifecycle if necessary
+    if (publicInstance.componentWillMount) {
+      publicInstance.componentWillMount();
+    }
+    // Get the rendered element by calling render()
+    renderedElement = publicInstance.render();
+  } else {
+    // Component function
+    renderedElement = type(props);
+  }
+
+  // This process is recursive because a component may
+  // return an element with a type of another component.
+  return mount(renderedElement);
+
+  // Note: this implementation is incomplete and recurses infinitely!
+  // It only handles elements like <App /> or <Button />.
+  // It doesn't handle elements like <div /> or <p /> yet.
+}
+
+var rootEl = document.getElementById('root');
+var node = mount(<App />);
+rootEl.appendChild(node);
+```
+
+>**Note:**
+>
+>This really *is* a pseudo-code. It isn't similar to the real implementation. It will also cause a stack overflow because we haven't discussed when to stop the recursion.
+
+Let's recap a few key ideas in the example above:
+
+* React elements are plain objects representing the component type (e.g. `App`) and the props.
+* User-defined components (e.g. `App`) can be classes or functions but they all "render to" elements.
+* "Mounting" is a recursive process that creates a DOM or Native tree given the top-level React element (e.g. `<App />`).
+
+### Mounting Host Elements {#mounting-host-elements}
+
+This process would be useless if we didn't render something to the screen as a result.
+
+In addition to user-defined ("composite") components, React elements may also represent platform-specific ("host") components. For example, `Button` might return a `<div />` from its render method.
+
+If element's `type` property is a string, we are dealing with a host element:
+
+```js
+console.log(<div />);
+// { type: 'div', props: {} }
+```
+
+There is no user-defined code associated with host elements.
+
+When the reconciler encounters a host element, it lets the renderer take care of mounting it. For example, React DOM would create a DOM node.
+
+If the host element has children, the reconciler recursively mounts them following the same algorithm as above. It doesn't matter whether children are host (like `<div><hr /></div>`), composite (like `<div><Button /></div>`), or both.
+
+The DOM nodes produced by the child components will be appended to the parent DOM node, and recursively, the complete DOM structure will be assembled.
+
+>**Note:**
+>
+>The reconciler itself is not tied to the DOM. The exact result of mounting (sometimes called "mount image" in the source code) depends on the renderer, and can be a DOM node (React DOM), a string (React DOM Server), or a number representing a native view (React Native).
+
+If we were to extend the code to handle host elements, it would look like this:
+
+```js
+function isClass(type) {
+  // React.Component subclasses have this flag
+  return (
+    Boolean(type.prototype) &&
+    Boolean(type.prototype.isReactComponent)
+  );
+}
+
+// This function only handles elements with a composite type.
+// For example, it handles <App /> and <Button />, but not a <div />.
+function mountComposite(element) {
+  var type = element.type;
+  var props = element.props;
+
+  var renderedElement;
+  if (isClass(type)) {
+    // Component class
+    var publicInstance = new type(props);
+    // Set the props
+    publicInstance.props = props;
+    // Call the lifecycle if necessary
+    if (publicInstance.componentWillMount) {
+      publicInstance.componentWillMount();
+    }
+    renderedElement = publicInstance.render();
+  } else if (typeof type === 'function') {
+    // Component function
+    renderedElement = type(props);
+  }
+
+  // This is recursive but we'll eventually reach the bottom of recursion when
+  // the element is host (e.g. <div />) rather than composite (e.g. <App />):
+  return mount(renderedElement);
+}
+
+// This function only handles elements with a host type.
+// For example, it handles <div /> and <p /> but not an <App />.
+function mountHost(element) {
+  var type = element.type;
+  var props = element.props;
+  var children = props.children || [];
+  if (!Array.isArray(children)) {
+    children = [children];
+  }
+  children = children.filter(Boolean);
+
+  // This block of code shouldn't be in the reconciler.
+  // Different renderers might initialize nodes differently.
+  // For example, React Native would create iOS or Android views.
+  var node = document.createElement(type);
+  Object.keys(props).forEach(propName => {
+    if (propName !== 'children') {
+      node.setAttribute(propName, props[propName]);
+    }
+  });
+
+  // Mount the children
+  children.forEach(childElement => {
+    // Children may be host (e.g. <div />) or composite (e.g. <Button />).
+    // We will also mount them recursively:
+    var childNode = mount(childElement);
+
+    // This line of code is also renderer-specific.
+    // It would be different depending on the renderer:
+    node.appendChild(childNode);
+  });
+
+  // Return the DOM node as mount result.
+  // This is where the recursion ends.
+  return node;
+}
+
+function mount(element) {
+  var type = element.type;
+  if (typeof type === 'function') {
+    // User-defined components
+    return mountComposite(element);
+  } else if (typeof type === 'string') {
+    // Platform-specific components
+    return mountHost(element);
+  }
+}
+
+var rootEl = document.getElementById('root');
+var node = mount(<App />);
+rootEl.appendChild(node);
+```
+
+This is working but still far from how the reconciler is really implemented. The key missing ingredient is support for updates.
+
+### Introducing Internal Instances {#introducing-internal-instances}
+
+The key feature of React is that you can re-render everything, and it won't recreate the DOM or reset the state:
+
+```js
+ReactDOM.render(<App />, rootEl);
+// Should reuse the existing DOM:
+ReactDOM.render(<App />, rootEl);
+```
+
+However, our implementation above only knows how to mount the initial tree. It can't perform updates on it because it doesn't store all the necessary information, such as all the `publicInstance`s, or which DOM `node`s correspond to which components.
+
+The stack reconciler codebase solves this by making the `mount()` function a method and putting it on a class. There are drawbacks to this approach, and we are going in the opposite direction in the [ongoing rewrite of the reconciler](/docs/codebase-overview.html#fiber-reconciler). Nevertheless this is how it works now.
+
+Instead of separate `mountHost` and `mountComposite` functions, we will create two classes: `DOMComponent` and `CompositeComponent`.
+
+Both classes have a constructor accepting the `element`, as well as a `mount()` method returning the mounted node. We will replace a top-level `mount()` function with a factory that instantiates the correct class:
+
+```js
+function instantiateComponent(element) {
+  var type = element.type;
+  if (typeof type === 'function') {
+    // User-defined components
+    return new CompositeComponent(element);
+  } else if (typeof type === 'string') {
+    // Platform-specific components
+    return new DOMComponent(element);
+  }  
+}
+```
+
+First, let's consider the implementation of `CompositeComponent`:
+
+```js
+class CompositeComponent {
+  constructor(element) {
+    this.currentElement = element;
+    this.renderedComponent = null;
+    this.publicInstance = null;
+  }
+
+  getPublicInstance() {
+    // For composite components, expose the class instance.
+    return this.publicInstance;
+  }
+
+  mount() {
+    var element = this.currentElement;
+    var type = element.type;
+    var props = element.props;
+
+    var publicInstance;
+    var renderedElement;
+    if (isClass(type)) {
+      // Component class
+      publicInstance = new type(props);
+      // Set the props
+      publicInstance.props = props;
+      // Call the lifecycle if necessary
+      if (publicInstance.componentWillMount) {
+        publicInstance.componentWillMount();
+      }
+      renderedElement = publicInstance.render();
+    } else if (typeof type === 'function') {
+      // Component function
+      publicInstance = null;
+      renderedElement = type(props);
+    }
+
+    // Save the public instance
+    this.publicInstance = publicInstance;
+
+    // Instantiate the child internal instance according to the element.
+    // It would be a DOMComponent for <div /> or <p />,
+    // and a CompositeComponent for <App /> or <Button />:
+    var renderedComponent = instantiateComponent(renderedElement);
+    this.renderedComponent = renderedComponent;
+
+    // Mount the rendered output
+    return renderedComponent.mount();
+  }
+}
+```
+
+This is not much different from our previous `mountComposite()` implementation, but now we can save some information, such as `this.currentElement`, `this.renderedComponent`, and `this.publicInstance`, for use during updates.
+
+Note that an instance of `CompositeComponent` is not the same thing as an instance of the user-supplied `element.type`. `CompositeComponent` is an implementation detail of our reconciler, and is never exposed to the user. The user-defined class is the one we read from `element.type`, and `CompositeComponent` creates an instance of it.
+
+To avoid the confusion, we will call instances of `CompositeComponent` and `DOMComponent` "internal instances". They exist so we can associate some long-lived data with them. Only the renderer and the reconciler are aware that they exist.
+
+In contrast, we call an instance of the user-defined class a "public instance". The public instance is what you see as `this` in the `render()` and other methods of your custom components.
+
+The `mountHost()` function, refactored to be a `mount()` method on `DOMComponent` class, also looks familiar:
+
+```js
+class DOMComponent {
+  constructor(element) {
+    this.currentElement = element;
+    this.renderedChildren = [];
+    this.node = null;
+  }
+
+  getPublicInstance() {
+    // For DOM components, only expose the DOM node.
+    return this.node;
+  }
+
+  mount() {
+    var element = this.currentElement;
+    var type = element.type;
+    var props = element.props;
+    var children = props.children || [];
+    if (!Array.isArray(children)) {
+      children = [children];
+    }
+
+    // Create and save the node
+    var node = document.createElement(type);
+    this.node = node;
+
+    // Set the attributes
+    Object.keys(props).forEach(propName => {
+      if (propName !== 'children') {
+        node.setAttribute(propName, props[propName]);
+      }
+    });
+
+    // Create and save the contained children.
+    // Each of them can be a DOMComponent or a CompositeComponent,
+    // depending on whether the element type is a string or a function.
+    var renderedChildren = children.map(instantiateComponent);
+    this.renderedChildren = renderedChildren;
+
+    // Collect DOM nodes they return on mount
+    var childNodes = renderedChildren.map(child => child.mount());
+    childNodes.forEach(childNode => node.appendChild(childNode));
+
+    // Return the DOM node as mount result
+    return node;
+  }
+}
+```
+
+The main difference after refactoring from `mountHost()` is that we now keep `this.node` and `this.renderedChildren` associated with the internal DOM component instance. We will also use them for applying non-destructive updates in the future.
+
+As a result, each internal instance, composite or host, now points to its child internal instances. To help visualize this, if a function `<App>` component renders a `<Button>` class component, and `Button` class renders a `<div>`, the internal instance tree would look like this:
+
+```js
+[object CompositeComponent] {
+  currentElement: <App />,
+  publicInstance: null,
+  renderedComponent: [object CompositeComponent] {
+    currentElement: <Button />,
+    publicInstance: [object Button],
+    renderedComponent: [object DOMComponent] {
+      currentElement: <div />,
+      node: [object HTMLDivElement],
+      renderedChildren: []
+    }
+  }
+}
+```
+
+In the DOM you would only see the `<div>`. However the internal instance tree contains both composite and host internal instances.
+
+The composite internal instances need to store:
+
+* The current element.
+* The public instance if element type is a class.
+* The single rendered internal instance. It can be either a `DOMComponent` or a `CompositeComponent`.
+
+The host internal instances need to store:
+
+* The current element.
+* The DOM node.
+* All the child internal instances. Each of them can be either a `DOMComponent` or a `CompositeComponent`.
+
+If you're struggling to imagine how an internal instance tree is structured in more complex applications, [React DevTools](https://github.com/facebook/react-devtools) can give you a close approximation, as it highlights host instances with grey, and composite instances with purple:
+
+ <img src="../images/docs/implementation-notes-tree.png" width="500" style="max-width: 100%" alt="React DevTools tree" />
+
+To complete this refactoring, we will introduce a function that mounts a complete tree into a container node, just like `ReactDOM.render()`. It returns a public instance, also like `ReactDOM.render()`:
+
+```js
+function mountTree(element, containerNode) {
+  // Create the top-level internal instance
+  var rootComponent = instantiateComponent(element);
+
+  // Mount the top-level component into the container
+  var node = rootComponent.mount();
+  containerNode.appendChild(node);
+
+  // Return the public instance it provides
+  var publicInstance = rootComponent.getPublicInstance();
+  return publicInstance;
+}
+
+var rootEl = document.getElementById('root');
+mountTree(<App />, rootEl);
+```
+
+### Unmounting {#unmounting}
+
+Now that we have internal instances that hold onto their children and the DOM nodes, we can implement unmounting. For a composite component, unmounting calls a lifecycle method and recurses.
+
+```js
+class CompositeComponent {
+
+  // ...
+
+  unmount() {
+    // Call the lifecycle method if necessary
+    var publicInstance = this.publicInstance;
+    if (publicInstance) {
+      if (publicInstance.componentWillUnmount) {
+        publicInstance.componentWillUnmount();
+      }
+    }
+
+    // Unmount the single rendered component
+    var renderedComponent = this.renderedComponent;
+    renderedComponent.unmount();
+  }
+}
+```
+
+For `DOMComponent`, unmounting tells each child to unmount:
+
+```js
+class DOMComponent {
+
+  // ...
+
+  unmount() {
+    // Unmount all the children
+    var renderedChildren = this.renderedChildren;
+    renderedChildren.forEach(child => child.unmount());
+  }
+}
+```
+
+In practice, unmounting DOM components also removes the event listeners and clears some caches, but we will skip those details.
+
+We can now add a new top-level function called `unmountTree(containerNode)` that is similar to `ReactDOM.unmountComponentAtNode()`:
+
+```js
+function unmountTree(containerNode) {
+  // Read the internal instance from a DOM node:
+  // (This doesn't work yet, we will need to change mountTree() to store it.)
+  var node = containerNode.firstChild;
+  var rootComponent = node._internalInstance;
+
+  // Unmount the tree and clear the container
+  rootComponent.unmount();
+  containerNode.innerHTML = '';
+}
+```
+
+In order for this to work, we need to read an internal root instance from a DOM node. We will modify `mountTree()` to add the `_internalInstance` property to the root DOM node. We will also teach `mountTree()` to destroy any existing tree so it can be called multiple times:
+
+```js
+function mountTree(element, containerNode) {
+  // Destroy any existing tree
+  if (containerNode.firstChild) {
+    unmountTree(containerNode);
+  }
+
+  // Create the top-level internal instance
+  var rootComponent = instantiateComponent(element);
+
+  // Mount the top-level component into the container
+  var node = rootComponent.mount();
+  containerNode.appendChild(node);
+
+  // Save a reference to the internal instance
+  node._internalInstance = rootComponent;
+
+  // Return the public instance it provides
+  var publicInstance = rootComponent.getPublicInstance();
+  return publicInstance;
+}
+```
+
+Now, running `unmountTree()`, or running `mountTree()` repeatedly, removes the old tree and runs the `componentWillUnmount()` lifecycle method on components.
+
+### Updating {#updating}
+
+In the previous section, we implemented unmounting. However React wouldn't be very useful if each prop change unmounted and mounted the whole tree. The goal of the reconciler is to reuse existing instances where possible to preserve the DOM and the state:
+
+```js
+var rootEl = document.getElementById('root');
+
+mountTree(<App />, rootEl);
+// Should reuse the existing DOM:
+mountTree(<App />, rootEl);
+```
+
+We will extend our internal instance contract with one more method. In addition to `mount()` and `unmount()`, both `DOMComponent` and `CompositeComponent` will implement a new method called `receive(nextElement)`:
+
+```js
+class CompositeComponent {
+  // ...
+
+  receive(nextElement) {
+    // ...
+  }
+}
+
+class DOMComponent {
+  // ...
+
+  receive(nextElement) {
+    // ...
+  }
+}
+```
+
+Its job is to do whatever is necessary to bring the component (and any of its children) up to date with the description provided by the `nextElement`.
+
+This is the part that is often described as "virtual DOM diffing" although what really happens is that we walk the internal tree recursively and let each internal instance receive an update.
+
+### Updating Composite Components {#updating-composite-components}
+
+When a composite component receives a new element, we run the `componentWillUpdate()` lifecycle method.
+
+Then we re-render the component with the new props, and get the next rendered element:
+
+```js
+class CompositeComponent {
+
+  // ...
+
+  receive(nextElement) {
+    var prevProps = this.currentElement.props;
+    var publicInstance = this.publicInstance;
+    var prevRenderedComponent = this.renderedComponent;
+    var prevRenderedElement = prevRenderedComponent.currentElement;
+
+    // Update *own* element
+    this.currentElement = nextElement;
+    var type = nextElement.type;
+    var nextProps = nextElement.props;
+
+    // Figure out what the next render() output is
+    var nextRenderedElement;
+    if (isClass(type)) {
+      // Component class
+      // Call the lifecycle if necessary
+      if (publicInstance.componentWillUpdate) {
+        publicInstance.componentWillUpdate(nextProps);
+      }
+      // Update the props
+      publicInstance.props = nextProps;
+      // Re-render
+      nextRenderedElement = publicInstance.render();
+    } else if (typeof type === 'function') {
+      // Component function
+      nextRenderedElement = type(nextProps);
+    }
+
+    // ...
+```
+
+Next, we can look at the rendered element's `type`. If the `type` has not changed since the last render, the component below can also be updated in place.
+
+For example, if it returned `<Button color="red" />` the first time, and `<Button color="blue" />` the second time, we can just tell the corresponding internal instance to `receive()` the next element:
+
+```js
+    // ...
+
+    // If the rendered element type has not changed,
+    // reuse the existing component instance and exit.
+    if (prevRenderedElement.type === nextRenderedElement.type) {
+      prevRenderedComponent.receive(nextRenderedElement);
+      return;
+    }
+
+    // ...
+```
+
+However, if the next rendered element has a different `type` than the previously rendered element, we can't update the internal instance. A `<button>` can't "become" an `<input>`.
+
+Instead, we have to unmount the existing internal instance and mount the new one corresponding to the rendered element type. For example, this is what happens when a component that previously rendered a `<button />` renders an `<input />`:
+
+```js
+    // ...
+
+    // If we reached this point, we need to unmount the previously
+    // mounted component, mount the new one, and swap their nodes.
+
+    // Find the old node because it will need to be replaced
+    var prevNode = prevRenderedComponent.getHostNode();
+
+    // Unmount the old child and mount a new child
+    prevRenderedComponent.unmount();
+    var nextRenderedComponent = instantiateComponent(nextRenderedElement);
+    var nextNode = nextRenderedComponent.mount();
+
+    // Replace the reference to the child
+    this.renderedComponent = nextRenderedComponent;
+
+    // Replace the old node with the new one
+    // Note: this is renderer-specific code and
+    // ideally should live outside of CompositeComponent:
+    prevNode.parentNode.replaceChild(nextNode, prevNode);
+  }
+}
+```
+
+To sum this up, when a composite component receives a new element, it may either delegate the update to its rendered internal instance, or unmount it and mount a new one in its place.
+
+There is another condition under which a component will re-mount rather than receive an element, and that is when the element's `key` has changed. We don't discuss `key` handling in this document because it adds more complexity to an already complex tutorial.
+
+Note that we needed to add a method called `getHostNode()` to the internal instance contract so that it's possible to locate the platform-specific node and replace it during the update. Its implementation is straightforward for both classes:
+
+```js
+class CompositeComponent {
+  // ...
+
+  getHostNode() {
+    // Ask the rendered component to provide it.
+    // This will recursively drill down any composites.
+    return this.renderedComponent.getHostNode();
+  }
+}
+
+class DOMComponent {
+  // ...
+
+  getHostNode() {
+    return this.node;
+  }  
+}
+```
+
+### Updating Host Components {#updating-host-components}
+
+Host component implementations, such as `DOMComponent`, update differently. When they receive an element, they need to update the underlying platform-specific view. In case of React DOM, this means updating the DOM attributes:
+
+```js
+class DOMComponent {
+  // ...
+
+  receive(nextElement) {
+    var node = this.node;
+    var prevElement = this.currentElement;
+    var prevProps = prevElement.props;
+    var nextProps = nextElement.props;    
+    this.currentElement = nextElement;
+
+    // Remove old attributes.
+    Object.keys(prevProps).forEach(propName => {
+      if (propName !== 'children' && !nextProps.hasOwnProperty(propName)) {
+        node.removeAttribute(propName);
+      }
+    });
+    // Set next attributes.
+    Object.keys(nextProps).forEach(propName => {
+      if (propName !== 'children') {
+        node.setAttribute(propName, nextProps[propName]);
+      }
+    });
+
+    // ...
+```
+
+Then, host components need to update their children. Unlike composite components, they might contain more than a single child.
+
+In this simplified example, we use an array of internal instances and iterate over it, either updating or replacing the internal instances depending on whether the received `type` matches their previous `type`. The real reconciler also takes element's `key` in the account and track moves in addition to insertions and deletions, but we will omit this logic.
+
+We collect DOM operations on children in a list so we can execute them in batch:
+
+```js
+    // ...
+
+    // These are arrays of React elements:
+    var prevChildren = prevProps.children || [];
+    if (!Array.isArray(prevChildren)) {
+      prevChildren = [prevChildren];
+    }
+    var nextChildren = nextProps.children || [];
+    if (!Array.isArray(nextChildren)) {
+      nextChildren = [nextChildren];
+    }
+    // These are arrays of internal instances:
+    var prevRenderedChildren = this.renderedChildren;
+    var nextRenderedChildren = [];
+
+    // As we iterate over children, we will add operations to the array.
+    var operationQueue = [];
+
+    // Note: the section below is extremely simplified!
+    // It doesn't handle reorders, children with holes, or keys.
+    // It only exists to illustrate the overall flow, not the specifics.
+
+    for (var i = 0; i < nextChildren.length; i++) {
+      // Try to get an existing internal instance for this child
+      var prevChild = prevRenderedChildren[i];
+
+      // If there is no internal instance under this index,
+      // a child has been appended to the end. Create a new
+      // internal instance, mount it, and use its node.
+      if (!prevChild) {
+        var nextChild = instantiateComponent(nextChildren[i]);
+        var node = nextChild.mount();
+
+        // Record that we need to append a node
+        operationQueue.push({type: 'ADD', node});
+        nextRenderedChildren.push(nextChild);
+        continue;
+      }
+
+      // We can only update the instance if its element's type matches.
+      // For example, <Button size="small" /> can be updated to
+      // <Button size="large" /> but not to an <App />.
+      var canUpdate = prevChildren[i].type === nextChildren[i].type;
+
+      // If we can't update an existing instance, we have to unmount it
+      // and mount a new one instead of it.
+      if (!canUpdate) {
+        var prevNode = prevChild.getHostNode();
+        prevChild.unmount();
+
+        var nextChild = instantiateComponent(nextChildren[i]);
+        var nextNode = nextChild.mount();
+
+        // Record that we need to swap the nodes
+        operationQueue.push({type: 'REPLACE', prevNode, nextNode});
+        nextRenderedChildren.push(nextChild);
+        continue;
+      }
+
+      // If we can update an existing internal instance,
+      // just let it receive the next element and handle its own update.
+      prevChild.receive(nextChildren[i]);
+      nextRenderedChildren.push(prevChild);
+    }
+
+    // Finally, unmount any children that don't exist:
+    for (var j = nextChildren.length; j < prevChildren.length; j++) {
+      var prevChild = prevRenderedChildren[j];
+      var node = prevChild.getHostNode();
+      prevChild.unmount();
+
+      // Record that we need to remove the node
+      operationQueue.push({type: 'REMOVE', node});
+    }
+
+    // Point the list of rendered children to the updated version.
+    this.renderedChildren = nextRenderedChildren;
+
+    // ...
+```
+
+As the last step, we execute the DOM operations. Again, the real reconciler code is more complex because it also handles moves:
+
+```js
+    // ...
+
+    // Process the operation queue.
+    while (operationQueue.length > 0) {
+      var operation = operationQueue.shift();
+      switch (operation.type) {
+      case 'ADD':
+        this.node.appendChild(operation.node);
+        break;
+      case 'REPLACE':
+        this.node.replaceChild(operation.nextNode, operation.prevNode);
+        break;
+      case 'REMOVE':
+        this.node.removeChild(operation.node);
+        break;
+      }
+    }
+  }
+}
+```
+
+And that is it for updating host components.
+
+### Top-Level Updates {#top-level-updates}
+
+Now that both `CompositeComponent` and `DOMComponent` implement the `receive(nextElement)` method, we can change the top-level `mountTree()` function to use it when the element `type` is the same as it was the last time:
+
+```js
+function mountTree(element, containerNode) {
+  // Check for an existing tree
+  if (containerNode.firstChild) {
+    var prevNode = containerNode.firstChild;
+    var prevRootComponent = prevNode._internalInstance;
+    var prevElement = prevRootComponent.currentElement;
+
+    // If we can, reuse the existing root component
+    if (prevElement.type === element.type) {
+      prevRootComponent.receive(element);
+      return;
+    }
+
+    // Otherwise, unmount the existing tree
+    unmountTree(containerNode);
+  }
+
+  // ...
+
+}
+```
+
+Now calling `mountTree()` two times with the same type isn't destructive:
+
+```js
+var rootEl = document.getElementById('root');
+
+mountTree(<App />, rootEl);
+// Reuses the existing DOM:
+mountTree(<App />, rootEl);
+```
+
+These are the basics of how React works internally.
+
+### What We Left Out {#what-we-left-out}
+
+This document is simplified compared to the real codebase. There are a few important aspects we didn't address:
+
+* Components can render `null`, and the reconciler can handle "empty slots" in arrays and rendered output.
+
+* The reconciler also reads `key` from the elements, and uses it to establish which internal instance corresponds to which element in an array. A bulk of complexity in the actual React implementation is related to that.
+
+* In addition to composite and host internal instance classes, there are also classes for "text" and "empty" components. They represent text nodes and the "empty slots" you get by rendering `null`.
+
+* Renderers use [injection](/docs/codebase-overview.html#dynamic-injection) to pass the host internal class to the reconciler. For example, React DOM tells the reconciler to use `ReactDOMComponent` as the host internal instance implementation.
+
+* The logic for updating the list of children is extracted into a mixin called `ReactMultiChild` which is used by the host internal instance class implementations both in React DOM and React Native.
+
+* The reconciler also implements support for `setState()` in composite components. Multiple updates inside event handlers get batched into a single update.
+
+* The reconciler also takes care of attaching and detaching refs to composite components and host nodes.
+
+* Lifecycle methods that are called after the DOM is ready, such as `componentDidMount()` and `componentDidUpdate()`, get collected into "callback queues" and are executed in a single batch.
+
+* React puts information about the current update into an internal object called "transaction". Transactions are useful for keeping track of the queue of pending lifecycle methods, the current DOM nesting for the warnings, and anything else that is "global" to a specific update. Transactions also ensure React "cleans everything up" after updates. For example, the transaction class provided by React DOM restores the input selection after any update.
+
+### Jumping into the Code {#jumping-into-the-code}
+
+* [`ReactMount`](https://github.com/facebook/react/blob/83381c1673d14cd16cf747e34c945291e5518a86/src/renderers/dom/client/ReactMount.js) is where the code like `mountTree()` and `unmountTree()` from this tutorial lives. It takes care of mounting and unmounting top-level components. [`ReactNativeMount`](https://github.com/facebook/react/blob/83381c1673d14cd16cf747e34c945291e5518a86/src/renderers/native/ReactNativeMount.js) is its React Native analog.
+* [`ReactDOMComponent`](https://github.com/facebook/react/blob/83381c1673d14cd16cf747e34c945291e5518a86/src/renderers/dom/shared/ReactDOMComponent.js) is the equivalent of `DOMComponent` in this tutorial. It implements the host component class for React DOM renderer. [`ReactNativeBaseComponent`](https://github.com/facebook/react/blob/83381c1673d14cd16cf747e34c945291e5518a86/src/renderers/native/ReactNativeBaseComponent.js) is its React Native analog.
+* [`ReactCompositeComponent`](https://github.com/facebook/react/blob/83381c1673d14cd16cf747e34c945291e5518a86/src/renderers/shared/stack/reconciler/ReactCompositeComponent.js) is the equivalent of `CompositeComponent` in this tutorial. It handles calling user-defined components and maintaining their state.
+* [`instantiateReactComponent`](https://github.com/facebook/react/blob/83381c1673d14cd16cf747e34c945291e5518a86/src/renderers/shared/stack/reconciler/instantiateReactComponent.js) contains the switch that picks the right internal instance class to construct for an element. It is equivalent to `instantiateComponent()` in this tutorial.
+
+* [`ReactReconciler`](https://github.com/facebook/react/blob/83381c1673d14cd16cf747e34c945291e5518a86/src/renderers/shared/stack/reconciler/ReactReconciler.js) is a wrapper with `mountComponent()`, `receiveComponent()`, and `unmountComponent()` methods. It calls the underlying implementations on the internal instances, but also includes some code around them that is shared by all internal instance implementations.
+
+* [`ReactChildReconciler`](https://github.com/facebook/react/blob/83381c1673d14cd16cf747e34c945291e5518a86/src/renderers/shared/stack/reconciler/ReactChildReconciler.js) implements the logic for mounting, updating, and unmounting children according to the `key` of their elements.
+
+* [`ReactMultiChild`](https://github.com/facebook/react/blob/83381c1673d14cd16cf747e34c945291e5518a86/src/renderers/shared/stack/reconciler/ReactMultiChild.js) implements processing the operation queue for child insertions, deletions, and moves independently of the renderer.
+
+* `mount()`, `receive()`, and `unmount()` are really called `mountComponent()`, `receiveComponent()`, and `unmountComponent()` in React codebase for legacy reasons, but they receive elements.
+
+* Properties on the internal instances start with an underscore, e.g. `_currentElement`. They are considered to be read-only public fields throughout the codebase.
+
+### Future Directions {#future-directions}
+
+Stack reconciler has inherent limitations such as being synchronous and unable to interrupt the work or split it in chunks. There is a work in progress on the [new Fiber reconciler](/docs/codebase-overview.html#fiber-reconciler) with a [completely different architecture](https://github.com/acdlite/react-fiber-architecture). In the future, we intend to replace stack reconciler with it, but at the moment it is far from feature parity.
+
+### Next Steps {#next-steps}
+
+Read the [next section](/docs/design-principles.html) to learn about the guiding principles we use for React development.
diff --git a/integrating-with-other-libraries.md b/integrating-with-other-libraries.md
new file mode 100644
index 000000000..5bc8b2570
--- /dev/null
+++ b/integrating-with-other-libraries.md
@@ -0,0 +1,439 @@
+---
+id: integrating-with-other-libraries
+title: Integrating with Other Libraries
+permalink: docs/integrating-with-other-libraries.html
+---
+
+React can be used in any web application. It can be embedded in other applications and, with a little care, other applications can be embedded in React. This guide will examine some of the more common use cases, focusing on integration with [jQuery](https://jquery.com/) and [Backbone](https://backbonejs.org/), but the same ideas can be applied to integrating components with any existing code.
+
+## Integrating with DOM Manipulation Plugins {#integrating-with-dom-manipulation-plugins}
+
+React is unaware of changes made to the DOM outside of React. It determines updates based on its own internal representation, and if the same DOM nodes are manipulated by another library, React gets confused and has no way to recover.
+
+This does not mean it is impossible or even necessarily difficult to combine React with other ways of affecting the DOM, you just have to be mindful of what each is doing.
+
+The easiest way to avoid conflicts is to prevent the React component from updating. You can do this by rendering elements that React has no reason to update, like an empty `<div />`.
+
+### How to Approach the Problem {#how-to-approach-the-problem}
+
+To demonstrate this, let's sketch out a wrapper for a generic jQuery plugin.
+
+We will attach a [ref](/docs/refs-and-the-dom.html) to the root DOM element. Inside `componentDidMount`, we will get a reference to it so we can pass it to the jQuery plugin.
+
+To prevent React from touching the DOM after mounting, we will return an empty `<div />` from the `render()` method. The `<div />` element has no properties or children, so React has no reason to update it, leaving the jQuery plugin free to manage that part of the DOM:
+
+```js{3,4,8,12}
+class SomePlugin extends React.Component {
+  componentDidMount() {
+    this.$el = $(this.el);
+    this.$el.somePlugin();
+  }
+
+  componentWillUnmount() {
+    this.$el.somePlugin('destroy');
+  }
+
+  render() {
+    return <div ref={el => this.el = el} />;
+  }
+}
+```
+
+Note that we defined both `componentDidMount` and `componentWillUnmount` [lifecycle methods](/docs/react-component.html#the-component-lifecycle). Many jQuery plugins attach event listeners to the DOM so it's important to detach them in `componentWillUnmount`. If the plugin does not provide a method for cleanup, you will probably have to provide your own, remembering to remove any event listeners the plugin registered to prevent memory leaks.
+
+### Integrating with jQuery Chosen Plugin {#integrating-with-jquery-chosen-plugin}
+
+For a more concrete example of these concepts, let's write a minimal wrapper for the plugin [Chosen](https://harvesthq.github.io/chosen/), which augments `<select>` inputs.
+
+>**Note:**
+>
+>Just because it's possible, doesn't mean that it's the best approach for React apps. We encourage you to use React components when you can. React components are easier to reuse in React applications, and often provide more control over their behavior and appearance.
+
+First, let's look at what Chosen does to the DOM.
+
+If you call it on a `<select>` DOM node, it reads the attributes off of the original DOM node, hides it with an inline style, and then appends a separate DOM node with its own visual representation right after the `<select>`. Then it fires jQuery events to notify us about the changes.
+
+Let's say that this is the API we're striving for with our `<Chosen>` wrapper React component:
+
+```js
+function Example() {
+  return (
+    <Chosen onChange={value => console.log(value)}>
+      <option>vanilla</option>
+      <option>chocolate</option>
+      <option>strawberry</option>
+    </Chosen>
+  );
+}
+```
+
+We will implement it as an [uncontrolled component](/docs/uncontrolled-components.html) for simplicity.
+
+First, we will create an empty component with a `render()` method where we return `<select>` wrapped in a `<div>`:
+
+```js{4,5}
+class Chosen extends React.Component {
+  render() {
+    return (
+      <div>
+        <select className="Chosen-select" ref={el => this.el = el}>
+          {this.props.children}
+        </select>
+      </div>
+    );
+  }
+}
+```
+
+Notice how we wrapped `<select>` in an extra `<div>`. This is necessary because Chosen will append another DOM element right after the `<select>` node we passed to it. However, as far as React is concerned, `<div>` always only has a single child. This is how we ensure that React updates won't conflict with the extra DOM node appended by Chosen. It is important that if you modify the DOM outside of React flow, you must ensure React doesn't have a reason to touch those DOM nodes.
+
+Next, we will implement the lifecycle methods. We need to initialize Chosen with the ref to the `<select>` node in `componentDidMount`, and tear it down in `componentWillUnmount`:
+
+```js{2,3,7}
+componentDidMount() {
+  this.$el = $(this.el);
+  this.$el.chosen();
+}
+
+componentWillUnmount() {
+  this.$el.chosen('destroy');
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/qmqeQx?editors=0010)
+
+Note that React assigns no special meaning to the `this.el` field. It only works because we have previously assigned this field from a `ref` in the `render()` method:
+
+```js
+<select className="Chosen-select" ref={el => this.el = el}>
+```
+
+This is enough to get our component to render, but we also want to be notified about the value changes. To do this, we will subscribe to the jQuery `change` event on the `<select>` managed by Chosen.
+
+We won't pass `this.props.onChange` directly to Chosen because component's props might change over time, and that includes event handlers. Instead, we will declare a `handleChange()` method that calls `this.props.onChange`, and subscribe it to the jQuery `change` event:
+
+```js{5,6,10,14-16}
+componentDidMount() {
+  this.$el = $(this.el);
+  this.$el.chosen();
+
+  this.handleChange = this.handleChange.bind(this);
+  this.$el.on('change', this.handleChange);
+}
+
+componentWillUnmount() {
+  this.$el.off('change', this.handleChange);
+  this.$el.chosen('destroy');
+}
+
+handleChange(e) {
+  this.props.onChange(e.target.value);
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/bWgbeE?editors=0010)
+
+Finally, there is one more thing left to do. In React, props can change over time. For example, the `<Chosen>` component can get different children if parent component's state changes. This means that at integration points it is important that we manually update the DOM in response to prop updates, since we no longer let React manage the DOM for us.
+
+Chosen's documentation suggests that we can use jQuery `trigger()` API to notify it about changes to the original DOM element. We will let React take care of updating `this.props.children` inside `<select>`, but we will also add a `componentDidUpdate()` lifecycle method that notifies Chosen about changes in the children list:
+
+```js{2,3}
+componentDidUpdate(prevProps) {
+  if (prevProps.children !== this.props.children) {
+    this.$el.trigger("chosen:updated");
+  }
+}
+```
+
+This way, Chosen will know to update its DOM element when the `<select>` children managed by React change.
+
+The complete implementation of the `Chosen` component looks like this:
+
+```js
+class Chosen extends React.Component {
+  componentDidMount() {
+    this.$el = $(this.el);
+    this.$el.chosen();
+
+    this.handleChange = this.handleChange.bind(this);
+    this.$el.on('change', this.handleChange);
+  }
+  
+  componentDidUpdate(prevProps) {
+    if (prevProps.children !== this.props.children) {
+      this.$el.trigger("chosen:updated");
+    }
+  }
+
+  componentWillUnmount() {
+    this.$el.off('change', this.handleChange);
+    this.$el.chosen('destroy');
+  }
+  
+  handleChange(e) {
+    this.props.onChange(e.target.value);
+  }
+
+  render() {
+    return (
+      <div>
+        <select className="Chosen-select" ref={el => this.el = el}>
+          {this.props.children}
+        </select>
+      </div>
+    );
+  }
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/xdgKOz?editors=0010)
+
+## Integrating with Other View Libraries {#integrating-with-other-view-libraries}
+
+React can be embedded into other applications thanks to the flexibility of [`ReactDOM.render()`](/docs/react-dom.html#render).
+
+Although React is commonly used at startup to load a single root React component into the DOM, `ReactDOM.render()` can also be called multiple times for independent parts of the UI which can be as small as a button, or as large as an app.
+
+In fact, this is exactly how React is used at Facebook. This lets us write applications in React piece by piece, and combine them with our existing server-generated templates and other client-side code.
+
+### Replacing String-Based Rendering with React {#replacing-string-based-rendering-with-react}
+
+A common pattern in older web applications is to describe chunks of the DOM as a string and insert it into the DOM like so: `$el.html(htmlString)`. These points in a codebase are perfect for introducing React. Just rewrite the string based rendering as a React component.
+
+So the following jQuery implementation...
+
+```js
+$('#container').html('<button id="btn">Say Hello</button>');
+$('#btn').click(function() {
+  alert('Hello!');
+});
+```
+
+...could be rewritten using a React component:
+
+```js
+function Button() {
+  return <button id="btn">Say Hello</button>;
+}
+
+ReactDOM.render(
+  <Button />,
+  document.getElementById('container'),
+  function() {
+    $('#btn').click(function() {
+      alert('Hello!');
+    });
+  }
+);
+```
+
+From here you could start moving more logic into the component and begin adopting more common React practices. For example, in components it is best not to rely on IDs because the same component can be rendered multiple times. Instead, we will use the [React event system](/docs/handling-events.html) and register the click handler directly on the React `<button>` element:
+
+```js{2,6,9}
+function Button(props) {
+  return <button onClick={props.onClick}>Say Hello</button>;
+}
+
+function HelloButton() {
+  function handleClick() {
+    alert('Hello!');
+  }
+  return <Button onClick={handleClick} />;
+}
+
+ReactDOM.render(
+  <HelloButton />,
+  document.getElementById('container')
+);
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/RVKbvW?editors=1010)
+
+You can have as many such isolated components as you like, and use `ReactDOM.render()` to render them to different DOM containers. Gradually, as you convert more of your app to React, you will be able to combine them into larger components, and move some of the `ReactDOM.render()` calls up the hierarchy.
+
+### Embedding React in a Backbone View {#embedding-react-in-a-backbone-view}
+
+[Backbone](https://backbonejs.org/) views typically use HTML strings, or string-producing template functions, to create the content for their DOM elements. This process, too, can be replaced with rendering a React component.
+
+Below, we will create a Backbone view called `ParagraphView`. It will override Backbone's `render()` function to render a React `<Paragraph>` component into the DOM element provided by Backbone (`this.el`). Here, too, we are using [`ReactDOM.render()`](/docs/react-dom.html#render):
+
+```js{1,5,8,12}
+function Paragraph(props) {
+  return <p>{props.text}</p>;
+}
+
+const ParagraphView = Backbone.View.extend({
+  render() {
+    const text = this.model.get('text');
+    ReactDOM.render(<Paragraph text={text} />, this.el);
+    return this;
+  },
+  remove() {
+    ReactDOM.unmountComponentAtNode(this.el);
+    Backbone.View.prototype.remove.call(this);
+  }
+});
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/gWgOYL?editors=0010)
+
+It is important that we also call `ReactDOM.unmountComponentAtNode()` in the `remove` method so that React unregisters event handlers and other resources associated with the component tree when it is detached.
+
+When a component is removed *from within* a React tree, the cleanup is performed automatically, but because we are removing the entire tree by hand, we must call this method.
+
+## Integrating with Model Layers {#integrating-with-model-layers}
+
+While it is generally recommended to use unidirectional data flow such as [React state](/docs/lifting-state-up.html), [Flux](https://facebook.github.io/flux/), or [Redux](https://redux.js.org/), React components can use a model layer from other frameworks and libraries.
+
+### Using Backbone Models in React Components {#using-backbone-models-in-react-components}
+
+The simplest way to consume [Backbone](https://backbonejs.org/) models and collections from a React component is to listen to the various change events and manually force an update.
+
+Components responsible for rendering models would listen to `'change'` events, while components responsible for rendering collections would listen for `'add'` and `'remove'` events. In both cases, call [`this.forceUpdate()`](/docs/react-component.html#forceupdate) to rerender the component with the new data.
+
+In the example below, the `List` component renders a Backbone collection, using the `Item` component to render individual items.
+
+```js{1,7-9,12,16,24,30-32,35,39,46}
+class Item extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleChange = this.handleChange.bind(this);
+  }
+
+  handleChange() {
+    this.forceUpdate();
+  }
+
+  componentDidMount() {
+    this.props.model.on('change', this.handleChange);
+  }
+
+  componentWillUnmount() {
+    this.props.model.off('change', this.handleChange);
+  }
+
+  render() {
+    return <li>{this.props.model.get('text')}</li>;
+  }
+}
+
+class List extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleChange = this.handleChange.bind(this);
+  }
+
+  handleChange() {
+    this.forceUpdate();
+  }
+
+  componentDidMount() {
+    this.props.collection.on('add', 'remove', this.handleChange);
+  }
+
+  componentWillUnmount() {
+    this.props.collection.off('add', 'remove', this.handleChange);
+  }
+
+  render() {
+    return (
+      <ul>
+        {this.props.collection.map(model => (
+          <Item key={model.cid} model={model} />
+        ))}
+      </ul>
+    );
+  }
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/GmrREm?editors=0010)
+
+### Extracting Data from Backbone Models {#extracting-data-from-backbone-models}
+
+The approach above requires your React components to be aware of the Backbone models and collections. If you later plan to migrate to another data management solution, you might want to concentrate the knowledge about Backbone in as few parts of the code as possible.
+
+One solution to this is to extract the model's attributes as plain data whenever it changes, and keep this logic in a single place. The following is [a higher-order component](/docs/higher-order-components.html) that extracts all attributes of a Backbone model into state, passing the data to the wrapped component.
+
+This way, only the higher-order component needs to know about Backbone model internals, and most components in the app can stay agnostic of Backbone.
+
+In the example below, we will make a copy of the model's attributes to form the initial state. We subscribe to the `change` event (and unsubscribe on unmounting), and when it happens, we update the state with the model's current attributes. Finally, we make sure that if the `model` prop itself changes, we don't forget to unsubscribe from the old model, and subscribe to the new one.
+
+Note that this example is not meant to be exhaustive with regards to working with Backbone, but it should give you an idea for how to approach this in a generic way:
+
+```js{1,5,10,14,16,17,22,26,32}
+function connectToBackboneModel(WrappedComponent) {
+  return class BackboneComponent extends React.Component {
+    constructor(props) {
+      super(props);
+      this.state = Object.assign({}, props.model.attributes);
+      this.handleChange = this.handleChange.bind(this);
+    }
+
+    componentDidMount() {
+      this.props.model.on('change', this.handleChange);
+    }
+
+    componentWillReceiveProps(nextProps) {
+      this.setState(Object.assign({}, nextProps.model.attributes));
+      if (nextProps.model !== this.props.model) {
+        this.props.model.off('change', this.handleChange);
+        nextProps.model.on('change', this.handleChange);
+      }
+    }
+
+    componentWillUnmount() {
+      this.props.model.off('change', this.handleChange);
+    }
+
+    handleChange(model) {
+      this.setState(model.changedAttributes());
+    }
+
+    render() {
+      const propsExceptModel = Object.assign({}, this.props);
+      delete propsExceptModel.model;
+      return <WrappedComponent {...propsExceptModel} {...this.state} />;
+    }
+  }
+}
+```
+
+To demonstrate how to use it, we will connect a `NameInput` React component to a Backbone model, and update its `firstName` attribute every time the input changes:
+
+```js{4,6,11,15,19-21}
+function NameInput(props) {
+  return (
+    <p>
+      <input value={props.firstName} onChange={props.handleChange} />
+      <br />
+      My name is {props.firstName}.
+    </p>
+  );
+}
+
+const BackboneNameInput = connectToBackboneModel(NameInput);
+
+function Example(props) {
+  function handleChange(e) {
+    props.model.set('firstName', e.target.value);
+  }
+
+  return (
+    <BackboneNameInput
+      model={props.model}
+      handleChange={handleChange}
+    />
+  );
+}
+
+const model = new Backbone.Model({ firstName: 'Frodo' });
+ReactDOM.render(
+  <Example model={model} />,
+  document.getElementById('root')
+);
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/PmWwwa?editors=0010)
+
+This technique is not limited to Backbone. You can use React with any model library by subscribing to its changes in the lifecycle methods and, optionally, copying the data into the local React state.
diff --git a/introducing-jsx.md b/introducing-jsx.md
new file mode 100644
index 000000000..1b059927a
--- /dev/null
+++ b/introducing-jsx.md
@@ -0,0 +1,184 @@
+---
+id: introducing-jsx
+title: Introducing JSX
+permalink: docs/introducing-jsx.html
+prev: hello-world.html
+next: rendering-elements.html
+---
+
+Consider this variable declaration:
+
+```js
+const element = <h1>Hello, world!</h1>;
+```
+
+This funny tag syntax is neither a string nor HTML.
+
+It is called JSX, and it is a syntax extension to JavaScript. We recommend using it with React to describe what the UI should look like. JSX may remind you of a template language, but it comes with the full power of JavaScript.
+
+JSX produces React "elements". We will explore rendering them to the DOM in the [next section](/docs/rendering-elements.html). Below, you can find the basics of JSX necessary to get you started.
+
+### Why JSX? {#why-jsx}
+
+React embraces the fact that rendering logic is inherently coupled with other UI logic: how events are handled, how the state changes over time, and how the data is prepared for display.
+
+Instead of artificially separating *technologies* by putting markup and logic in separate files, React [separates *concerns*](https://en.wikipedia.org/wiki/Separation_of_concerns) with loosely coupled units called "components" that contain both. We will come back to components in a [further section](/docs/components-and-props.html), but if you're not yet comfortable putting markup in JS, [this talk](https://www.youtube.com/watch?v=x7cQ3mrcKaY) might convince you otherwise.
+
+React [doesn't require](/docs/react-without-jsx.html) using JSX, but most people find it helpful as a visual aid when working with UI inside the JavaScript code. It also allows React to show more useful error and warning messages.
+
+With that out of the way, let's get started!
+
+### Embedding Expressions in JSX {#embedding-expressions-in-jsx}
+
+In the example below, we declare a variable called `name` and then use it inside JSX by wrapping it in curly braces:
+
+```js{1,2}
+const name = 'Josh Perez';
+const element = <h1>Hello, {name}</h1>;
+
+ReactDOM.render(
+  element,
+  document.getElementById('root')
+);
+```
+
+You can put any valid [JavaScript expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators#Expressions) inside the curly braces in JSX. For example, `2 + 2`, `user.firstName`, or `formatName(user)` are all valid JavaScript expressions.
+
+In the example below, we embed the result of calling a JavaScript function, `formatName(user)`, into an `<h1>` element.
+
+```js{12}
+function formatName(user) {
+  return user.firstName + ' ' + user.lastName;
+}
+
+const user = {
+  firstName: 'Harper',
+  lastName: 'Perez'
+};
+
+const element = (
+  <h1>
+    Hello, {formatName(user)}!
+  </h1>
+);
+
+ReactDOM.render(
+  element,
+  document.getElementById('root')
+);
+```
+
+[](codepen://introducing-jsx)
+
+We split JSX over multiple lines for readability. While it isn't required, when doing this, we also recommend wrapping it in parentheses to avoid the pitfalls of [automatic semicolon insertion](https://stackoverflow.com/q/2846283).
+
+### JSX is an Expression Too {#jsx-is-an-expression-too}
+
+After compilation, JSX expressions become regular JavaScript function calls and evaluate to JavaScript objects.
+
+This means that you can use JSX inside of `if` statements and `for` loops, assign it to variables, accept it as arguments, and return it from functions:
+
+```js{3,5}
+function getGreeting(user) {
+  if (user) {
+    return <h1>Hello, {formatName(user)}!</h1>;
+  }
+  return <h1>Hello, Stranger.</h1>;
+}
+```
+
+### Specifying Attributes with JSX {#specifying-attributes-with-jsx}
+
+You may use quotes to specify string literals as attributes:
+
+```js
+const element = <div tabIndex="0"></div>;
+```
+
+You may also use curly braces to embed a JavaScript expression in an attribute:
+
+```js
+const element = <img src={user.avatarUrl}></img>;
+```
+
+Don't put quotes around curly braces when embedding a JavaScript expression in an attribute. You should either use quotes (for string values) or curly braces (for expressions), but not both in the same attribute.
+
+>**Warning:**
+>
+>Since JSX is closer to JavaScript than to HTML, React DOM uses `camelCase` property naming convention instead of HTML attribute names.
+>
+>For example, `class` becomes [`className`](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) in JSX, and `tabindex` becomes [`tabIndex`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/tabIndex).
+
+### Specifying Children with JSX {#specifying-children-with-jsx}
+
+If a tag is empty, you may close it immediately with `/>`, like XML:
+
+```js
+const element = <img src={user.avatarUrl} />;
+```
+
+JSX tags may contain children:
+
+```js
+const element = (
+  <div>
+    <h1>Hello!</h1>
+    <h2>Good to see you here.</h2>
+  </div>
+);
+```
+
+### JSX Prevents Injection Attacks {#jsx-prevents-injection-attacks}
+
+It is safe to embed user input in JSX:
+
+```js
+const title = response.potentiallyMaliciousInput;
+// This is safe:
+const element = <h1>{title}</h1>;
+```
+
+By default, React DOM [escapes](https://stackoverflow.com/questions/7381974/which-characters-need-to-be-escaped-on-html) any values embedded in JSX before rendering them. Thus it ensures that you can never inject anything that's not explicitly written in your application. Everything is converted to a string before being rendered. This helps prevent [XSS (cross-site-scripting)](https://en.wikipedia.org/wiki/Cross-site_scripting) attacks.
+
+### JSX Represents Objects {#jsx-represents-objects}
+
+Babel compiles JSX down to `React.createElement()` calls.
+
+These two examples are identical:
+
+```js
+const element = (
+  <h1 className="greeting">
+    Hello, world!
+  </h1>
+);
+```
+
+```js
+const element = React.createElement(
+  'h1',
+  {className: 'greeting'},
+  'Hello, world!'
+);
+```
+
+`React.createElement()` performs a few checks to help you write bug-free code but essentially it creates an object like this:
+
+```js
+// Note: this structure is simplified
+const element = {
+  type: 'h1',
+  props: {
+    className: 'greeting',
+    children: 'Hello, world!'
+  }
+};
+```
+
+These objects are called "React elements". You can think of them as descriptions of what you want to see on the screen. React reads these objects and uses them to construct the DOM and keep it up to date.
+
+We will explore rendering React elements to the DOM in the next section.
+
+>**Tip:**
+>
+>We recommend using the ["Babel" language definition](https://babeljs.io/docs/editors) for your editor of choice so that both ES6 and JSX code is properly highlighted. This website uses the [Oceanic Next](https://labs.voronianski.com/oceanic-next-color-scheme/) color scheme which is compatible with it.
diff --git a/jsx-in-depth.md b/jsx-in-depth.md
new file mode 100644
index 000000000..eb3dc3a5b
--- /dev/null
+++ b/jsx-in-depth.md
@@ -0,0 +1,461 @@
+---
+id: jsx-in-depth
+title: JSX In Depth
+permalink: docs/jsx-in-depth.html
+redirect_from:
+  - "docs/jsx-spread.html"
+  - "docs/jsx-gotchas.html"
+  - "tips/if-else-in-JSX.html"
+  - "tips/self-closing-tag.html"
+  - "tips/maximum-number-of-jsx-root-nodes.html"
+  - "tips/children-props-type.html"
+  - "docs/jsx-in-depth-zh-CN.html"
+  - "docs/jsx-in-depth-ko-KR.html"
+---
+
+Fundamentally, JSX just provides syntactic sugar for the `React.createElement(component, props, ...children)` function. The JSX code:
+
+```js
+<MyButton color="blue" shadowSize={2}>
+  Click Me
+</MyButton>
+```
+
+compiles into:
+
+```js
+React.createElement(
+  MyButton,
+  {color: 'blue', shadowSize: 2},
+  'Click Me'
+)
+```
+
+You can also use the self-closing form of the tag if there are no children. So:
+
+```js
+<div className="sidebar" />
+```
+
+compiles into:
+
+```js
+React.createElement(
+  'div',
+  {className: 'sidebar'},
+  null
+)
+```
+
+If you want to test out how some specific JSX is converted into JavaScript, you can try out [the online Babel compiler](babel://jsx-simple-example).
+
+## Specifying The React Element Type {#specifying-the-react-element-type}
+
+The first part of a JSX tag determines the type of the React element.
+
+Capitalized types indicate that the JSX tag is referring to a React component. These tags get compiled into a direct reference to the named variable, so if you use the JSX `<Foo />` expression, `Foo` must be in scope.
+
+### React Must Be in Scope {#react-must-be-in-scope}
+
+Since JSX compiles into calls to `React.createElement`, the `React` library must also always be in scope from your JSX code.
+
+For example, both of the imports are necessary in this code, even though `React` and `CustomButton` are not directly referenced from JavaScript:
+
+```js{1,2,5}
+import React from 'react';
+import CustomButton from './CustomButton';
+
+function WarningButton() {
+  // return React.createElement(CustomButton, {color: 'red'}, null);
+  return <CustomButton color="red" />;
+}
+```
+
+If you don't use a JavaScript bundler and loaded React from a `<script>` tag, it is already in scope as the `React` global.
+
+### Using Dot Notation for JSX Type {#using-dot-notation-for-jsx-type}
+
+You can also refer to a React component using dot-notation from within JSX. This is convenient if you have a single module that exports many React components. For example, if `MyComponents.DatePicker` is a component, you can use it directly from JSX with:
+
+```js{10}
+import React from 'react';
+
+const MyComponents = {
+  DatePicker: function DatePicker(props) {
+    return <div>Imagine a {props.color} datepicker here.</div>;
+  }
+}
+
+function BlueDatePicker() {
+  return <MyComponents.DatePicker color="blue" />;
+}
+```
+
+### User-Defined Components Must Be Capitalized {#user-defined-components-must-be-capitalized}
+
+When an element type starts with a lowercase letter, it refers to a built-in component like `<div>` or `<span>` and results in a string `'div'` or `'span'` passed to `React.createElement`. Types that start with a capital letter like `<Foo />` compile to `React.createElement(Foo)` and correspond to a component defined or imported in your JavaScript file.
+
+We recommend naming components with a capital letter. If you do have a component that starts with a lowercase letter, assign it to a capitalized variable before using it in JSX.
+
+For example, this code will not run as expected:
+
+```js{3,4,10,11}
+import React from 'react';
+
+// Wrong! This is a component and should have been capitalized:
+function hello(props) {
+  // Correct! This use of <div> is legitimate because div is a valid HTML tag:
+  return <div>Hello {props.toWhat}</div>;
+}
+
+function HelloWorld() {
+  // Wrong! React thinks <hello /> is an HTML tag because it's not capitalized:
+  return <hello toWhat="World" />;
+}
+```
+
+To fix this, we will rename `hello` to `Hello` and use `<Hello />` when referring to it:
+
+```js{3,4,10,11}
+import React from 'react';
+
+// Correct! This is a component and should be capitalized:
+function Hello(props) {
+  // Correct! This use of <div> is legitimate because div is a valid HTML tag:
+  return <div>Hello {props.toWhat}</div>;
+}
+
+function HelloWorld() {
+  // Correct! React knows <Hello /> is a component because it's capitalized.
+  return <Hello toWhat="World" />;
+}
+```
+
+### Choosing the Type at Runtime {#choosing-the-type-at-runtime}
+
+You cannot use a general expression as the React element type. If you do want to use a general expression to indicate the type of the element, just assign it to a capitalized variable first. This often comes up when you want to render a different component based on a prop:
+
+```js{10,11}
+import React from 'react';
+import { PhotoStory, VideoStory } from './stories';
+
+const components = {
+  photo: PhotoStory,
+  video: VideoStory
+};
+
+function Story(props) {
+  // Wrong! JSX type can't be an expression.
+  return <components[props.storyType] story={props.story} />;
+}
+```
+
+To fix this, we will assign the type to a capitalized variable first:
+
+```js{10-12}
+import React from 'react';
+import { PhotoStory, VideoStory } from './stories';
+
+const components = {
+  photo: PhotoStory,
+  video: VideoStory
+};
+
+function Story(props) {
+  // Correct! JSX type can be a capitalized variable.
+  const SpecificStory = components[props.storyType];
+  return <SpecificStory story={props.story} />;
+}
+```
+
+## Props in JSX {#props-in-jsx}
+
+There are several different ways to specify props in JSX.
+
+### JavaScript Expressions as Props {#javascript-expressions-as-props}
+
+You can pass any JavaScript expression as a prop, by surrounding it with `{}`. For example, in this JSX:
+
+```js
+<MyComponent foo={1 + 2 + 3 + 4} />
+```
+
+For `MyComponent`, the value of `props.foo` will be `10` because the expression `1 + 2 + 3 + 4` gets evaluated.
+
+`if` statements and `for` loops are not expressions in JavaScript, so they can't be used in JSX directly. Instead, you can put these in the surrounding code. For example:
+
+```js{3-7}
+function NumberDescriber(props) {
+  let description;
+  if (props.number % 2 == 0) {
+    description = <strong>even</strong>;
+  } else {
+    description = <i>odd</i>;
+  }
+  return <div>{props.number} is an {description} number</div>;
+}
+```
+
+You can learn more about [conditional rendering](/docs/conditional-rendering.html) and [loops](/docs/lists-and-keys.html) in the corresponding sections.
+
+### String Literals {#string-literals}
+
+You can pass a string literal as a prop. These two JSX expressions are equivalent:
+
+```js
+<MyComponent message="hello world" />
+
+<MyComponent message={'hello world'} />
+```
+
+When you pass a string literal, its value is HTML-unescaped. So these two JSX expressions are equivalent:
+
+```js
+<MyComponent message="&lt;3" />
+
+<MyComponent message={'<3'} />
+```
+
+This behavior is usually not relevant. It's only mentioned here for completeness.
+
+### Props Default to "True" {#props-default-to-true}
+
+If you pass no value for a prop, it defaults to `true`. These two JSX expressions are equivalent:
+
+```js
+<MyTextBox autocomplete />
+
+<MyTextBox autocomplete={true} />
+```
+
+In general, we don't recommend using this because it can be confused with the [ES6 object shorthand](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Operators/Object_initializer#New_notations_in_ECMAScript_2015) `{foo}` which is short for `{foo: foo}` rather than `{foo: true}`. This behavior is just there so that it matches the behavior of HTML.
+
+### Spread Attributes {#spread-attributes}
+
+If you already have `props` as an object, and you want to pass it in JSX, you can use `...` as a "spread" operator to pass the whole props object. These two components are equivalent:
+
+```js{7}
+function App1() {
+  return <Greeting firstName="Ben" lastName="Hector" />;
+}
+
+function App2() {
+  const props = {firstName: 'Ben', lastName: 'Hector'};
+  return <Greeting {...props} />;
+}
+```
+
+You can also pick specific props that your component will consume while passing all other props using the spread operator.
+
+```js{2}
+const Button = props => {
+  const { kind, ...other } = props;
+  const className = kind === "primary" ? "PrimaryButton" : "SecondaryButton";
+  return <button className={className} {...other} />;
+};
+
+const App = () => {
+  return (
+    <div>
+      <Button kind="primary" onClick={() => console.log("clicked!")}>
+        Hello World!
+      </Button>
+    </div>
+  );
+};
+```
+
+In the example above, the `kind` prop is safely consumed and *is not* passed on to the `<button>` element in the DOM.
+All other props are passed via the `...other` object making this component really flexible. You can see that it passes an `onClick` and `children` props.
+
+Spread attributes can be useful but they also make it easy to pass unnecessary props to components that don't care about them or to pass invalid HTML attributes to the DOM. We recommend using this syntax sparingly.  
+
+## Children in JSX {#children-in-jsx}
+
+In JSX expressions that contain both an opening tag and a closing tag, the content between those tags is passed as a special prop: `props.children`. There are several different ways to pass children:
+
+### String Literals {#string-literals-1}
+
+You can put a string between the opening and closing tags and `props.children` will just be that string. This is useful for many of the built-in HTML elements. For example:
+
+```js
+<MyComponent>Hello world!</MyComponent>
+```
+
+This is valid JSX, and `props.children` in `MyComponent` will simply be the string `"Hello world!"`. HTML is unescaped, so you can generally write JSX just like you would write HTML in this way:
+
+```html
+<div>This is valid HTML &amp; JSX at the same time.</div>
+```
+
+JSX removes whitespace at the beginning and ending of a line. It also removes blank lines. New lines adjacent to tags are removed; new lines that occur in the middle of string literals are condensed into a single space. So these all render to the same thing:
+
+```js
+<div>Hello World</div>
+
+<div>
+  Hello World
+</div>
+
+<div>
+  Hello
+  World
+</div>
+
+<div>
+
+  Hello World
+</div>
+```
+
+### JSX Children {#jsx-children}
+
+You can provide more JSX elements as the children. This is useful for displaying nested components:
+
+```js
+<MyContainer>
+  <MyFirstComponent />
+  <MySecondComponent />
+</MyContainer>
+```
+
+You can mix together different types of children, so you can use string literals together with JSX children. This is another way in which JSX is like HTML, so that this is both valid JSX and valid HTML:
+
+```html
+<div>
+  Here is a list:
+  <ul>
+    <li>Item 1</li>
+    <li>Item 2</li>
+  </ul>
+</div>
+```
+
+A React component can also return an array of elements:
+
+```js
+render() {
+  // No need to wrap list items in an extra element!
+  return [
+    // Don't forget the keys :)
+    <li key="A">First item</li>,
+    <li key="B">Second item</li>,
+    <li key="C">Third item</li>,
+  ];
+}
+```
+
+### JavaScript Expressions as Children {#javascript-expressions-as-children}
+
+You can pass any JavaScript expression as children, by enclosing it within `{}`. For example, these expressions are equivalent:
+
+```js
+<MyComponent>foo</MyComponent>
+
+<MyComponent>{'foo'}</MyComponent>
+```
+
+This is often useful for rendering a list of JSX expressions of arbitrary length. For example, this renders an HTML list:
+
+```js{2,9}
+function Item(props) {
+  return <li>{props.message}</li>;
+}
+
+function TodoList() {
+  const todos = ['finish doc', 'submit pr', 'nag dan to review'];
+  return (
+    <ul>
+      {todos.map((message) => <Item key={message} message={message} />)}
+    </ul>
+  );
+}
+```
+
+JavaScript expressions can be mixed with other types of children. This is often useful in lieu of string templates:
+
+```js{2}
+function Hello(props) {
+  return <div>Hello {props.addressee}!</div>;
+}
+```
+
+### Functions as Children {#functions-as-children}
+
+Normally, JavaScript expressions inserted in JSX will evaluate to a string, a React element, or a list of those things. However, `props.children` works just like any other prop in that it can pass any sort of data, not just the sorts that React knows how to render. For example, if you have a custom component, you could have it take a callback as `props.children`:
+
+```js{4,13}
+// Calls the children callback numTimes to produce a repeated component
+function Repeat(props) {
+  let items = [];
+  for (let i = 0; i < props.numTimes; i++) {
+    items.push(props.children(i));
+  }
+  return <div>{items}</div>;
+}
+
+function ListOfTenThings() {
+  return (
+    <Repeat numTimes={10}>
+      {(index) => <div key={index}>This is item {index} in the list</div>}
+    </Repeat>
+  );
+}
+```
+
+Children passed to a custom component can be anything, as long as that component transforms them into something React can understand before rendering. This usage is not common, but it works if you want to stretch what JSX is capable of.
+
+### Booleans, Null, and Undefined Are Ignored {#booleans-null-and-undefined-are-ignored}
+
+`false`, `null`, `undefined`, and `true` are valid children. They simply don't render. These JSX expressions will all render to the same thing:
+
+```js
+<div />
+
+<div></div>
+
+<div>{false}</div>
+
+<div>{null}</div>
+
+<div>{undefined}</div>
+
+<div>{true}</div>
+```
+
+This can be useful to conditionally render React elements. This JSX renders the `<Header />` component only if `showHeader` is `true`:
+
+```js{2}
+<div>
+  {showHeader && <Header />}
+  <Content />
+</div>
+```
+
+One caveat is that some ["falsy" values](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), such as the `0` number, are still rendered by React. For example, this code will not behave as you might expect because `0` will be printed when `props.messages` is an empty array:
+
+```js{2}
+<div>
+  {props.messages.length &&
+    <MessageList messages={props.messages} />
+  }
+</div>
+```
+
+To fix this, make sure that the expression before `&&` is always boolean:
+
+```js{2}
+<div>
+  {props.messages.length > 0 &&
+    <MessageList messages={props.messages} />
+  }
+</div>
+```
+
+Conversely, if you want a value like `false`, `true`, `null`, or `undefined` to appear in the output, you have to [convert it to a string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#String_conversion) first:
+
+```js{2}
+<div>
+  My JavaScript variable is {String(myVariable)}.
+</div>
+```
diff --git a/legacy-context.md b/legacy-context.md
new file mode 100644
index 000000000..a17137fd8
--- /dev/null
+++ b/legacy-context.md
@@ -0,0 +1,217 @@
+---
+id: legacy-context
+title: Legacy Context
+permalink: docs/legacy-context.html
+---
+
+> Note:
+>
+> The legacy context API will be removed in a future major version.
+> Use the [new context API](/docs/context.html) introduced with version 16.3.
+> The legacy API will continue working for all 16.x releases.
+
+## How To Use Context {#how-to-use-context}
+
+> This section documents a legacy API. See the [new API](/docs/context.html).
+
+Suppose you have a structure like:
+
+```javascript
+class Button extends React.Component {
+  render() {
+    return (
+      <button style={{background: this.props.color}}>
+        {this.props.children}
+      </button>
+    );
+  }
+}
+
+class Message extends React.Component {
+  render() {
+    return (
+      <div>
+        {this.props.text} <Button color={this.props.color}>Delete</Button>
+      </div>
+    );
+  }
+}
+
+class MessageList extends React.Component {
+  render() {
+    const color = "purple";
+    const children = this.props.messages.map((message) =>
+      <Message text={message.text} color={color} />
+    );
+    return <div>{children}</div>;
+  }
+}
+```
+
+In this example, we manually thread through a `color` prop in order to style the `Button` and `Message` components appropriately. Using context, we can pass this through the tree automatically:
+
+```javascript{6,13-15,21,28-30,40-42}
+import PropTypes from 'prop-types';
+
+class Button extends React.Component {
+  render() {
+    return (
+      <button style={{background: this.context.color}}>
+        {this.props.children}
+      </button>
+    );
+  }
+}
+
+Button.contextTypes = {
+  color: PropTypes.string
+};
+
+class Message extends React.Component {
+  render() {
+    return (
+      <div>
+        {this.props.text} <Button>Delete</Button>
+      </div>
+    );
+  }
+}
+
+class MessageList extends React.Component {
+  getChildContext() {
+    return {color: "purple"};
+  }
+
+  render() {
+    const children = this.props.messages.map((message) =>
+      <Message text={message.text} />
+    );
+    return <div>{children}</div>;
+  }
+}
+
+MessageList.childContextTypes = {
+  color: PropTypes.string
+};
+```
+
+By adding `childContextTypes` and `getChildContext` to `MessageList` (the context provider), React passes the information down automatically and any component in the subtree (in this case, `Button`) can access it by defining `contextTypes`.
+
+If `contextTypes` is not defined, then `context` will be an empty object.
+
+> Note:
+>
+> `React.PropTypes` has moved into a different package since React v15.5. Please use [the `prop-types` library instead](https://www.npmjs.com/package/prop-types) to define `contextTypes`.
+>
+> We provide [a codemod script](/blog/2017/04/07/react-v15.5.0.html#migrating-from-react.proptypes) to automate the conversion.
+
+### Parent-Child Coupling {#parent-child-coupling}
+
+> This section documents a legacy API. See the [new API](/docs/context.html).
+
+Context can also let you build an API where parents and children communicate. For example, one library that works this way is [React Router V4](https://reacttraining.com/react-router):
+
+```javascript
+import { BrowserRouter as Router, Route, Link } from 'react-router-dom';
+
+const BasicExample = () => (
+  <Router>
+    <div>
+      <ul>
+        <li><Link to="/">Home</Link></li>
+        <li><Link to="/about">About</Link></li>
+        <li><Link to="/topics">Topics</Link></li>
+      </ul>
+
+      <hr />
+
+      <Route exact path="/" component={Home} />
+      <Route path="/about" component={About} />
+      <Route path="/topics" component={Topics} />
+    </div>
+  </Router>
+);
+```
+
+By passing down some information from the `Router` component, each `Link` and `Route` can communicate back to the containing `Router`.
+
+Before you build components with an API similar to this, consider if there are cleaner alternatives. For example, you can pass entire React components as props if you'd like to.
+
+### Referencing Context in Lifecycle Methods {#referencing-context-in-lifecycle-methods}
+
+> This section documents a legacy API. See the [new API](/docs/context.html).
+
+If `contextTypes` is defined within a component, the following [lifecycle methods](/docs/react-component.html#the-component-lifecycle) will receive an additional parameter, the `context` object:
+
+- [`constructor(props, context)`](/docs/react-component.html#constructor)
+- [`componentWillReceiveProps(nextProps, nextContext)`](/docs/react-component.html#componentwillreceiveprops)
+- [`shouldComponentUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#shouldcomponentupdate)
+- [`componentWillUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#componentwillupdate)
+
+> Note:
+>
+> As of React 16, `componentDidUpdate` no longer receives `prevContext`.
+
+### Referencing Context in Function Components {#referencing-context-in-stateless-function-components}
+
+> This section documents a legacy API. See the [new API](/docs/context.html).
+
+Function components are also able to reference `context` if `contextTypes` is defined as a property of the function. The following code shows a `Button` component written as a function component.
+
+```javascript
+import PropTypes from 'prop-types';
+
+const Button = ({children}, context) =>
+  <button style={{background: context.color}}>
+    {children}
+  </button>;
+
+Button.contextTypes = {color: PropTypes.string};
+```
+
+### Updating Context {#updating-context}
+
+> This section documents a legacy API. See the [new API](/docs/context.html).
+
+Don't do it.
+
+React has an API to update context, but it is fundamentally broken and you should not use it.
+
+The `getChildContext` function will be called when the state or props changes. In order to update data in the context, trigger a local state update with `this.setState`. This will trigger a new context and changes will be received by the children.
+
+```javascript
+import PropTypes from 'prop-types';
+
+class MediaQuery extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {type:'desktop'};
+  }
+
+  getChildContext() {
+    return {type: this.state.type};
+  }
+
+  componentDidMount() {
+    const checkMediaQuery = () => {
+      const type = window.matchMedia("(min-width: 1025px)").matches ? 'desktop' : 'mobile';
+      if (type !== this.state.type) {
+        this.setState({type});
+      }
+    };
+
+    window.addEventListener('resize', checkMediaQuery);
+    checkMediaQuery();
+  }
+
+  render() {
+    return this.props.children;
+  }
+}
+
+MediaQuery.childContextTypes = {
+  type: PropTypes.string
+};
+```
+
+The problem is, if a context value provided by component changes, descendants that use that value won't update if an intermediate parent returns `false` from `shouldComponentUpdate`. This is totally out of control of the components using context, so there's basically no way to reliably update the context. [This blog post](https://medium.com/@mweststrate/how-to-safely-use-react-context-b7e343eff076) has a good explanation of why this is a problem and how you might get around it.
diff --git a/lifting-state-up.md b/lifting-state-up.md
new file mode 100644
index 000000000..c01c5eab2
--- /dev/null
+++ b/lifting-state-up.md
@@ -0,0 +1,330 @@
+---
+id: lifting-state-up
+title: Lifting State Up
+permalink: docs/lifting-state-up.html
+prev: forms.html
+next: composition-vs-inheritance.html
+redirect_from:
+  - "docs/flux-overview.html"
+  - "docs/flux-todo-list.html"
+---
+
+Often, several components need to reflect the same changing data. We recommend lifting the shared state up to their closest common ancestor. Let's see how this works in action.
+
+In this section, we will create a temperature calculator that calculates whether the water would boil at a given temperature.
+
+We will start with a component called `BoilingVerdict`. It accepts the `celsius` temperature as a prop, and prints whether it is enough to boil the water:
+
+```js{3,5}
+function BoilingVerdict(props) {
+  if (props.celsius >= 100) {
+    return <p>The water would boil.</p>;
+  }
+  return <p>The water would not boil.</p>;
+}
+```
+
+Next, we will create a component called `Calculator`. It renders an `<input>` that lets you enter the temperature, and keeps its value in `this.state.temperature`.
+
+Additionally, it renders the `BoilingVerdict` for the current input value.
+
+```js{5,9,13,17-21}
+class Calculator extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleChange = this.handleChange.bind(this);
+    this.state = {temperature: ''};
+  }
+
+  handleChange(e) {
+    this.setState({temperature: e.target.value});
+  }
+
+  render() {
+    const temperature = this.state.temperature;
+    return (
+      <fieldset>
+        <legend>Enter temperature in Celsius:</legend>
+        <input
+          value={temperature}
+          onChange={this.handleChange} />
+        <BoilingVerdict
+          celsius={parseFloat(temperature)} />
+      </fieldset>
+    );
+  }
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/ZXeOBm?editors=0010)
+
+## Adding a Second Input {#adding-a-second-input}
+
+Our new requirement is that, in addition to a Celsius input, we provide a Fahrenheit input, and they are kept in sync.
+
+We can start by extracting a `TemperatureInput` component from `Calculator`. We will add a new `scale` prop to it that can either be `"c"` or `"f"`:
+
+```js{1-4,19,22}
+const scaleNames = {
+  c: 'Celsius',
+  f: 'Fahrenheit'
+};
+
+class TemperatureInput extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleChange = this.handleChange.bind(this);
+    this.state = {temperature: ''};
+  }
+
+  handleChange(e) {
+    this.setState({temperature: e.target.value});
+  }
+
+  render() {
+    const temperature = this.state.temperature;
+    const scale = this.props.scale;
+    return (
+      <fieldset>
+        <legend>Enter temperature in {scaleNames[scale]}:</legend>
+        <input value={temperature}
+               onChange={this.handleChange} />
+      </fieldset>
+    );
+  }
+}
+```
+
+We can now change the `Calculator` to render two separate temperature inputs:
+
+```js{5,6}
+class Calculator extends React.Component {
+  render() {
+    return (
+      <div>
+        <TemperatureInput scale="c" />
+        <TemperatureInput scale="f" />
+      </div>
+    );
+  }
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/jGBryx?editors=0010)
+
+We have two inputs now, but when you enter the temperature in one of them, the other doesn't update. This contradicts our requirement: we want to keep them in sync.
+
+We also can't display the `BoilingVerdict` from `Calculator`. The `Calculator` doesn't know the current temperature because it is hidden inside the `TemperatureInput`.
+
+## Writing Conversion Functions {#writing-conversion-functions}
+
+First, we will write two functions to convert from Celsius to Fahrenheit and back:
+
+```js
+function toCelsius(fahrenheit) {
+  return (fahrenheit - 32) * 5 / 9;
+}
+
+function toFahrenheit(celsius) {
+  return (celsius * 9 / 5) + 32;
+}
+```
+
+These two functions convert numbers. We will write another function that takes a string `temperature` and a converter function as arguments and returns a string. We will use it to calculate the value of one input based on the other input.
+
+It returns an empty string on an invalid `temperature`, and it keeps the output rounded to the third decimal place:
+
+```js
+function tryConvert(temperature, convert) {
+  const input = parseFloat(temperature);
+  if (Number.isNaN(input)) {
+    return '';
+  }
+  const output = convert(input);
+  const rounded = Math.round(output * 1000) / 1000;
+  return rounded.toString();
+}
+```
+
+For example, `tryConvert('abc', toCelsius)` returns an empty string, and `tryConvert('10.22', toFahrenheit)` returns `'50.396'`.
+
+## Lifting State Up {#lifting-state-up}
+
+Currently, both `TemperatureInput` components independently keep their values in the local state:
+
+```js{5,9,13}
+class TemperatureInput extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleChange = this.handleChange.bind(this);
+    this.state = {temperature: ''};
+  }
+
+  handleChange(e) {
+    this.setState({temperature: e.target.value});
+  }
+
+  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.
+
+In React, sharing state is accomplished by moving it up to the closest common ancestor of the components that need it. This is called "lifting state up". We will remove the local state from the `TemperatureInput` and move it into the `Calculator` instead.
+
+If the `Calculator` owns the shared state, it becomes the "source of truth" for the current temperature in both inputs. It can instruct them both to have values that are consistent with each other. Since the props of both `TemperatureInput` components are coming from the same parent `Calculator` component, the two inputs will always be in sync.
+
+Let's see how this works step by step.
+
+First, we will replace `this.state.temperature` with `this.props.temperature` in the `TemperatureInput` component. For now, let's pretend `this.props.temperature` already exists, although we will need to pass it from the `Calculator` in the future:
+
+```js{3}
+  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.
+
+In React, this is usually solved by making a component "controlled". Just like the DOM `<input>` accepts both a `value` and an `onChange` prop, so can the custom `TemperatureInput` accept both `temperature` and `onTemperatureChange` props from its parent `Calculator`.
+
+Now, when the `TemperatureInput` wants to update its temperature, it calls `this.props.onTemperatureChange`:
+
+```js{3}
+  handleChange(e) {
+    // Before: this.setState({temperature: e.target.value});
+    this.props.onTemperatureChange(e.target.value);
+    // ...
+```
+
+>Note:
+>
+>There is no special meaning to either `temperature` or `onTemperatureChange` prop names in custom components. We could have called them anything else, like name them `value` and `onChange` which is a common convention.
+
+The `onTemperatureChange` prop will be provided together with the `temperature` prop by the parent `Calculator` component. It will handle the change by modifying its own local state, thus re-rendering both inputs with the new values. We will look at the new `Calculator` implementation very soon.
+
+Before diving into the changes in the `Calculator`, let's recap our changes to the `TemperatureInput` component. We have removed the local state from it, and instead of reading `this.state.temperature`, we now read `this.props.temperature`. Instead of calling `this.setState()` when we want to make a change, we now call `this.props.onTemperatureChange()`, which will be provided by the `Calculator`:
+
+```js{8,12}
+class TemperatureInput extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleChange = this.handleChange.bind(this);
+  }
+
+  handleChange(e) {
+    this.props.onTemperatureChange(e.target.value);
+  }
+
+  render() {
+    const temperature = this.props.temperature;
+    const scale = this.props.scale;
+    return (
+      <fieldset>
+        <legend>Enter temperature in {scaleNames[scale]}:</legend>
+        <input value={temperature}
+               onChange={this.handleChange} />
+      </fieldset>
+    );
+  }
+}
+```
+
+Now let's turn to the `Calculator` component.
+
+We will store the current input's `temperature` and `scale` in its local state. This is the state we "lifted up" from the inputs, and it will serve as the "source of truth" for both of them. It is the minimal representation of all the data we need to know in order to render both inputs.
+
+For example, if we enter 37 into the Celsius input, the state of the `Calculator` component will be:
+
+```js
+{
+  temperature: '37',
+  scale: 'c'
+}
+```
+
+If we later edit the Fahrenheit field to be 212, the state of the `Calculator` will be:
+
+```js
+{
+  temperature: '212',
+  scale: 'f'
+}
+```
+
+We could have stored the value of both inputs but it turns out to be unnecessary. It is enough to store the value of the most recently changed input, and the scale that it represents. We can then infer the value of the other input based on the current `temperature` and `scale` alone.
+
+The inputs stay in sync because their values are computed from the same state:
+
+```js{6,10,14,18-21,27-28,31-32,34}
+class Calculator extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleCelsiusChange = this.handleCelsiusChange.bind(this);
+    this.handleFahrenheitChange = this.handleFahrenheitChange.bind(this);
+    this.state = {temperature: '', scale: 'c'};
+  }
+
+  handleCelsiusChange(temperature) {
+    this.setState({scale: 'c', temperature});
+  }
+
+  handleFahrenheitChange(temperature) {
+    this.setState({scale: 'f', temperature});
+  }
+
+  render() {
+    const scale = this.state.scale;
+    const temperature = this.state.temperature;
+    const celsius = scale === 'f' ? tryConvert(temperature, toCelsius) : temperature;
+    const fahrenheit = scale === 'c' ? tryConvert(temperature, toFahrenheit) : temperature;
+
+    return (
+      <div>
+        <TemperatureInput
+          scale="c"
+          temperature={celsius}
+          onTemperatureChange={this.handleCelsiusChange} />
+        <TemperatureInput
+          scale="f"
+          temperature={fahrenheit}
+          onTemperatureChange={this.handleFahrenheitChange} />
+        <BoilingVerdict
+          celsius={parseFloat(celsius)} />
+      </div>
+    );
+  }
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/WZpxpz?editors=0010)
+
+Now, no matter which input you edit, `this.state.temperature` and `this.state.scale` in the `Calculator` get updated. One of the inputs gets the value as is, so any user input is preserved, and the other input value is always recalculated based on it.
+
+Let's recap what happens when you edit an input:
+
+* React calls the function specified as `onChange` on the DOM `<input>`. In our case, this is the `handleChange` method in the `TemperatureInput` component.
+* The `handleChange` method in the `TemperatureInput` component calls `this.props.onTemperatureChange()` with the new desired value. Its props, including `onTemperatureChange`, were provided by its parent component, the `Calculator`.
+* When it previously rendered, the `Calculator` has specified that `onTemperatureChange` of the Celsius `TemperatureInput` is the `Calculator`'s `handleCelsiusChange` method, and `onTemperatureChange` of the Fahrenheit `TemperatureInput` is the `Calculator`'s `handleFahrenheitChange` method. So either of these two `Calculator` methods gets called depending on which input we edited.
+* Inside these methods, the `Calculator` component asks React to re-render itself by calling `this.setState()` with the new input value and the current scale of the input we just edited.
+* React calls the `Calculator` component's `render` method to learn what the UI should look like. The values of both inputs are recomputed based on the current temperature and the active scale. The temperature conversion is performed here.
+* React calls the `render` methods of the individual `TemperatureInput` components with their new props specified by the `Calculator`. It learns what their UI should look like.
+* React calls the `render` method of the `BoilingVerdict` component, passing the temperature in Celsius as its props.
+* React DOM updates the DOM with the boiling verdict and to match the desired input values. The input we just edited receives its current value, and the other input is updated to the temperature after conversion.
+
+Every update goes through the same steps so the inputs stay in sync.
+
+## Lessons Learned {#lessons-learned}
+
+There should be a single "source of truth" for any data that changes in a React application. Usually, the state is first added to the component that needs it for rendering. Then, if other components also need it, you can lift it up to their closest common ancestor. Instead of trying to sync the state between different components, you should rely on the [top-down data flow](/docs/state-and-lifecycle.html#the-data-flows-down).
+
+Lifting state involves writing more "boilerplate" code than two-way binding approaches, but as a benefit, it takes less work to find and isolate bugs. Since any state "lives" in some component and that component alone can change it, the surface area for bugs is greatly reduced. Additionally, you can implement any custom logic to reject or transform user input.
+
+If something can be derived from either props or state, it probably shouldn't be in the state. For example, instead of storing both `celsiusValue` and `fahrenheitValue`, we store just the last edited `temperature` and its `scale`. The value of the other input can always be calculated from them in the `render()` method. This lets us clear or apply rounding to the other field without losing any precision in the user input.
+
+When you see something wrong in the UI, you can use [React Developer Tools](https://github.com/facebook/react/tree/master/packages/react-devtools) to inspect the props and move up the tree until you find the component responsible for updating the state. This lets you trace the bugs to their source:
+
+<img src="../images/docs/react-devtools-state.gif" alt="Monitoring State in React DevTools" max-width="100%" height="100%">
+
diff --git a/lists-and-keys.md b/lists-and-keys.md
new file mode 100644
index 000000000..448ef64ac
--- /dev/null
+++ b/lists-and-keys.md
@@ -0,0 +1,301 @@
+---
+id: lists-and-keys
+title: Lists and Keys
+permalink: docs/lists-and-keys.html
+prev: conditional-rendering.html
+next: forms.html
+---
+
+पहले, आइए समीक्षा करें कि आप जावास्क्रिप्ट में लिस्ट्स को कैसे बदलते हैं।
+
+नीचे दिए गए कोड में हम `numbers` की एक array के मूल्यों को दोगुना करने के लिए [`map()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) फ़ंक्शन का उपयोग करते हैं। हम `map()` द्वारा दिए गए नए array को `doubled` नाम के वेरिएबल को सौपते हैं और फिर लॉग करते हैं।
+
+```javascript{2}
+const numbers = [1, 2, 3, 4, 5];
+const doubled = numbers.map((number) => number * 2);
+console.log(doubled);
+```
+
+यह कोड [2, 4, 6, 8, 10] को कंसोल में लोग करता है।
+
+React में, array को [एलिमेंट्स](/docs/rendering-elements.html) की लिस्ट में बदलना लगभग समान है।
+
+### कई कौम्पोनॅन्टस को रेंडर करना {#rendering-multiple-components}
+
+आप एलिमेंट्स का संग्रह बना सकते हैं और कर्ली ब्रेसिज़ `{}` का उपयोग करके [उन्हें JSX में शामिल कर सकते हैं।](/docs/introducing-jsx.html#embedding-expressions-in-jsx)
+
+हमने जावास्क्रिप्ट [`map()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) फंक्शन का उपयोग करके `numbers` नाम की array में लूप लगाया है। हमने प्रत्येक आइटम के लिए `<li>` एलिमेंट को रिटर्न किया है। अंत में, हम परिणामस्वरूप आयी हुई एलिमेंट्स की array को `listItems` को सौपते है:
+
+```javascript{2-4}
+const numbers = [1, 2, 3, 4, 5];
+const listItems = numbers.map((number) =>
+  <li>{number}</li>
+);
+```
+
+हम पुरे `listItems` array को `<ul>` एलिमेंट में शामिल करके इसे [DOM में रेंडर करते हैं](/docs/rendering-elements.html#rendering-an-element-into-the-dom):
+
+```javascript{2}
+ReactDOM.render(
+  <ul>{listItems}</ul>,
+  document.getElementById('root')
+);
+```
+
+[**इसे CodePen पर आज़माएँ**](https://codepen.io/gaearon/pen/GjPyQr?editors=0011)
+
+यह कोड 1 से 5 के बीच संख्याओं की एक बुलेट लिस्ट प्रदर्शित करता है।
+
+### मूल लिस्टस कौम्पोनॅन्ट {#basic-list-component}
+
+आमतौर पर आप एक [कौम्पोनॅन्ट](/docs/components-and-props.html) के अंदर लिस्ट रेंडर करते हैं। 
+
+हम पिछले उदाहरण को एक कौम्पोनॅन्ट में बदल सकते हैं जो `numbers` की एक array को स्वीकार करता है और एलिमेंटस की लिस्ट को आउटपुट करता है।
+
+```javascript{3-5,7,13}
+function NumberList(props) {
+  const numbers = props.numbers;
+  const listItems = numbers.map((number) =>
+    <li>{number}</li>
+  );
+  return (
+    <ul>{listItems}</ul>
+  );
+}
+
+const numbers = [1, 2, 3, 4, 5];
+ReactDOM.render(
+  <NumberList numbers={numbers} />,
+  document.getElementById('root')
+);
+```
+
+जब आप यह कोड चलाते हैं, तो आपको एक चेतावनी दी जाती है कि लिस्ट आइटम के लिए एक key प्रदान की जानी चाहिए। "key" एक विशेष स्ट्रिंग एट्रिब्यूट है जिसे आपको एलिमेंटस की सूची बनाते समय शामिल करने की आवश्यकता होती है। हम अगले भाग में चर्चा करेंगे कि यह महत्वपूर्ण क्यों है।
+
+आइए `numbers.map()` के अंदर हमारी लिस्ट आइटम को एक `key`असाइन करें और लापता key की समस्या को ठीक करें।
+
+```javascript{4}
+function NumberList(props) {
+  const numbers = props.numbers;
+  const listItems = numbers.map((number) =>
+    <li key={number.toString()}>
+      {number}
+    </li>
+  );
+  return (
+    <ul>{listItems}</ul>
+  );
+}
+
+const numbers = [1, 2, 3, 4, 5];
+ReactDOM.render(
+  <NumberList numbers={numbers} />,
+  document.getElementById('root')
+);
+```
+
+[**इसे CodePen पर आज़माएँ**](https://codepen.io/gaearon/pen/jrXYRR?editors=0011)
+
+## Keys {#keys}
+
+Keys React को पहचानने में मदद करती हैं कि कौन से आइटम ऐड किये गए हैं, या हटा दिए गए हैं। एलिमेंट्स को स्टेबल करने के लिए array के अंदर एलिमेंट्स को key दी जानी चाहिए:
+
+```js{3}
+const numbers = [1, 2, 3, 4, 5];
+const listItems = numbers.map((number) =>
+  <li key={number.toString()}>
+    {number}
+  </li>
+);
+```
+
+Key चुनने का सबसे अच्छा तरीका एक string का उपयोग करना है जो विशिष्ट रूप से अपने सिब्लिंग्स के बीच एक लिस्ट आइटम की पहचान करता है। अक्सर आप अपने डेटा की IDs को key के रूप में उपयोग करेंगे:
+
+```js{2}
+const todoItems = todos.map((todo) =>
+  <li key={todo.id}>
+    {todo.text}
+  </li>
+);
+```
+
+जब आपके पास प्रदान की गई वस्तुओं के लिए स्थिर ID नहीं है, तो आप अंतिम उपाय के रूप में आइटम इंडेक्स का key के रूप में उपयोग कर सकते हैं:
+
+```js{2,3}
+const todoItems = todos.map((todo, index) =>
+  // Only do this if items have no stable IDs
+  <li key={index}>
+    {todo.text}
+  </li>
+);
+```
+
+यदि आइटम का क्रम बदल सकता है तो हम key के लिए इंडेक्स का उपयोग ना करने की सिफारिश करते हैं। इसका नकारात्मक प्रभाव पड़ सकता हैं और यह कौम्पोनॅन्ट की अवस्था के साथ समस्या भी पैदा कर सकता है। अधिक जानकारी के लिए Robin Pokorny के [इंडेक्स को key के रूप में उपयोग करने के नकारात्मक प्रभाव](https://medium.com/@robinpokorny/index-as-a-key-is-an-anti-pattern-e0349aece318) के आर्टिकल को देखें। यदि आप लिस्ट आइटम्स को एक स्पष्ट key नहीं देते हैं, तो React key के रूप में इंडेक्स का उपयोग करता है।
+
+यदि आप अधिक सीखने में रुचि रखते हैं, तो यहाँ [key की आवशयकताओ के बारे में गहराई से स्पष्टीकरणं](/docs/reconciliation.html#recursing-on-children) दिया गया हैं।
+
+### Key के साथ कौम्पोनॅन्टस निकालना {#extracting-components-with-keys}
+
+Keys केवल आस-पास के array के संदर्भ में ही समझ में आती हैं।
+
+उदाहरण के लिए, यदि आप एक ListItem कौम्पोनॅन्ट को [निकालते](/docs/components-and-props.html#extracting-components) हैं, तो आपको key `ListItem` के `<li>` एलिमेंट पर रखने के बजाये array में `<ListItem />` एलिमेंट पर रखनी चाहिए। 
+
+**उदाहरण: key का गलत उपयोग**
+
+```javascript{4,5,14,15}
+function ListItem(props) {
+  const value = props.value;
+  return (
+    // Wrong! There is no need to specify the key here:
+    <li key={value.toString()}>
+      {value}
+    </li>
+  );
+}
+
+function NumberList(props) {
+  const numbers = props.numbers;
+  const listItems = numbers.map((number) =>
+    // Wrong! The key should have been specified here:
+    <ListItem value={number} />
+  );
+  return (
+    <ul>
+      {listItems}
+    </ul>
+  );
+}
+
+const numbers = [1, 2, 3, 4, 5];
+ReactDOM.render(
+  <NumberList numbers={numbers} />,
+  document.getElementById('root')
+);
+```
+
+**उदाहरण: key का सही उपयोग**
+
+```javascript{2,3,9,10}
+function ListItem(props) {
+  // Correct! There is no need to specify the key here:
+  return <li>{props.value}</li>;
+}
+
+function NumberList(props) {
+  const numbers = props.numbers;
+  const listItems = numbers.map((number) =>
+    // Correct! Key should be specified inside the array.
+    <ListItem key={number.toString()}
+              value={number} />
+  );
+  return (
+    <ul>
+      {listItems}
+    </ul>
+  );
+}
+
+const numbers = [1, 2, 3, 4, 5];
+ReactDOM.render(
+  <NumberList numbers={numbers} />,
+  document.getElementById('root')
+);
+```
+
+[**इसे CodePen पर आज़माएँ**](https://codepen.io/gaearon/pen/ZXeOGM?editors=0010)
+
+एक अच्छा नियम यह है `map()` कॉल के एलिमेंट्स को key की आवशयकता होती हैं ।  
+
+### Keys सिर्फ़ सिब्लिंग्स के बीच अद्वितीय होनी चाहिए {#keys-must-only-be-unique-among-siblings}
+
+Arrays के भीतर उपयोग की जाने वाली key उनके सिब्लिंग्स के बीच अद्वितीय होनी चाहिए। हालाँकि उन्हें पूरी तरह से अद्वितीय होने की आवश्यकता नहीं है। हम अलग-अलग arrays के लिए सामान keys का उपयोग कर सकते हैं:
+
+```js{2,5,11,12,19,21}
+function Blog(props) {
+  const sidebar = (
+    <ul>
+      {props.posts.map((post) =>
+        <li key={post.id}>
+          {post.title}
+        </li>
+      )}
+    </ul>
+  );
+  const content = props.posts.map((post) =>
+    <div key={post.id}>
+      <h3>{post.title}</h3>
+      <p>{post.content}</p>
+    </div>
+  );
+  return (
+    <div>
+      {sidebar}
+      <hr />
+      {content}
+    </div>
+  );
+}
+
+const posts = [
+  {id: 1, title: 'Hello World', content: 'Welcome to learning React!'},
+  {id: 2, title: 'Installation', content: 'You can install React from npm.'}
+];
+ReactDOM.render(
+  <Blog posts={posts} />,
+  document.getElementById('root')
+);
+```
+
+[**इसे CodePen पर आज़माएँ**](https://codepen.io/gaearon/pen/NRZYGN?editors=0010)
+
+Keys React के लिए संकेत के रूप में काम करती हैं लेेकिन वह आपके कौम्पोनॅन्टस को नहीं दी जाती हैं। यदि आपको अपने कौम्पोनॅन्ट में समान वैल्यू की आवश्यकता है, तो इसे अलग नाम के साथ स्पष्ट रूप से prop की तरह पास करें:
+
+```js{3,4}
+const content = posts.map((post) =>
+  <Post
+    key={post.id}
+    id={post.id}
+    title={post.title} />
+);
+```
+
+ऊपर के उदाहरण के साथ, `Post` कौम्पोनॅन्ट `props.id` पढ़ सकता है, लेकिन `props.key` नहीं।
+
+### JSX में map() को एम्बेड करना {#embedding-map-in-jsx}
+
+ऊपर दिए गए उदाहरणों में हमने एक अलग `listItems` वेरिएबल को घोषित किया था और इसे JSX में शामिल किया था:
+
+```js{3-6}
+function NumberList(props) {
+  const numbers = props.numbers;
+  const listItems = numbers.map((number) =>
+    <ListItem key={number.toString()}
+              value={number} />
+  );
+  return (
+    <ul>
+      {listItems}
+    </ul>
+  );
+}
+```
+
+JSX कर्ली ब्रेसिज़ में किसी भी [एक्सप्रेशन की एम्बेडिंग](/docs/introducing-jsx.html#embedding-expressions-in-jsx) करने की अनुमति देता है ताकि हम `map()` के परिणाम को इनलाइन कर सकें:
+
+```js{5-8}
+function NumberList(props) {
+  const numbers = props.numbers;
+  return (
+    <ul>
+      {numbers.map((number) =>
+        <ListItem key={number.toString()}
+                  value={number} />
+      )}
+    </ul>
+  );
+}
+```
+
+[**इसे CodePen पर आज़माएँ**](https://codepen.io/gaearon/pen/BLvYrB?editors=0010)
+
+कभी-कभी इसका परिणाम स्पष्ट कोड होता है, लेकिन इस शैली का दुरुपयोग भी किया जा सकता है। जैसे जावास्क्रिप्ट में ये आपको तय करना होता है की readability के लिए एक variable को extract करना चाहिए या नहीं। ध्यान रखें कि यदि `map()` बॉडी बहुत नेस्टेड है, तो [कंपोनेंट निकालने](/docs/components-and-props.html#extracting-components) का अच्छा समय हो सकता है।
diff --git a/nav.yml b/nav.yml
new file mode 100644
index 000000000..4a481fc01
--- /dev/null
+++ b/nav.yml
@@ -0,0 +1,163 @@
+- title: Installation
+  items:
+    - id: getting-started
+      title: Getting Started
+    - id: add-react-to-a-website
+      title: Add React to a Website
+    - id: create-a-new-react-app
+      title: Create a New React App
+    - id: cdn-links
+      title: CDN Links
+- title: Main Concepts
+  isOrdered: true
+  items:
+    - id: hello-world
+      title: Hello World
+    - id: introducing-jsx
+      title: Introducing JSX
+    - id: rendering-elements
+      title: Rendering Elements
+    - id: components-and-props
+      title: Components and Props
+    - id: state-and-lifecycle
+      title: State and Lifecycle
+    - id: handling-events
+      title: Handling Events
+    - id: conditional-rendering
+      title: Conditional Rendering
+    - id: lists-and-keys
+      title: Lists and Keys
+    - id: forms
+      title: Forms
+    - id: lifting-state-up
+      title: Lifting State Up
+    - id: composition-vs-inheritance
+      title: Composition vs Inheritance
+    - id: thinking-in-react
+      title: Thinking In React
+- title: Advanced Guides
+  items:
+    - id: accessibility
+      title: Accessibility
+    - id: code-splitting
+      title: Code-Splitting
+    - id: context
+      title: Context
+    - id: error-boundaries
+      title: Error Boundaries
+    - id: forwarding-refs
+      title: Forwarding Refs
+    - id: fragments
+      title: Fragments
+    - id: higher-order-components
+      title: Higher-Order Components
+    - id: integrating-with-other-libraries
+      title: Integrating with Other Libraries
+    - id: jsx-in-depth
+      title: JSX In Depth
+    - id: optimizing-performance
+      title: Optimizing Performance
+    - id: portals
+      title: Portals
+    - id: profiler
+      title: Profiler
+    - id: react-without-es6
+      title: React Without ES6
+    - id: react-without-jsx
+      title: React Without JSX
+    - id: reconciliation
+      title: Reconciliation
+    - id: refs-and-the-dom
+      title: Refs and the DOM
+    - id: render-props
+      title: Render Props
+    - id: static-type-checking
+      title: Static Type Checking
+    - id: strict-mode
+      title: Strict Mode
+    - id: typechecking-with-proptypes
+      title: Typechecking With PropTypes
+    - id: uncontrolled-components
+      title: Uncontrolled Components
+    - id: web-components
+      title: Web Components
+- title: API Reference
+  items:
+    - id: react-api
+      title: React
+      subitems:
+        - id: react-component
+          title: React.Component
+    - id: react-dom
+      title: ReactDOM
+    - id: react-dom-server
+      title: ReactDOMServer
+    - id: dom-elements
+      title: DOM Elements
+    - id: events
+      title: SyntheticEvent
+    - id: test-utils
+      title: Test Utilities
+    - id: shallow-renderer
+      title: Shallow Renderer
+    - id: test-renderer
+      title: Test Renderer
+    - id: javascript-environment-requirements
+      title: JS Environment Requirements
+    - id: glossary
+      title: Glossary
+- title: Hooks (New)
+  isOrdered: true
+  items:
+      - id: hooks-intro
+        title: Introducing Hooks
+      - id: hooks-overview
+        title: Hooks at a Glance
+      - id: hooks-state
+        title: Using the State Hook
+      - id: hooks-effect
+        title: Using the Effect Hook
+      - id: hooks-rules
+        title: Rules of Hooks
+      - id: hooks-custom
+        title: Building Your Own Hooks
+      - id: hooks-reference
+        title: Hooks API Reference
+      - id: hooks-faq
+        title: Hooks FAQ
+- title: Testing
+  items:
+    - id: testing 
+      title: Testing Overview
+    - id: testing-recipes
+      title: Testing Recipes
+    - id: testing-environments
+      title: Testing Environments
+- title: Contributing
+  items:
+  - id: how-to-contribute
+    title: How to Contribute
+  - id: codebase-overview
+    title: Codebase Overview
+  - id: implementation-notes
+    title: Implementation Notes
+  - id: design-principles
+    title: Design Principles
+- title: FAQ
+  items:
+    - id: faq-ajax
+      title: AJAX and APIs
+    - id: faq-build
+      title: Babel, JSX, and Build Steps
+    - id: faq-functions
+      title: Passing Functions to Components
+    - id: faq-state
+      title: Component State
+    - id: faq-styling
+      title: Styling and CSS
+    - id: faq-structure
+      title: File Structure
+    - id: faq-versioning
+      title: Versioning Policy
+    - id: faq-internals
+      title: Virtual DOM and Internals
diff --git a/optimizing-performance.md b/optimizing-performance.md
new file mode 100644
index 000000000..b5aea3bd6
--- /dev/null
+++ b/optimizing-performance.md
@@ -0,0 +1,384 @@
+---
+id: optimizing-performance
+title: Optimizing Performance
+permalink: docs/optimizing-performance.html
+redirect_from:
+  - "docs/advanced-performance.html"
+---
+
+Internally, React uses several clever techniques to minimize the number of costly DOM operations required to update the UI. For many applications, using React will lead to a fast user interface without doing much work to specifically optimize for performance. Nevertheless, there are several ways you can speed up your React application.
+
+## Use the Production Build {#use-the-production-build}
+
+If you're benchmarking or experiencing performance problems in your React apps, make sure you're testing with the minified production build.
+
+By default, React includes many helpful warnings. These warnings are very useful in development. However, they make React larger and slower so you should make sure to use the production version when you deploy the app.
+
+If you aren't sure whether your build process is set up correctly, you can check it by installing [React Developer Tools for Chrome](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi). If you visit a site with React in production mode, the icon will have a dark background:
+
+<img src="../images/docs/devtools-prod.png" style="max-width:100%" alt="React DevTools on a website with production version of React">
+
+If you visit a site with React in development mode, the icon will have a red background:
+
+<img src="../images/docs/devtools-dev.png" style="max-width:100%" alt="React DevTools on a website with development version of React">
+
+It is expected that you use the development mode when working on your app, and the production mode when deploying your app to the users.
+
+You can find instructions for building your app for production below.
+
+### Create React App {#create-react-app}
+
+If your project is built with [Create React App](https://github.com/facebookincubator/create-react-app), run:
+
+```
+npm run build
+```
+
+This will create a production build of your app in the `build/` folder of your project.
+
+Remember that this is only necessary before deploying to production. For normal development, use `npm start`.
+
+### Single-File Builds {#single-file-builds}
+
+We offer production-ready versions of React and React DOM as single files:
+
+```html
+<script src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
+<script src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>
+```
+
+Remember that only React files ending with `.production.min.js` are suitable for production.
+
+### Brunch {#brunch}
+
+For the most efficient Brunch production build, install the [`terser-brunch`](https://github.com/brunch/terser-brunch) plugin:
+
+```
+# If you use npm
+npm install --save-dev terser-brunch
+
+# If you use Yarn
+yarn add --dev terser-brunch
+```
+
+Then, to create a production build, add the `-p` flag to the `build` command:
+
+```
+brunch build -p
+```
+
+Remember that you only need to do this for production builds. You shouldn't pass the `-p` flag or apply this plugin in development, because it will hide useful React warnings and make the builds much slower.
+
+### Browserify {#browserify}
+
+For the most efficient Browserify production build, install a few plugins:
+
+```
+# If you use npm
+npm install --save-dev envify terser uglifyify 
+
+# If you use Yarn
+yarn add --dev envify terser uglifyify 
+```
+
+To create a production build, make sure that you add these transforms **(the order matters)**:
+
+* The [`envify`](https://github.com/hughsk/envify) transform ensures the right build environment is set. Make it global (`-g`).
+* The [`uglifyify`](https://github.com/hughsk/uglifyify) transform removes development imports. Make it global too (`-g`).
+* Finally, the resulting bundle is piped to [`terser`](https://github.com/terser-js/terser) for mangling ([read why](https://github.com/hughsk/uglifyify#motivationusage)).
+
+For example:
+
+```
+browserify ./index.js \
+  -g [ envify --NODE_ENV production ] \
+  -g uglifyify \
+  | terser --compress --mangle > ./bundle.js
+```
+
+Remember that you only need to do this for production builds. You shouldn't apply these plugins in development because they will hide useful React warnings, and make the builds much slower.
+
+### Rollup {#rollup}
+
+For the most efficient Rollup production build, install a few plugins:
+
+```bash
+# If you use npm
+npm install --save-dev rollup-plugin-commonjs rollup-plugin-replace rollup-plugin-terser
+
+# If you use Yarn
+yarn add --dev rollup-plugin-commonjs rollup-plugin-replace rollup-plugin-terser
+```
+
+To create a production build, make sure that you add these plugins **(the order matters)**:
+
+* The [`replace`](https://github.com/rollup/rollup-plugin-replace) plugin ensures the right build environment is set.
+* The [`commonjs`](https://github.com/rollup/rollup-plugin-commonjs) plugin provides support for CommonJS in Rollup.
+* The [`terser`](https://github.com/TrySound/rollup-plugin-terser) plugin compresses and mangles the final bundle.
+
+```js
+plugins: [
+  // ...
+  require('rollup-plugin-replace')({
+    'process.env.NODE_ENV': JSON.stringify('production')
+  }),
+  require('rollup-plugin-commonjs')(),
+  require('rollup-plugin-terser')(),
+  // ...
+]
+```
+
+For a complete setup example [see this gist](https://gist.github.com/Rich-Harris/cb14f4bc0670c47d00d191565be36bf0).
+
+Remember that you only need to do this for production builds. You shouldn't apply the `terser` plugin or the `replace` plugin with `'production'` value in development because they will hide useful React warnings, and make the builds much slower.
+
+### webpack {#webpack}
+
+>**Note:**
+>
+>If you're using Create React App, please follow [the instructions above](#create-react-app).<br>
+>This section is only relevant if you configure webpack directly.
+
+Webpack v4+ will minify your code by default in production mode.
+
+```js
+const TerserPlugin = require('terser-webpack-plugin');
+
+module.exports = {
+  mode: 'production',
+  optimization: {
+    minimizer: [new TerserPlugin({ /* additional options here */ })],
+  },
+};
+```
+
+You can learn more about this in [webpack documentation](https://webpack.js.org/guides/production/).
+
+Remember that you only need to do this for production builds. You shouldn't apply `TerserPlugin` in development because it will hide useful React warnings, and make the builds much slower.
+
+## Profiling Components with the Chrome Performance Tab {#profiling-components-with-the-chrome-performance-tab}
+
+In the **development** mode, you can visualize how components mount, update, and unmount, using the performance tools in supported browsers. For example:
+
+<center><img src="../images/blog/react-perf-chrome-timeline.png" style="max-width:100%" alt="React components in Chrome timeline" /></center>
+
+To do this in Chrome:
+
+1. Temporarily **disable all Chrome extensions, especially React DevTools**. They can significantly skew the results!
+
+2. Make sure you're running the application in the development mode.
+
+3. Open the Chrome DevTools **[Performance](https://developers.google.com/web/tools/chrome-devtools/evaluate-performance/timeline-tool)** tab and press **Record**.
+
+4. Perform the actions you want to profile. Don't record more than 20 seconds or Chrome might hang.
+
+5. Stop recording.
+
+6. React events will be grouped under the **User Timing** label.
+
+For a more detailed walkthrough, check out [this article by Ben Schwarz](https://calibreapp.com/blog/2017-11-28-debugging-react/).
+
+Note that **the numbers are relative so components will render faster in production**. Still, this should help you realize when unrelated UI gets updated by mistake, and how deep and how often your UI updates occur.
+
+Currently Chrome, Edge, and IE are the only browsers supporting this feature, but we use the standard [User Timing API](https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API) so we expect more browsers to add support for it.
+
+## Profiling Components with the DevTools Profiler {#profiling-components-with-the-devtools-profiler}
+
+`react-dom` 16.5+ and `react-native` 0.57+ provide enhanced profiling capabilities in DEV mode with the React DevTools Profiler.
+An overview of the Profiler can be found in the blog post ["Introducing the React Profiler"](/blog/2018/09/10/introducing-the-react-profiler.html).
+A video walkthrough of the profiler is also [available on YouTube](https://www.youtube.com/watch?v=nySib7ipZdk).
+
+If you haven't yet installed the React DevTools, you can find them here:
+
+- [Chrome Browser Extension](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en)
+- [Firefox Browser Extension](https://addons.mozilla.org/en-GB/firefox/addon/react-devtools/)
+- [Standalone Node Package](https://www.npmjs.com/package/react-devtools)
+
+> Note
+>
+> A production profiling bundle of `react-dom` is also available as `react-dom/profiling`.
+> Read more about how to use this bundle at [fb.me/react-profiling](https://fb.me/react-profiling)
+
+## Virtualize Long Lists {#virtualize-long-lists}
+
+If your application renders long lists of data (hundreds or thousands of rows), we recommended using a technique known as "windowing". This technique only renders a small subset of your rows at any given time, and can dramatically reduce the time it takes to re-render the components as well as the number of DOM nodes created.
+
+[react-window](https://react-window.now.sh/) and [react-virtualized](https://bvaughn.github.io/react-virtualized/) are popular windowing libraries. They provide several reusable components for displaying lists, grids, and tabular data. You can also create your own windowing component, like [Twitter did](https://medium.com/@paularmstrong/twitter-lite-and-high-performance-react-progressive-web-apps-at-scale-d28a00e780a3), if you want something more tailored to your application's specific use case.
+
+## Avoid Reconciliation {#avoid-reconciliation}
+
+React builds and maintains an internal representation of the rendered UI. It includes the React elements you return from your components. This representation lets React avoid creating DOM nodes and accessing existing ones beyond necessity, as that can be slower than operations on JavaScript objects. Sometimes it is referred to as a "virtual DOM", but it works the same way on React Native.
+
+When a component's props or state change, React decides whether an actual DOM update is necessary by comparing the newly returned element with the previously rendered one. When they are not equal, React will update the DOM.
+
+Even though React only updates the changed DOM nodes, re-rendering still takes some time. In many cases it's not a problem, but if the slowdown is noticeable, you can speed all of this up by overriding the lifecycle function `shouldComponentUpdate`, which is triggered before the re-rendering process starts. The default implementation of this function returns `true`, leaving React to perform the update:
+
+```javascript
+shouldComponentUpdate(nextProps, nextState) {
+  return true;
+}
+```
+
+If you know that in some situations your component doesn't need to update, you can return `false` from `shouldComponentUpdate` instead, to skip the whole rendering process, including calling `render()` on this component and below.
+
+In most cases, instead of writing `shouldComponentUpdate()` by hand, you can inherit from [`React.PureComponent`](/docs/react-api.html#reactpurecomponent). It is equivalent to implementing `shouldComponentUpdate()` with a shallow comparison of current and previous props and state.
+
+## shouldComponentUpdate In Action {#shouldcomponentupdate-in-action}
+
+Here's a subtree of components. For each one, `SCU` indicates what `shouldComponentUpdate` returned, and `vDOMEq` indicates whether the rendered React elements were equivalent. Finally, the circle's color indicates whether the component had to be reconciled or not.
+
+<figure><img src="../images/docs/should-component-update.png" style="max-width:100%" /></figure>
+
+Since `shouldComponentUpdate` returned `false` for the subtree rooted at C2, React did not attempt to render C2, and thus didn't even have to invoke `shouldComponentUpdate` on C4 and C5.
+
+For C1 and C3, `shouldComponentUpdate` returned `true`, so React had to go down to the leaves and check them. For C6 `shouldComponentUpdate` returned `true`, and since the rendered elements weren't equivalent React had to update the DOM.
+
+The last interesting case is C8. React had to render this component, but since the React elements it returned were equal to the previously rendered ones, it didn't have to update the DOM.
+
+Note that React only had to do DOM mutations for C6, which was inevitable. For C8, it bailed out by comparing the rendered React elements, and for C2's subtree and C7, it didn't even have to compare the elements as we bailed out on `shouldComponentUpdate`, and `render` was not called.
+
+## Examples {#examples}
+
+If the only way your component ever changes is when the `props.color` or the `state.count` variable changes, you could have `shouldComponentUpdate` check that:
+
+```javascript
+class CounterButton extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {count: 1};
+  }
+
+  shouldComponentUpdate(nextProps, nextState) {
+    if (this.props.color !== nextProps.color) {
+      return true;
+    }
+    if (this.state.count !== nextState.count) {
+      return true;
+    }
+    return false;
+  }
+
+  render() {
+    return (
+      <button
+        color={this.props.color}
+        onClick={() => this.setState(state => ({count: state.count + 1}))}>
+        Count: {this.state.count}
+      </button>
+    );
+  }
+}
+```
+
+In this code, `shouldComponentUpdate` is just checking if there is any change in `props.color` or `state.count`. If those values don't change, the component doesn't update. If your component got more complex, you could use a similar pattern of doing a "shallow comparison" between all the fields of `props` and `state` to determine if the component should update. This pattern is common enough that React provides a helper to use this logic - just inherit from `React.PureComponent`. So this code is a simpler way to achieve the same thing:
+
+```js
+class CounterButton extends React.PureComponent {
+  constructor(props) {
+    super(props);
+    this.state = {count: 1};
+  }
+
+  render() {
+    return (
+      <button
+        color={this.props.color}
+        onClick={() => this.setState(state => ({count: state.count + 1}))}>
+        Count: {this.state.count}
+      </button>
+    );
+  }
+}
+```
+
+Most of the time, you can use `React.PureComponent` instead of writing your own `shouldComponentUpdate`. It only does a shallow comparison, so you can't use it if the props or state may have been mutated in a way that a shallow comparison would miss.
+
+This can be a problem with more complex data structures. For example, let's say you want a `ListOfWords` component to render a comma-separated list of words, with a parent `WordAdder` component that lets you click a button to add a word to the list. This code does *not* work correctly:
+
+```javascript
+class ListOfWords extends React.PureComponent {
+  render() {
+    return <div>{this.props.words.join(',')}</div>;
+  }
+}
+
+class WordAdder extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      words: ['marklar']
+    };
+    this.handleClick = this.handleClick.bind(this);
+  }
+
+  handleClick() {
+    // This section is bad style and causes a bug
+    const words = this.state.words;
+    words.push('marklar');
+    this.setState({words: words});
+  }
+
+  render() {
+    return (
+      <div>
+        <button onClick={this.handleClick} />
+        <ListOfWords words={this.state.words} />
+      </div>
+    );
+  }
+}
+```
+
+The problem is that `PureComponent` will do a simple comparison between the old and new values of `this.props.words`. Since this code mutates the `words` array in the `handleClick` method of `WordAdder`, the old and new values of `this.props.words` will compare as equal, even though the actual words in the array have changed. The `ListOfWords` will thus not update even though it has new words that should be rendered.
+
+## The Power Of Not Mutating Data {#the-power-of-not-mutating-data}
+
+The simplest way to avoid this problem is to avoid mutating values that you are using as props or state. For example, the `handleClick` method above could be rewritten using `concat` as:
+
+```javascript
+handleClick() {
+  this.setState(state => ({
+    words: state.words.concat(['marklar'])
+  }));
+}
+```
+
+ES6 supports a [spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator) for arrays which can make this easier. If you're using Create React App, this syntax is available by default.
+
+```js
+handleClick() {
+  this.setState(state => ({
+    words: [...state.words, 'marklar'],
+  }));
+};
+```
+
+You can also rewrite code that mutates objects to avoid mutation, in a similar way. For example, let's say we have an object named `colormap` and we want to write a function that changes `colormap.right` to be `'blue'`. We could write:
+
+```js
+function updateColorMap(colormap) {
+  colormap.right = 'blue';
+}
+```
+
+To write this without mutating the original object, we can use [Object.assign](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) method:
+
+```js
+function updateColorMap(colormap) {
+  return Object.assign({}, colormap, {right: 'blue'});
+}
+```
+
+`updateColorMap` now returns a new object, rather than mutating the old one. `Object.assign` is in ES6 and requires a polyfill.
+
+There is a JavaScript proposal to add [object spread properties](https://github.com/sebmarkbage/ecmascript-rest-spread) to make it easier to update objects without mutation as well:
+
+```js
+function updateColorMap(colormap) {
+  return {...colormap, right: 'blue'};
+}
+```
+
+If you're using Create React App, both `Object.assign` and the object spread syntax are available by default.
+
+When you deal with deeply nested objects, updating them in an immutable way can feel convoluted. If you run into this problem, check out [Immer](https://github.com/mweststrate/immer) or [immutability-helper](https://github.com/kolodny/immutability-helper). These libraries let you write highly readable code without losing the benefits of immutability.
diff --git a/portals.md b/portals.md
new file mode 100644
index 000000000..650121396
--- /dev/null
+++ b/portals.md
@@ -0,0 +1,154 @@
+---
+id: portals
+title: Portals
+permalink: docs/portals.html
+---
+
+Portals provide a first-class way to render children into a DOM node that exists outside the DOM hierarchy of the parent component.
+
+```js
+ReactDOM.createPortal(child, container)
+```
+
+The first argument (`child`) is any [renderable React child](/docs/react-component.html#render), such as an element, string, or fragment. The second argument (`container`) is a DOM element.
+
+## Usage {#usage}
+
+Normally, when you return an element from a component's render method, it's mounted into the DOM as a child of the nearest parent node:
+
+```js{4,6}
+render() {
+  // React mounts a new div and renders the children into it
+  return (
+    <div>
+      {this.props.children}
+    </div>
+  );
+}
+```
+
+However, sometimes it's useful to insert a child into a different location in the DOM:
+
+```js{6}
+render() {
+  // React does *not* create a new div. It renders the children into `domNode`.
+  // `domNode` is any valid DOM node, regardless of its location in the DOM.
+  return ReactDOM.createPortal(
+    this.props.children,
+    domNode
+  );
+}
+```
+
+A typical use case for portals is when a parent component has an `overflow: hidden` or `z-index` style, but you need the child to visually "break out" of its container. For example, dialogs, hovercards, and tooltips.
+
+> Note:
+>
+> When working with portals, remember that [managing keyboard focus](/docs/accessibility.html#programmatically-managing-focus) becomes very important.
+>
+> For modal dialogs, ensure that everyone can interact with them by following the [WAI-ARIA Modal Authoring Practices](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal).
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/yzMaBd)
+
+## Event Bubbling Through Portals {#event-bubbling-through-portals}
+
+Even though a portal can be anywhere in the DOM tree, it behaves like a normal React child in every other way. Features like context work exactly the same regardless of whether the child is a portal, as the portal still exists in the *React tree* regardless of position in the *DOM tree*.
+
+This includes event bubbling. An event fired from inside a portal will propagate to ancestors in the containing *React tree*, even if those elements are not ancestors in the *DOM tree*. Assuming the following HTML structure:
+
+```html
+<html>
+  <body>
+    <div id="app-root"></div>
+    <div id="modal-root"></div>
+  </body>
+</html>
+```
+
+A `Parent` component in `#app-root` would be able to catch an uncaught, bubbling event from the sibling node `#modal-root`.
+
+```js{28-31,42-49,53,61-63,70-71,74}
+// These two containers are siblings in the DOM
+const appRoot = document.getElementById('app-root');
+const modalRoot = document.getElementById('modal-root');
+
+class Modal extends React.Component {
+  constructor(props) {
+    super(props);
+    this.el = document.createElement('div');
+  }
+
+  componentDidMount() {
+    // The portal element is inserted in the DOM tree after
+    // the Modal's children are mounted, meaning that children
+    // will be mounted on a detached DOM node. If a child
+    // component requires to be attached to the DOM tree
+    // immediately when mounted, for example to measure a
+    // DOM node, or uses 'autoFocus' in a descendant, add
+    // state to Modal and only render the children when Modal
+    // is inserted in the DOM tree.
+    modalRoot.appendChild(this.el);
+  }
+
+  componentWillUnmount() {
+    modalRoot.removeChild(this.el);
+  }
+
+  render() {
+    return ReactDOM.createPortal(
+      this.props.children,
+      this.el,
+    );
+  }
+}
+
+class Parent extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {clicks: 0};
+    this.handleClick = this.handleClick.bind(this);
+  }
+
+  handleClick() {
+    // This will fire when the button in Child is clicked,
+    // updating Parent's state, even though button
+    // is not direct descendant in the DOM.
+    this.setState(state => ({
+      clicks: state.clicks + 1
+    }));
+  }
+
+  render() {
+    return (
+      <div onClick={this.handleClick}>
+        <p>Number of clicks: {this.state.clicks}</p>
+        <p>
+          Open up the browser DevTools
+          to observe that the button
+          is not a child of the div
+          with the onClick handler.
+        </p>
+        <Modal>
+          <Child />
+        </Modal>
+      </div>
+    );
+  }
+}
+
+function Child() {
+  // The click event on this button will bubble up to parent,
+  // because there is no 'onClick' attribute defined
+  return (
+    <div className="modal">
+      <button>Click</button>
+    </div>
+  );
+}
+
+ReactDOM.render(<Parent />, appRoot);
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/jGBWpE)
+
+Catching an event bubbling up from a portal in a parent component allows the development of more flexible abstractions that are not inherently reliant on portals. For example, if you render a `<Modal />` component, the parent can capture its events regardless of whether it's implemented using portals.
diff --git a/react-without-es6.md b/react-without-es6.md
new file mode 100644
index 000000000..8b54d0981
--- /dev/null
+++ b/react-without-es6.md
@@ -0,0 +1,225 @@
+---
+id: react-without-es6
+title: React Without ES6
+permalink: docs/react-without-es6.html
+---
+
+Normally you would define a React component as a plain JavaScript class:
+
+```javascript
+class Greeting extends React.Component {
+  render() {
+    return <h1>Hello, {this.props.name}</h1>;
+  }
+}
+```
+
+If you don't use ES6 yet, you may use the `create-react-class` module instead:
+
+
+```javascript
+var createReactClass = require('create-react-class');
+var Greeting = createReactClass({
+  render: function() {
+    return <h1>Hello, {this.props.name}</h1>;
+  }
+});
+```
+
+The API of ES6 classes is similar to `createReactClass()` with a few exceptions.
+
+## Declaring Default Props {#declaring-default-props}
+
+With functions and ES6 classes `defaultProps` is defined as a property on the component itself:
+
+```javascript
+class Greeting extends React.Component {
+  // ...
+}
+
+Greeting.defaultProps = {
+  name: 'Mary'
+};
+```
+
+With `createReactClass()`, you need to define `getDefaultProps()` as a function on the passed object:
+
+```javascript
+var Greeting = createReactClass({
+  getDefaultProps: function() {
+    return {
+      name: 'Mary'
+    };
+  },
+
+  // ...
+
+});
+```
+
+## Setting the Initial State {#setting-the-initial-state}
+
+In ES6 classes, you can define the initial state by assigning `this.state` in the constructor:
+
+```javascript
+class Counter extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {count: props.initialCount};
+  }
+  // ...
+}
+```
+
+With `createReactClass()`, you have to provide a separate `getInitialState` method that returns the initial state:
+
+```javascript
+var Counter = createReactClass({
+  getInitialState: function() {
+    return {count: this.props.initialCount};
+  },
+  // ...
+});
+```
+
+## Autobinding {#autobinding}
+
+In React components declared as ES6 classes, methods follow the same semantics as regular ES6 classes. This means that they don't automatically bind `this` to the instance. You'll have to explicitly use `.bind(this)` in the constructor:
+
+```javascript
+class SayHello extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {message: 'Hello!'};
+    // This line is important!
+    this.handleClick = this.handleClick.bind(this);
+  }
+
+  handleClick() {
+    alert(this.state.message);
+  }
+
+  render() {
+    // Because `this.handleClick` is bound, we can use it as an event handler.
+    return (
+      <button onClick={this.handleClick}>
+        Say hello
+      </button>
+    );
+  }
+}
+```
+
+With `createReactClass()`, this is not necessary because it binds all methods:
+
+```javascript
+var SayHello = createReactClass({
+  getInitialState: function() {
+    return {message: 'Hello!'};
+  },
+
+  handleClick: function() {
+    alert(this.state.message);
+  },
+
+  render: function() {
+    return (
+      <button onClick={this.handleClick}>
+        Say hello
+      </button>
+    );
+  }
+});
+```
+
+This means writing ES6 classes comes with a little more boilerplate code for event handlers, but the upside is slightly better performance in large applications.
+
+If the boilerplate code is too unattractive to you, you may enable the **experimental** [Class Properties](https://babeljs.io/docs/plugins/transform-class-properties/) syntax proposal with Babel:
+
+
+```javascript
+class SayHello extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {message: 'Hello!'};
+  }
+  // WARNING: this syntax is experimental!
+  // Using an arrow here binds the method:
+  handleClick = () => {
+    alert(this.state.message);
+  }
+
+  render() {
+    return (
+      <button onClick={this.handleClick}>
+        Say hello
+      </button>
+    );
+  }
+}
+```
+
+Please note that the syntax above is **experimental** and the syntax may change, or the proposal might not make it into the language.
+
+If you'd rather play it safe, you have a few options:
+
+* Bind methods in the constructor.
+* Use arrow functions, e.g. `onClick={(e) => this.handleClick(e)}`.
+* Keep using `createReactClass`.
+
+## Mixins {#mixins}
+
+>**Note:**
+>
+>ES6 launched without any mixin support. Therefore, there is no support for mixins when you use React with ES6 classes.
+>
+>**We also found numerous issues in codebases using mixins, [and don't recommend using them in the new code](/blog/2016/07/13/mixins-considered-harmful.html).**
+>
+>This section exists only for the reference.
+
+Sometimes very different components may share some common functionality. These are sometimes called [cross-cutting concerns](https://en.wikipedia.org/wiki/Cross-cutting_concern). `createReactClass` lets you use a legacy `mixins` system for that.
+
+One common use case is a component wanting to update itself on a time interval. It's easy to use `setInterval()`, but it's important to cancel your interval when you don't need it anymore to save memory. React provides [lifecycle methods](/docs/react-component.html#the-component-lifecycle) that let you know when a component is about to be created or destroyed. Let's create a simple mixin that uses these methods to provide an easy `setInterval()` function that will automatically get cleaned up when your component is destroyed.
+
+```javascript
+var SetIntervalMixin = {
+  componentWillMount: function() {
+    this.intervals = [];
+  },
+  setInterval: function() {
+    this.intervals.push(setInterval.apply(null, arguments));
+  },
+  componentWillUnmount: function() {
+    this.intervals.forEach(clearInterval);
+  }
+};
+
+var createReactClass = require('create-react-class');
+
+var TickTock = createReactClass({
+  mixins: [SetIntervalMixin], // Use the mixin
+  getInitialState: function() {
+    return {seconds: 0};
+  },
+  componentDidMount: function() {
+    this.setInterval(this.tick, 1000); // Call a method on the mixin
+  },
+  tick: function() {
+    this.setState({seconds: this.state.seconds + 1});
+  },
+  render: function() {
+    return (
+      <p>
+        React has been running for {this.state.seconds} seconds.
+      </p>
+    );
+  }
+});
+
+ReactDOM.render(
+  <TickTock />,
+  document.getElementById('example')
+);
+```
+
+If a component is using multiple mixins and several mixins define the same lifecycle method (i.e. several mixins want to do some cleanup when the component is destroyed), all of the lifecycle methods are guaranteed to be called. Methods defined on mixins run in the order mixins were listed, followed by a method call on the component.
diff --git a/react-without-jsx.md b/react-without-jsx.md
new file mode 100644
index 000000000..85cdba45f
--- /dev/null
+++ b/react-without-jsx.md
@@ -0,0 +1,59 @@
+---
+id: react-without-jsx
+title: React Without JSX
+permalink: docs/react-without-jsx.html
+---
+
+JSX is not a requirement for using React. Using React without JSX is especially convenient when you don't want to set up compilation in your build environment.
+
+Each JSX element is just syntactic sugar for calling `React.createElement(component, props, ...children)`. So, anything you can do with JSX can also be done with just plain JavaScript.
+
+For example, this code written with JSX:
+
+```js
+class Hello extends React.Component {
+  render() {
+    return <div>Hello {this.props.toWhat}</div>;
+  }
+}
+
+ReactDOM.render(
+  <Hello toWhat="World" />,
+  document.getElementById('root')
+);
+```
+
+can be compiled to this code that does not use JSX:
+
+```js
+class Hello extends React.Component {
+  render() {
+    return React.createElement('div', null, `Hello ${this.props.toWhat}`);
+  }
+}
+
+ReactDOM.render(
+  React.createElement(Hello, {toWhat: 'World'}, null),
+  document.getElementById('root')
+);
+```
+
+If you're curious to see more examples of how JSX is converted to JavaScript, you can try out [the online Babel compiler](babel://jsx-simple-example).
+
+The component can either be provided as a string, or as a subclass of `React.Component`, or a plain function for stateless components.
+
+If you get tired of typing `React.createElement` so much, one common pattern is to assign a shorthand:
+
+```js
+const e = React.createElement;
+
+ReactDOM.render(
+  e('div', null, 'Hello World'),
+  document.getElementById('root')
+);
+```
+
+If you use this shorthand form for `React.createElement`, it can be almost as convenient to use React without JSX.
+
+Alternatively, you can refer to community projects such as [`react-hyperscript`](https://github.com/mlmorg/react-hyperscript) and [`hyperscript-helpers`](https://github.com/ohanhi/hyperscript-helpers) which offer a terser syntax.
+
diff --git a/reconciliation.md b/reconciliation.md
new file mode 100644
index 000000000..1624bfbde
--- /dev/null
+++ b/reconciliation.md
@@ -0,0 +1,157 @@
+---
+id: reconciliation
+title: Reconciliation
+permalink: docs/reconciliation.html
+---
+
+React provides a declarative API so that you don't have to worry about exactly what changes on every update. This makes writing applications a lot easier, but it might not be obvious how this is implemented within React. This article explains the choices we made in React's "diffing" algorithm so that component updates are predictable while being fast enough for high-performance apps.
+
+## Motivation {#motivation}
+
+When you use React, at a single point in time you can think of the `render()` function as creating a tree of React elements. On the next state or props update, that `render()` function will return a different tree of React elements. React then needs to figure out how to efficiently update the UI to match the most recent tree.
+
+There are some generic solutions to this algorithmic problem of generating the minimum number of operations to transform one tree into another. However, the [state of the art algorithms](https://grfia.dlsi.ua.es/ml/algorithms/references/editsurvey_bille.pdf) have a complexity in the order of O(n<sup>3</sup>) where n is the number of elements in the tree.
+
+If we used this in React, displaying 1000 elements would require in the order of one billion comparisons. This is far too expensive. Instead, React implements a heuristic O(n) algorithm based on two assumptions:
+
+1. Two elements of different types will produce different trees.
+2. The developer can hint at which child elements may be stable across different renders with a `key` prop.
+
+In practice, these assumptions are valid for almost all practical use cases.
+
+## The Diffing Algorithm {#the-diffing-algorithm}
+
+When diffing two trees, React first compares the two root elements. The behavior is different depending on the types of the root elements.
+
+### Elements Of Different Types {#elements-of-different-types}
+
+Whenever the root elements have different types, React will tear down the old tree and build the new tree from scratch. Going from `<a>` to `<img>`, or from `<Article>` to `<Comment>`, or from `<Button>` to `<div>` - any of those will lead to a full rebuild.
+
+When tearing down a tree, old DOM nodes are destroyed. Component instances receive `componentWillUnmount()`. When building up a new tree, new DOM nodes are inserted into the DOM. Component instances receive `componentWillMount()` and then `componentDidMount()`. Any state associated with the old tree is lost.
+
+Any components below the root will also get unmounted and have their state destroyed. For example, when diffing:
+
+```xml
+<div>
+  <Counter />
+</div>
+
+<span>
+  <Counter />
+</span>
+```
+
+This will destroy the old `Counter` and remount a new one.
+
+### DOM Elements Of The Same Type {#dom-elements-of-the-same-type}
+
+When comparing two React DOM elements of the same type, React looks at the attributes of both, keeps the same underlying DOM node, and only updates the changed attributes. For example:
+
+```xml
+<div className="before" title="stuff" />
+
+<div className="after" title="stuff" />
+```
+
+By comparing these two elements, React knows to only modify the `className` on the underlying DOM node.
+
+When updating `style`, React also knows to update only the properties that changed. For example:
+
+```xml
+<div style={{color: 'red', fontWeight: 'bold'}} />
+
+<div style={{color: 'green', fontWeight: 'bold'}} />
+```
+
+When converting between these two elements, React knows to only modify the `color` style, not the `fontWeight`.
+
+After handling the DOM node, React then recurses on the children.
+
+### Component Elements Of The Same Type {#component-elements-of-the-same-type}
+
+When a component updates, the instance stays the same, so that state is maintained across renders. React updates the props of the underlying component instance to match the new element, and calls `componentWillReceiveProps()` and `componentWillUpdate()` on the underlying instance.
+
+Next, the `render()` method is called and the diff algorithm recurses on the previous result and the new result.
+
+### Recursing On Children {#recursing-on-children}
+
+By default, when recursing on the children of a DOM node, React just iterates over both lists of children at the same time and generates a mutation whenever there's a difference.
+
+For example, when adding an element at the end of the children, converting between these two trees works well:
+
+```xml
+<ul>
+  <li>first</li>
+  <li>second</li>
+</ul>
+
+<ul>
+  <li>first</li>
+  <li>second</li>
+  <li>third</li>
+</ul>
+```
+
+React will match the two `<li>first</li>` trees, match the two `<li>second</li>` trees, and then insert the `<li>third</li>` tree.
+
+If you implement it naively, inserting an element at the beginning has worse performance. For example, converting between these two trees works poorly:
+
+```xml
+<ul>
+  <li>Duke</li>
+  <li>Villanova</li>
+</ul>
+
+<ul>
+  <li>Connecticut</li>
+  <li>Duke</li>
+  <li>Villanova</li>
+</ul>
+```
+
+React will mutate every child instead of realizing it can keep the `<li>Duke</li>` and `<li>Villanova</li>` subtrees intact. This inefficiency can be a problem.
+
+### Keys {#keys}
+
+In order to solve this issue, React supports a `key` attribute. When children have keys, React uses the key to match children in the original tree with children in the subsequent tree. For example, adding a `key` to our inefficient example above can make the tree conversion efficient:
+
+```xml
+<ul>
+  <li key="2015">Duke</li>
+  <li key="2016">Villanova</li>
+</ul>
+
+<ul>
+  <li key="2014">Connecticut</li>
+  <li key="2015">Duke</li>
+  <li key="2016">Villanova</li>
+</ul>
+```
+
+Now React knows that the element with key `'2014'` is the new one, and the elements with the keys `'2015'` and `'2016'` have just moved.
+
+In practice, finding a key is usually not hard. The element you are going to display may already have a unique ID, so the key can just come from your data:
+
+```js
+<li key={item.id}>{item.name}</li>
+```
+
+When that's not the case, you can add a new ID property to your model or hash some parts of the content to generate a key. The key only has to be unique among its siblings, not globally unique.
+
+As a last resort, you can pass an item's index in the array as a key. This can work well if the items are never reordered, but reorders will be slow.
+
+Reorders can also cause issues with component state when indexes are used as keys. Component instances are updated and reused based on their key. If the key is an index, moving an item changes it. As a result, component state for things like uncontrolled inputs can get mixed up and updated in unexpected ways.
+
+[Here](codepen://reconciliation/index-used-as-key) is an example of the issues that can be caused by using indexes as keys on CodePen, and [here](codepen://reconciliation/no-index-used-as-key) is an updated version of the same example showing how not using indexes as keys will fix these reordering, sorting, and prepending issues.
+
+## Tradeoffs {#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. 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.
+
+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.
+
+1. The algorithm will not try to match subtrees of different component types. If you see yourself alternating between two component types with very similar output, you may want to make it the same type. In practice, we haven't found this to be an issue.
+
+2. Keys should be stable, predictable, and unique. Unstable keys (like those produced by `Math.random()`) will cause many component instances and DOM nodes to be unnecessarily recreated, which can cause performance degradation and lost state in child components.
diff --git a/reference-dom-elements.md b/reference-dom-elements.md
new file mode 100644
index 000000000..52e780b96
--- /dev/null
+++ b/reference-dom-elements.md
@@ -0,0 +1,196 @@
+---
+id: dom-elements
+title: DOM Elements
+layout: docs
+category: Reference
+permalink: docs/dom-elements.html
+redirect_from:
+  - "docs/tags-and-attributes.html"
+  - "docs/dom-differences.html"
+  - "docs/special-non-dom-attributes.html"
+  - "docs/class-name-manipulation.html"
+  - "tips/inline-styles.html"
+  - "tips/style-props-value-px.html"
+  - "tips/dangerously-set-inner-html.html"
+---
+
+React implements a browser-independent DOM system for performance and cross-browser compatibility. We took the opportunity to clean up a few rough edges in browser DOM implementations.
+
+In React, all DOM properties and attributes (including event handlers) should be camelCased. For example, the HTML attribute `tabindex` corresponds to the attribute `tabIndex` in React. The exception is `aria-*` and `data-*` attributes, which should be lowercased. For example, you can keep `aria-label` as `aria-label`.
+
+## Differences In Attributes {#differences-in-attributes}
+
+There are a number of attributes that work differently between React and HTML:
+
+### checked {#checked}
+
+The `checked` attribute is supported by `<input>` components of type `checkbox` or `radio`. You can use it to set whether the component is checked. This is useful for building controlled components. `defaultChecked` is the uncontrolled equivalent, which sets whether the component is checked when it is first mounted.
+
+### className {#classname}
+
+To specify a CSS class, use the `className` attribute. This applies to all regular DOM and SVG elements like `<div>`, `<a>`, and others.
+
+If you use React with Web Components (which is uncommon), use the `class` attribute instead.
+
+### dangerouslySetInnerHTML {#dangerouslysetinnerhtml}
+
+`dangerouslySetInnerHTML` is React's replacement for using `innerHTML` in the browser DOM. In general, setting HTML from code is risky because it's easy to inadvertently expose your users to a [cross-site scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) attack. So, you can set HTML directly from React, but you have to type out `dangerouslySetInnerHTML` and pass an object with a `__html` key, to remind yourself that it's dangerous. For example:
+
+```js
+function createMarkup() {
+  return {__html: 'First &middot; Second'};
+}
+
+function MyComponent() {
+  return <div dangerouslySetInnerHTML={createMarkup()} />;
+}
+```
+
+### htmlFor {#htmlfor}
+
+Since `for` is a reserved word in JavaScript, React elements use `htmlFor` instead.
+
+### onChange {#onchange}
+
+The `onChange` event behaves as you would expect it to: whenever a form field is changed, this event is fired. We intentionally do not use the existing browser behavior because `onChange` is a misnomer for its behavior and React relies on this event to handle user input in real time.
+
+### selected {#selected}
+
+The `selected` attribute is supported by `<option>` components. You can use it to set whether the component is selected. This is useful for building controlled components.
+
+### style {#style}
+
+>Note
+>
+>Some examples in the documentation use `style` for convenience, but **using the `style` attribute as the primary means of styling elements is generally not recommended.** In most cases, [`className`](#classname) should be used to reference classes defined in an external CSS stylesheet. `style` is most often used in React applications to add dynamically-computed styles at render time. See also [FAQ: Styling and CSS](/docs/faq-styling.html).
+
+The `style` attribute accepts a JavaScript object with camelCased properties rather than a CSS string. This is consistent with the DOM `style` JavaScript property, is more efficient, and prevents XSS security holes. For example:
+
+```js
+const divStyle = {
+  color: 'blue',
+  backgroundImage: 'url(' + imgUrl + ')',
+};
+
+function HelloWorldComponent() {
+  return <div style={divStyle}>Hello World!</div>;
+}
+```
+
+Note that styles are not autoprefixed. To support older browsers, you need to supply corresponding style properties:
+
+```js
+const divStyle = {
+  WebkitTransition: 'all', // note the capital 'W' here
+  msTransition: 'all' // 'ms' is the only lowercase vendor prefix
+};
+
+function ComponentWithTransition() {
+  return <div style={divStyle}>This should work cross-browser</div>;
+}
+```
+
+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`](https://www.andismith.com/blogs/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 numeric inline style properties. If you want to use units other than "px", specify the value as a string with the desired unit. For example:
+
+```js
+// Result style: '10px'
+<div style={{ height: 10 }}>
+  Hello World!
+</div>
+
+// Result style: '10%'
+<div style={{ height: '10%' }}>
+  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 {#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.
+
+### suppressHydrationWarning {#suppresshydrationwarning}
+
+If you use server-side React rendering, normally there is a warning when the server and the client render different content. However, in some rare cases, it is very hard or impossible to guarantee an exact match. For example, timestamps are expected to differ on the server and on the client.
+
+If you set `suppressHydrationWarning` to `true`, React will not warn you about mismatches in the attributes and the content of that element. It only works one level deep, and is intended to be used as an escape hatch. Don't overuse it. You can read more about hydration in the [`ReactDOM.hydrate()` documentation](/docs/react-dom.html#hydrate).
+
+### value {#value}
+
+The `value` attribute is supported by `<input>` and `<textarea>` components. You can use it to set the value of the component. This is useful for building controlled components. `defaultValue` is the uncontrolled equivalent, which sets the value of the component when it is first mounted.
+
+## All Supported HTML Attributes {#all-supported-html-attributes}
+
+As of React 16, any standard [or custom](/blog/2017/09/08/dom-attributes-in-react-16.html) DOM attributes are fully supported.
+
+React has always provided a JavaScript-centric API to the DOM. Since React components often take both custom and DOM-related props, React uses the `camelCase` convention just like the DOM APIs:
+
+```js
+<div tabIndex="-1" />      // Just like node.tabIndex DOM API
+<div className="Button" /> // Just like node.className DOM API
+<input readOnly={true} />  // Just like node.readOnly DOM API
+```
+
+These props work similarly to the corresponding HTML attributes, with the exception of the special cases documented above.
+
+Some of the DOM attributes supported by React include:
+
+```
+accept acceptCharset accessKey action allowFullScreen alt async autoComplete
+autoFocus autoPlay capture cellPadding cellSpacing challenge charSet checked
+cite classID className colSpan cols content contentEditable contextMenu controls
+controlsList coords crossOrigin data dateTime default defer dir disabled
+download draggable encType form formAction formEncType formMethod formNoValidate
+formTarget frameBorder headers height hidden high href hrefLang htmlFor
+httpEquiv icon id inputMode integrity is keyParams keyType kind label lang list
+loop low manifest marginHeight marginWidth max maxLength media mediaGroup method
+min minLength multiple muted name noValidate nonce open optimum pattern
+placeholder poster preload profile radioGroup readOnly rel required reversed
+role rowSpan rows sandbox scope scoped scrolling seamless selected shape size
+sizes span spellCheck src srcDoc srcLang srcSet start step style summary
+tabIndex target title type useMap value width wmode wrap
+```
+
+Similarly, all SVG attributes are fully supported:
+
+```
+accentHeight accumulate additive alignmentBaseline allowReorder alphabetic
+amplitude arabicForm ascent attributeName attributeType autoReverse azimuth
+baseFrequency baseProfile baselineShift bbox begin bias by calcMode capHeight
+clip clipPath clipPathUnits clipRule colorInterpolation
+colorInterpolationFilters colorProfile colorRendering contentScriptType
+contentStyleType cursor cx cy d decelerate descent diffuseConstant direction
+display divisor dominantBaseline dur dx dy edgeMode elevation enableBackground
+end exponent externalResourcesRequired fill fillOpacity fillRule filter
+filterRes filterUnits floodColor floodOpacity focusable fontFamily fontSize
+fontSizeAdjust fontStretch fontStyle fontVariant fontWeight format from fx fy
+g1 g2 glyphName glyphOrientationHorizontal glyphOrientationVertical glyphRef
+gradientTransform gradientUnits hanging horizAdvX horizOriginX ideographic
+imageRendering in in2 intercept k k1 k2 k3 k4 kernelMatrix kernelUnitLength
+kerning keyPoints keySplines keyTimes lengthAdjust letterSpacing lightingColor
+limitingConeAngle local markerEnd markerHeight markerMid markerStart
+markerUnits markerWidth mask maskContentUnits maskUnits mathematical mode
+numOctaves offset opacity operator order orient orientation origin overflow
+overlinePosition overlineThickness paintOrder panose1 pathLength
+patternContentUnits patternTransform patternUnits pointerEvents points
+pointsAtX pointsAtY pointsAtZ preserveAlpha preserveAspectRatio primitiveUnits
+r radius refX refY renderingIntent repeatCount repeatDur requiredExtensions
+requiredFeatures restart result rotate rx ry scale seed shapeRendering slope
+spacing specularConstant specularExponent speed spreadMethod startOffset
+stdDeviation stemh stemv stitchTiles stopColor stopOpacity
+strikethroughPosition strikethroughThickness string stroke strokeDasharray
+strokeDashoffset strokeLinecap strokeLinejoin strokeMiterlimit strokeOpacity
+strokeWidth surfaceScale systemLanguage tableValues targetX targetY textAnchor
+textDecoration textLength textRendering to transform u1 u2 underlinePosition
+underlineThickness unicode unicodeBidi unicodeRange unitsPerEm vAlphabetic
+vHanging vIdeographic vMathematical values vectorEffect version vertAdvY
+vertOriginX vertOriginY viewBox viewTarget visibility widths wordSpacing
+writingMode x x1 x2 xChannelSelector xHeight xlinkActuate xlinkArcrole
+xlinkHref xlinkRole xlinkShow xlinkTitle xlinkType xmlns xmlnsXlink xmlBase
+xmlLang xmlSpace y y1 y2 yChannelSelector z zoomAndPan
+```
+
+You may also use custom attributes as long as they're fully lowercase.
diff --git a/reference-events.md b/reference-events.md
new file mode 100644
index 000000000..745c6a71e
--- /dev/null
+++ b/reference-events.md
@@ -0,0 +1,389 @@
+---
+id: events
+title: SyntheticEvent
+permalink: docs/events.html
+layout: docs
+category: Reference
+---
+
+This reference guide documents the `SyntheticEvent` wrapper that forms part of React's Event System. See the [Handling Events](/docs/handling-events.html) guide to learn more.
+
+## Overview {#overview}
+
+Your event handlers will be passed instances of `SyntheticEvent`, a cross-browser wrapper around the browser's native event. It has the same interface as the browser's native event, including `stopPropagation()` and `preventDefault()`, except the events work identically across all browsers.
+
+If you find that you need the underlying browser event for some reason, simply use the `nativeEvent` attribute to get it. Every `SyntheticEvent` object has the following attributes:
+
+```javascript
+boolean bubbles
+boolean cancelable
+DOMEventTarget currentTarget
+boolean defaultPrevented
+number eventPhase
+boolean isTrusted
+DOMEvent nativeEvent
+void preventDefault()
+boolean isDefaultPrevented()
+void stopPropagation()
+boolean isPropagationStopped()
+DOMEventTarget target
+number timeStamp
+string type
+```
+
+> Note:
+>
+> As of v0.14, returning `false` from an event handler will no longer stop event propagation. Instead, `e.stopPropagation()` or `e.preventDefault()` should be triggered manually, as appropriate.
+
+### Event Pooling {#event-pooling}
+
+The `SyntheticEvent` is pooled. This means that the `SyntheticEvent` object will be reused and all properties will be nullified after the event callback has been invoked.
+This is for performance reasons.
+As such, you cannot access the event in an asynchronous way.
+
+```javascript
+function onClick(event) {
+  console.log(event); // => nullified object.
+  console.log(event.type); // => "click"
+  const eventType = event.type; // => "click"
+
+  setTimeout(function() {
+    console.log(event.type); // => null
+    console.log(eventType); // => "click"
+  }, 0);
+
+  // Won't work. this.state.clickEvent will only contain null values.
+  this.setState({clickEvent: event});
+
+  // You can still export event properties.
+  this.setState({eventType: event.type});
+}
+```
+
+> Note:
+>
+> If you want to access the event properties in an asynchronous way, you should call `event.persist()` on the event, which will remove the synthetic event from the pool and allow references to the event to be retained by user code.
+
+## Supported Events {#supported-events}
+
+React normalizes events so that they have consistent properties across different browsers.
+
+The event handlers below are triggered by an event in the bubbling phase. To register an event handler for the capture phase, append `Capture` to the event name; for example, instead of using `onClick`, you would use `onClickCapture` to handle the click event in the capture phase.
+
+- [Clipboard Events](#clipboard-events)
+- [Composition Events](#composition-events)
+- [Keyboard Events](#keyboard-events)
+- [Focus Events](#focus-events)
+- [Form Events](#form-events)
+- [Mouse Events](#mouse-events)
+- [Pointer Events](#pointer-events)
+- [Selection Events](#selection-events)
+- [Touch Events](#touch-events)
+- [UI Events](#ui-events)
+- [Wheel Events](#wheel-events)
+- [Media Events](#media-events)
+- [Image Events](#image-events)
+- [Animation Events](#animation-events)
+- [Transition Events](#transition-events)
+- [Other Events](#other-events)
+
+* * *
+
+## Reference {#reference}
+
+### Clipboard Events {#clipboard-events}
+
+Event names:
+
+```
+onCopy onCut onPaste
+```
+
+Properties:
+
+```javascript
+DOMDataTransfer clipboardData
+```
+
+* * *
+
+### Composition Events {#composition-events}
+
+Event names:
+
+```
+onCompositionEnd onCompositionStart onCompositionUpdate
+```
+
+Properties:
+
+```javascript
+string data
+
+```
+
+* * *
+
+### Keyboard Events {#keyboard-events}
+
+Event names:
+
+```
+onKeyDown onKeyPress onKeyUp
+```
+
+Properties:
+
+```javascript
+boolean altKey
+number charCode
+boolean ctrlKey
+boolean getModifierState(key)
+string key
+number keyCode
+string locale
+number location
+boolean metaKey
+boolean repeat
+boolean shiftKey
+number which
+```
+
+The `key` property can take any of the values documented in the [DOM Level 3 Events spec](https://www.w3.org/TR/uievents-key/#named-key-attribute-values).
+
+* * *
+
+### Focus Events {#focus-events}
+
+Event names:
+
+```
+onFocus onBlur
+```
+
+These focus events work on all elements in the React DOM, not just form elements.
+
+Properties:
+
+```javascript
+DOMEventTarget relatedTarget
+```
+
+* * *
+
+### Form Events {#form-events}
+
+Event names:
+
+```
+onChange onInput onInvalid onSubmit
+```
+
+For more information about the onChange event, see [Forms](/docs/forms.html).
+
+* * *
+
+### Mouse Events {#mouse-events}
+
+Event names:
+
+```
+onClick onContextMenu onDoubleClick onDrag onDragEnd onDragEnter onDragExit
+onDragLeave onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave
+onMouseMove onMouseOut onMouseOver onMouseUp
+```
+
+The `onMouseEnter` and `onMouseLeave` events propagate from the element being left to the one being entered instead of ordinary bubbling and do not have a capture phase.
+
+Properties:
+
+```javascript
+boolean altKey
+number button
+number buttons
+number clientX
+number clientY
+boolean ctrlKey
+boolean getModifierState(key)
+boolean metaKey
+number pageX
+number pageY
+DOMEventTarget relatedTarget
+number screenX
+number screenY
+boolean shiftKey
+```
+
+* * *
+
+### Pointer Events {#pointer-events}
+
+Event names:
+
+```
+onPointerDown onPointerMove onPointerUp onPointerCancel onGotPointerCapture
+onLostPointerCapture onPointerEnter onPointerLeave onPointerOver onPointerOut
+```
+
+The `onPointerEnter` and `onPointerLeave` events propagate from the element being left to the one being entered instead of ordinary bubbling and do not have a capture phase.
+
+Properties:
+
+As defined in the [W3 spec](https://www.w3.org/TR/pointerevents/), pointer events extend [Mouse Events](#mouse-events) with the following properties:
+
+```javascript
+number pointerId
+number width
+number height
+number pressure
+number tangentialPressure
+number tiltX
+number tiltY
+number twist
+string pointerType
+boolean isPrimary
+```
+
+A note on cross-browser support:
+
+Pointer events are not yet supported in every browser (at the time of writing this article, supported browsers include: Chrome, Firefox, Edge, and Internet Explorer). React deliberately does not polyfill support for other browsers because a standard-conform polyfill would significantly increase the bundle size of `react-dom`.
+
+If your application requires pointer events, we recommend adding a third party pointer event polyfill.
+
+* * *
+
+### Selection Events {#selection-events}
+
+Event names:
+
+```
+onSelect
+```
+
+* * *
+
+### Touch Events {#touch-events}
+
+Event names:
+
+```
+onTouchCancel onTouchEnd onTouchMove onTouchStart
+```
+
+Properties:
+
+```javascript
+boolean altKey
+DOMTouchList changedTouches
+boolean ctrlKey
+boolean getModifierState(key)
+boolean metaKey
+boolean shiftKey
+DOMTouchList targetTouches
+DOMTouchList touches
+```
+
+* * *
+
+### UI Events {#ui-events}
+
+Event names:
+
+```
+onScroll
+```
+
+Properties:
+
+```javascript
+number detail
+DOMAbstractView view
+```
+
+* * *
+
+### Wheel Events {#wheel-events}
+
+Event names:
+
+```
+onWheel
+```
+
+Properties:
+
+```javascript
+number deltaMode
+number deltaX
+number deltaY
+number deltaZ
+```
+
+* * *
+
+### Media Events {#media-events}
+
+Event names:
+
+```
+onAbort onCanPlay onCanPlayThrough onDurationChange onEmptied onEncrypted
+onEnded onError onLoadedData onLoadedMetadata onLoadStart onPause onPlay
+onPlaying onProgress onRateChange onSeeked onSeeking onStalled onSuspend
+onTimeUpdate onVolumeChange onWaiting
+```
+
+* * *
+
+### Image Events {#image-events}
+
+Event names:
+
+```
+onLoad onError
+```
+
+* * *
+
+### Animation Events {#animation-events}
+
+Event names:
+
+```
+onAnimationStart onAnimationEnd onAnimationIteration
+```
+
+Properties:
+
+```javascript
+string animationName
+string pseudoElement
+float elapsedTime
+```
+
+* * *
+
+### Transition Events {#transition-events}
+
+Event names:
+
+```
+onTransitionEnd
+```
+
+Properties:
+
+```javascript
+string propertyName
+string pseudoElement
+float elapsedTime
+```
+
+* * *
+
+### Other Events {#other-events}
+
+Event names:
+
+```
+onToggle
+```
diff --git a/reference-glossary.md b/reference-glossary.md
new file mode 100644
index 000000000..bdf3587a5
--- /dev/null
+++ b/reference-glossary.md
@@ -0,0 +1,166 @@
+---
+id: glossary
+title: Glossary of React Terms
+layout: docs
+category: Reference
+permalink: docs/glossary.html
+
+---
+
+## Single-page Application {#single-page-application}
+
+A single-page application is an application that loads a single HTML page and all the necessary assets (such as JavaScript and CSS) required for the application to run. Any interactions with the page or subsequent pages do not require a round trip to the server which means the page is not reloaded.
+
+Though you may build a single-page application in React, it is not a requirement. React can also be used for enhancing small parts of existing websites with additional interactivity. Code written in React can coexist peacefully with markup rendered on the server by something like PHP, or with other client-side libraries. In fact, this is exactly how React is being used at Facebook.
+
+## ES6, ES2015, ES2016, etc {#es6-es2015-es2016-etc}
+
+These acronyms all refer to the most recent versions of the ECMAScript Language Specification standard, which the JavaScript language is an implementation of. The ES6 version (also known as ES2015) includes many additions to the previous versions such as: arrow functions, classes, template literals, `let` and `const` statements. You can learn more about specific versions [here](https://en.wikipedia.org/wiki/ECMAScript#Versions).
+
+## Compilers {#compilers}
+
+A JavaScript compiler takes JavaScript code, transforms it and returns JavaScript code in a different format. The most common use case is to take ES6 syntax and transform it into syntax that older browsers are capable of interpreting. [Babel](https://babeljs.io/) is the compiler most commonly used with React.
+
+## Bundlers {#bundlers}
+
+Bundlers take JavaScript and CSS code written as separate modules (often hundreds of them), and combine them together into a few files better optimized for the browsers. Some bundlers commonly used in React applications include [Webpack](https://webpack.js.org/) and [Browserify](http://browserify.org/).
+
+## Package Managers {#package-managers}
+
+Package managers are tools that allow you to manage dependencies in your project. [npm](https://www.npmjs.com/) and [Yarn](https://yarnpkg.com/) are two package managers commonly used in React applications. Both of them are clients for the same npm package registry.
+
+## CDN {#cdn}
+
+CDN stands for Content Delivery Network. CDNs deliver cached, static content from a network of servers across the globe. 
+
+## JSX {#jsx}
+
+JSX is a syntax extension to JavaScript. It is similar to a template language, but it has full power of JavaScript. JSX gets compiled to `React.createElement()` calls which return plain JavaScript objects called "React elements". To get a basic introduction to JSX [see the docs here](/docs/introducing-jsx.html) and find a more in-depth tutorial on JSX [here](/docs/jsx-in-depth.html).
+
+React DOM uses camelCase property naming convention instead of HTML attribute names. For example, `tabindex` becomes `tabIndex` in JSX. The attribute `class` is also written as `className` since `class` is a reserved word in JavaScript:
+
+```js
+const name = 'Clementine';
+ReactDOM.render(
+  <h1 className="hello">My name is {name}!</h1>,
+  document.getElementById('root')
+);
+```  
+
+## [Elements](/docs/rendering-elements.html) {#elements}
+
+React elements are the building blocks of React applications. One might confuse elements with a more widely known concept of "components". An element describes what you want to see on the screen. React elements are immutable.
+
+```js
+const element = <h1>Hello, world</h1>;
+```
+
+Typically, elements are not used directly, but get returned from components.
+
+## [Components](/docs/components-and-props.html) {#components}
+
+React components are small, reusable pieces of code that return a React element to be rendered to the page. The simplest version of React component is a plain JavaScript function that returns a React element:
+
+```js
+function Welcome(props) {
+  return <h1>Hello, {props.name}</h1>;
+}
+```
+
+Components can also be ES6 classes:
+
+```js
+class Welcome extends React.Component {
+  render() {
+    return <h1>Hello, {this.props.name}</h1>;
+  }
+}
+```
+
+Components can be broken down into distinct pieces of functionality and used within other components. Components can return other components, arrays, strings and numbers. A good rule of thumb is that if a part of your UI is used several times (Button, Panel, Avatar), or is complex enough on its own (App, FeedStory, Comment), it is a good candidate to be a reusable component. Component names should also always start with a capital letter (`<Wrapper/>` **not** `<wrapper/>`). See [this documentation](/docs/components-and-props.html#rendering-a-component) for more information on rendering components. 
+
+### [`props`](/docs/components-and-props.html) {#props}
+
+`props` are inputs to a React component. They are data passed down from a parent component to a child component.
+
+Remember that `props` are readonly. They should not be modified in any way:
+
+```js
+// Wrong!
+props.number = 42;
+```
+
+If you need to modify some value in response to user input or a network response, use `state` instead.
+
+### `props.children` {#propschildren}
+
+`props.children` is available on every component. It contains the content between the opening and closing tags of a component. For example:
+
+```js
+<Welcome>Hello world!</Welcome>
+```
+
+The string `Hello world!` is available in `props.children` in the `Welcome` component:
+
+```js
+function Welcome(props) {
+  return <p>{props.children}</p>;
+}
+```
+
+For components defined as classes, use `this.props.children`:
+
+```js
+class Welcome extends React.Component {
+  render() {
+    return <p>{this.props.children}</p>;
+  }
+}
+```
+
+### [`state`](/docs/state-and-lifecycle.html#adding-local-state-to-a-class) {#state}
+
+A component needs `state` when some data associated with it changes over time. For example, a `Checkbox` component might need `isChecked` in its state, and a `NewsFeed` component might want to keep track of `fetchedPosts` in its state.
+
+The most important difference between `state` and `props` is that `props` are passed from a parent component, but `state` is managed by the component itself. A component cannot change its `props`, but it can change its `state`.
+
+For each particular piece of changing data, there should be just one component that "owns" it in its state. Don't try to synchronize states of two different components. Instead, [lift it up](/docs/lifting-state-up.html) to their closest shared ancestor, and pass it down as props to both of them.
+
+## [Lifecycle Methods](/docs/state-and-lifecycle.html#adding-lifecycle-methods-to-a-class) {#lifecycle-methods}
+
+Lifecycle methods are custom functionality that gets executed during the different phases of a component. There are methods available when the component gets created and inserted into the DOM ([mounting](/docs/react-component.html#mounting)), when the component updates, and when the component gets unmounted or removed from the DOM.
+
+ ## [Controlled](/docs/forms.html#controlled-components) vs. [Uncontrolled Components](/docs/uncontrolled-components.html)
+
+React has two different approaches to dealing with form inputs. 
+
+An input form element whose value is controlled by React is called a *controlled component*. When a user enters data into a controlled component a change event handler is triggered and your code decides whether the input is valid (by re-rendering with the updated value). If you do not re-render then the form element will remain unchanged.
+
+An *uncontrolled component* works like form elements do outside of React. When a user inputs data into a form field (an input box, dropdown, etc) the updated information is reflected without React needing to do anything. However, this also means that you can't force the field to have a certain value.
+
+In most cases you should use controlled components.
+
+## [Keys](/docs/lists-and-keys.html) {#keys}
+
+A "key" is a special string attribute you need to include when creating arrays of elements. Keys help React identify which items have changed, are added, or are removed. Keys should be given to the elements inside an array to give the elements a stable identity.
+
+Keys only need to be unique among sibling elements in the same array. They don't need to be unique across the whole application or even a single component.
+
+Don't pass something like `Math.random()` to keys. It is important that keys have a "stable identity" across re-renders so that React can determine when items are added, removed, or re-ordered. Ideally, keys should correspond to unique and stable identifiers coming from your data, such as `post.id`.
+
+## [Refs](/docs/refs-and-the-dom.html) {#refs}
+
+React supports a special attribute that you can attach to any component. The `ref` attribute can be an object created by [`React.createRef()` function](/docs/react-api.html#reactcreateref) or a callback function, or a string (in legacy API). When the `ref` attribute is a callback function, the function receives the underlying DOM element or class instance (depending on the type of element) as its argument. This allows you to have direct access to the DOM element or component instance.
+
+Use refs sparingly. If you find yourself often using refs to "make things happen" in your app, consider getting more familiar with [top-down data flow](/docs/lifting-state-up.html).
+
+## [Events](/docs/handling-events.html) {#events}
+
+Handling events with React elements has some syntactic differences:
+
+* React event handlers are named using camelCase, rather than lowercase.
+* With JSX you pass a function as the event handler, rather than a string.
+
+## [Reconciliation](/docs/reconciliation.html) {#reconciliation}
+
+When a component's props or state change, React decides whether an actual DOM update is necessary by comparing the newly returned element with the previously rendered one. When they are not equal, React will update the DOM. This process is called "reconciliation".
diff --git a/reference-javascript-environment-requirements.md b/reference-javascript-environment-requirements.md
new file mode 100644
index 000000000..8c9f6e3dc
--- /dev/null
+++ b/reference-javascript-environment-requirements.md
@@ -0,0 +1,31 @@
+---
+id: javascript-environment-requirements
+title: जावास्क्रिप्ट एनवायरनमेंट आवश्यकताएँ
+layout: docs
+category: Reference
+permalink: docs/javascript-environment-requirements.html
+---
+
+React 16 [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) और [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) कलेक्शन टाइप पर निर्भर करता है। यदि आप पुराने ब्राउज़र्स और उपकरणों का समर्थन करते हैं, जो अभी तक ये टाइप नेटिवली प्रदान नहीं कर सकते हैं (जैसे IE <11) या जिनके पास नॉन-कम्प्लाइअन्ट कार्यान्वयन हैं (उदाहरण IE 11), तो अपने बंडल किए गए एप्लिकेशन में एक वैश्विक polyfill शामिल करें, जैसे कि [core-js](https://github.com/zloirock/core-js) या [babel-polyfill](https://babeljs.io/docs/usage/polyfill/)।
+
+पुराने ब्राउज़र्स का समर्थन करने के लिए core-js का उपयोग करके React 16 के लिए एक polyfilled एनवायरनमेंट ऐसा दिखेगा:
+
+```js
+import 'core-js/es/map';
+import 'core-js/es/set';
+
+import React from 'react';
+import ReactDOM from 'react-dom';
+
+ReactDOM.render(
+  <h1>Hello, world!</h1>,
+  document.getElementById('root')
+);
+```
+
+React `requestAnimationFrame` पर भी निर्भर करती है (परीक्षण एनवायरनमेंट में भी)।
+आप `requestAnimationFrame` के समर्थन के लिए [raf](https://www.npmjs.com/package/raf) package का उपयोग कर सकते हैं :
+
+```js
+import 'raf/polyfill';
+```
diff --git a/reference-profiler.md b/reference-profiler.md
new file mode 100644
index 000000000..58a9e41c9
--- /dev/null
+++ b/reference-profiler.md
@@ -0,0 +1,119 @@
+---
+id: profiler
+title: Profiler API
+layout: docs
+category: Reference
+permalink: docs/profiler.html
+---
+
+The `Profiler` measures how often a React application renders and what the "cost" of rendering is.
+Its purpose is to help identify parts of an application that are slow and may benefit from [optimizations such as memoization](https://reactjs.org/docs/hooks-faq.html#how-to-memoize-calculations).
+
+> Note:
+>
+> Profiling adds some additional overhead, so **it is disabled in [the production build](https://reactjs.org/docs/optimizing-performance.html#use-the-production-build)**.
+>
+> To opt into production profiling, React provides a special production build with profiling enabled.
+> Read more about how to use this build at [fb.me/react-profiling](https://fb.me/react-profiling)
+
+## Usage
+
+A `Profiler` can be added anywhere in a React tree to measure the cost of rendering that part of the tree.
+It requires two props: an `id` (string) and an `onRender` callback (function) which React calls any time a component within the tree "commits" an update.
+
+For example, to profile a `Navigation` component and its descendants:
+
+```js{3}
+render(
+  <App>
+    <Profiler id="Navigation" onRender={callback}>
+      <Navigation {...props} />
+    </Profiler>
+    <Main {...props} />
+  </App>
+);
+```
+
+Multiple `Profiler` components can be used to measure different parts of an application:
+```js{3,6}
+render(
+  <App>
+    <Profiler id="Navigation" onRender={callback}>
+      <Navigation {...props} />
+    </Profiler>
+    <Profiler id="Main" onRender={callback}>
+      <Main {...props} />
+    </Profiler>
+  </App>
+);
+```
+
+`Profiler` components can also be nested to measure different components within the same subtree:
+```js{2,6,8}
+render(
+  <App>
+    <Profiler id="Panel" onRender={callback}>
+      <Panel {...props}>
+        <Profiler id="Content" onRender={callback}>
+          <Content {...props} />
+        </Profiler>
+        <Profiler id="PreviewPane" onRender={callback}>
+          <PreviewPane {...props} />
+        </Profiler>
+      </Panel>
+    </Profiler>
+  </App>
+);
+```
+
+> Note
+>
+> Although `Profiler` is a light-weight component, it should be used only when necessary; each use adds some CPU and memory overhead to an application.
+
+## `onRender` Callback
+
+The `Profiler` requires an `onRender` function as a prop.
+React calls this function any time a component within the profiled tree "commits" an update.
+It receives parameters describing what was rendered and how long it took.
+
+```js
+function onRenderCallback(
+  id, // the "id" prop of the Profiler tree that has just committed
+  phase, // either "mount" (if the tree just mounted) or "update" (if it re-rendered)
+  actualDuration, // time spent rendering the committed update
+  baseDuration, // estimated time to render the entire subtree without memoization
+  startTime, // when React began rendering this update
+  commitTime, // when React committed this update
+  interactions // the Set of interactions belonging to this update
+) {
+  // Aggregate or log render timings...
+}
+```
+
+Let's take a closer look at each of the props:
+
+* **`id: string`** - 
+The `id` prop of the `Profiler` tree that has just committed.
+This can be used to identify which part of the tree was committed if you are using multiple profilers.
+* **`phase: "mount" | "update"`** -
+Identifies whether the tree has just been mounted for the first time or re-rendered due to a change in props, state, or hooks.
+* **`actualDuration: number`** -
+Time spent rendering the `Profiler` and its descendants for the current update.
+This indicates how well the subtree makes use of memoization (e.g. [`React.memo`](/docs/react-api.html#reactmemo), [`useMemo`](/docs/hooks-reference.html#usememo), [`shouldComponentUpdate`](/docs/hooks-faq.html#how-do-i-implement-shouldcomponentupdate)).
+Ideally this value should decrease significantly after the initial mount as many of the descendants will only need to re-render if their specific props change.
+* **`baseDuration: number`** -
+Duration of the most recent `render` time for each individual component within the `Profiler` tree.
+This value estimates a worst-case cost of rendering (e.g. the initial mount or a tree with no memoization).
+* **`startTime: number`** -
+Timestamp when React began rendering the current update.
+* **`commitTime: number`** -
+Timestamp when React committed the current update.
+This value is shared between all profilers in a commit, enabling them to be grouped if desirable.
+* **`interactions: Set`** -
+Set of ["interactions"](http://fb.me/react-interaction-tracing) that were being traced the update was scheduled (e.g. when `render` or `setState` were called).
+
+> Note
+>
+> Interactions can be used to identify the cause of an update, although the API for tracing them is still experimental.
+>
+> Learn more about it at [fb.me/react-interaction-tracing](http://fb.me/react-interaction-tracing)
diff --git a/reference-pure-render-mixin.md b/reference-pure-render-mixin.md
new file mode 100644
index 000000000..1b5b56b9c
--- /dev/null
+++ b/reference-pure-render-mixin.md
@@ -0,0 +1,51 @@
+---
+id: pure-render-mixin
+title: PureRenderMixin
+layout: docs
+category: Reference
+permalink: docs/pure-render-mixin-old.html
+---
+
+> Note
+
+> 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.
+
+Example:
+
+```js
+var PureRenderMixin = require('react-addons-pure-render-mixin');
+var createReactClass = require('create-react-class');
+createReactClass({
+  mixins: [PureRenderMixin],
+
+  render: function() {
+    return <div className={this.props.className}>foo</div>;
+  }
+});
+```
+
+Example using ES6 class syntax:
+
+```js
+import PureRenderMixin from 'react-addons-pure-render-mixin';
+class FooComponent extends React.Component {
+  constructor(props) {
+    super(props);
+    this.shouldComponentUpdate = PureRenderMixin.shouldComponentUpdate.bind(this);
+  }
+
+  render() {
+    return <div className={this.props.className}>foo</div>;
+  }
+}
+```
+
+Under the hood, the mixin implements [shouldComponentUpdate](/docs/component-specs.html#updating-shouldcomponentupdate), in which it compares the current props and state with the next ones and returns `false` if the equalities pass.
+
+> Note:
+>
+> This only shallowly compares the objects. If these contain complex data structures, it may produce false-negatives for deeper differences. Only mix into components which have simple props and state, or use `forceUpdate()` when you know deep data structures have changed. Or, consider using [immutable objects](https://facebook.github.io/immutable-js/) to facilitate fast comparisons of nested data.
+>
+> Furthermore, `shouldComponentUpdate` skips updates for the whole component subtree. Make sure all the children components are also "pure".
diff --git a/reference-react-component.md b/reference-react-component.md
new file mode 100644
index 000000000..ecb4d087c
--- /dev/null
+++ b/reference-react-component.md
@@ -0,0 +1,642 @@
+---
+id: react-component
+title: React.Component
+layout: docs
+category: Reference
+permalink: docs/react-component.html
+redirect_from:
+  - "docs/component-api.html"
+  - "docs/component-specs.html"
+  - "docs/component-specs-ko-KR.html"
+  - "docs/component-specs-zh-CN.html"
+  - "tips/UNSAFE_componentWillReceiveProps-not-triggered-after-mounting.html"
+  - "tips/dom-event-listeners.html"
+  - "tips/initial-ajax.html"
+  - "tips/use-react-with-other-libraries.html"
+---
+
+This page contains a detailed API reference for the React component class definition. It assumes you're familiar with fundamental React concepts, such as [Components and Props](/docs/components-and-props.html), as well as [State and Lifecycle](/docs/state-and-lifecycle.html). If you're not, read them first.
+
+## Overview {#overview}
+
+React lets you define components as classes or functions. Components defined as classes currently provide more features which are described in detail on this page. To define a React component class, you need to extend `React.Component`:
+
+```js
+class Welcome extends React.Component {
+  render() {
+    return <h1>Hello, {this.props.name}</h1>;
+  }
+}
+```
+
+The only method you *must* define in a `React.Component` subclass is called [`render()`](#render). All the other methods described on this page are optional.
+
+**We strongly recommend against creating your own base component classes.** In React components, [code reuse is primarily achieved through composition rather than inheritance](/docs/composition-vs-inheritance.html).
+
+>Note:
+>
+>React doesn't force you to use the ES6 class syntax. If you prefer to avoid it, you may use the `create-react-class` module or a similar custom abstraction instead. Take a look at [Using React without ES6](/docs/react-without-es6.html) to learn more.
+
+### The Component Lifecycle {#the-component-lifecycle}
+
+Each component has several "lifecycle methods" that you can override to run code at particular times in the process. **You can use [this lifecycle diagram](http://projects.wojtekmaj.pl/react-lifecycle-methods-diagram/) as a cheat sheet.** In the list below, commonly used lifecycle methods are marked as **bold**. The rest of them exist for relatively rare use cases.
+
+#### Mounting {#mounting}
+
+These methods are called in the following order when an instance of a component is being created and inserted into the DOM:
+
+- [**`constructor()`**](#constructor)
+- [`static getDerivedStateFromProps()`](#static-getderivedstatefromprops)
+- [**`render()`**](#render)
+- [**`componentDidMount()`**](#componentdidmount)
+
+>Note:
+>
+>These methods are considered legacy and you should [avoid them](/blog/2018/03/27/update-on-async-rendering.html) in new code:
+>
+>- [`UNSAFE_componentWillMount()`](#unsafe_componentwillmount)
+
+#### Updating {#updating}
+
+An update can be caused by changes to props or state. These methods are called in the following order when a component is being re-rendered:
+
+- [`static getDerivedStateFromProps()`](#static-getderivedstatefromprops)
+- [`shouldComponentUpdate()`](#shouldcomponentupdate)
+- [**`render()`**](#render)
+- [`getSnapshotBeforeUpdate()`](#getsnapshotbeforeupdate)
+- [**`componentDidUpdate()`**](#componentdidupdate)
+
+>Note:
+>
+>These methods are considered legacy and you should [avoid them](/blog/2018/03/27/update-on-async-rendering.html) in new code:
+>
+>- [`UNSAFE_componentWillUpdate()`](#unsafe_componentwillupdate)
+>- [`UNSAFE_componentWillReceiveProps()`](#unsafe_componentwillreceiveprops)
+
+#### Unmounting {#unmounting}
+
+This method is called when a component is being removed from the DOM:
+
+- [**`componentWillUnmount()`**](#componentwillunmount)
+
+#### Error Handling {#error-handling}
+
+These methods are called when there is an error during rendering, in a lifecycle method, or in the constructor of any child component.
+
+- [`static getDerivedStateFromError()`](#static-getderivedstatefromerror)
+- [`componentDidCatch()`](#componentdidcatch)
+
+### Other APIs {#other-apis}
+
+Each component also provides some other APIs:
+
+  - [`setState()`](#setstate)
+  - [`forceUpdate()`](#forceupdate)
+
+### Class Properties {#class-properties}
+
+  - [`defaultProps`](#defaultprops)
+  - [`displayName`](#displayname)
+
+### Instance Properties {#instance-properties}
+
+  - [`props`](#props)
+  - [`state`](#state)
+
+* * *
+
+## Reference {#reference}
+
+### Commonly Used Lifecycle Methods {#commonly-used-lifecycle-methods}
+
+The methods in this section cover the vast majority of use cases you'll encounter creating React components. **For a visual reference, check out [this lifecycle diagram](http://projects.wojtekmaj.pl/react-lifecycle-methods-diagram/).**
+
+### `render()` {#render}
+
+```javascript
+render()
+```
+
+The `render()` method is the only required method in a class component.
+
+When called, it should examine `this.props` and `this.state` and return one of the following types:
+
+- **React elements.** Typically created via [JSX](/docs/introducing-jsx.html). For example, `<div />` and `<MyComponent />` are React elements that instruct React to render a DOM node, or another user-defined component, respectively.
+- **Arrays and fragments.** Let you return multiple elements from render. See the documentation on [fragments](/docs/fragments.html) for more details.
+- **Portals**. Let you render children into a different DOM subtree. See the documentation on [portals](/docs/portals.html) for more details.
+- **String and numbers.** These are rendered as text nodes in the DOM.
+- **Booleans or `null`**. Render nothing. (Mostly exists to support `return test && <Child />` pattern, where `test` is boolean.)
+
+The `render()` function should be pure, meaning that it does not modify component state, it returns the same result each time it's invoked, and it does not directly interact with the browser.
+
+If you need to interact with the browser, perform your work in `componentDidMount()` or the other lifecycle methods instead. Keeping `render()` pure makes components easier to think about.
+
+> Note
+>
+> `render()` will not be invoked if [`shouldComponentUpdate()`](#shouldcomponentupdate) returns false.
+
+* * *
+
+### `constructor()` {#constructor}
+
+```javascript
+constructor(props)
+```
+
+**If you don't initialize state and you don't bind methods, you don't need to implement a constructor for your React component.**
+
+The constructor for a React component is called before it is mounted. When implementing the constructor for a `React.Component` subclass, you should call `super(props)` before any other statement. Otherwise, `this.props` will be undefined in the constructor, which can lead to bugs.
+
+Typically, in React constructors are only used for two purposes:
+
+* Initializing [local state](/docs/state-and-lifecycle.html) by assigning an object to `this.state`.
+* Binding [event handler](/docs/handling-events.html) methods to an instance.
+
+You **should not call `setState()`** in the `constructor()`. Instead, if your component needs to use local state, **assign the initial state to `this.state`** directly in the constructor:
+
+```js
+constructor(props) {
+  super(props);
+  // Don't call this.setState() here!
+  this.state = { counter: 0 };
+  this.handleClick = this.handleClick.bind(this);
+}
+```
+
+Constructor is the only place where you should assign `this.state` directly. In all other methods, you need to use `this.setState()` instead.
+
+Avoid introducing any side-effects or subscriptions in the constructor. For those use cases, use `componentDidMount()` instead.
+
+>Note
+>
+>**Avoid copying props into state! This is a common mistake:**
+>
+>```js
+>constructor(props) {
+>  super(props);
+>  // Don't do this!
+>  this.state = { color: props.color };
+>}
+>```
+>
+>The problem is that it's both unnecessary (you can use `this.props.color` directly instead), and creates bugs (updates to the `color` prop won't be reflected in the state).
+>
+>**Only use this pattern if you intentionally want to ignore prop updates.** In that case, it makes sense to rename the prop to be called `initialColor` or `defaultColor`. You can then force a component to "reset" its internal state by [changing its `key`](/blog/2018/06/07/you-probably-dont-need-derived-state.html#recommendation-fully-uncontrolled-component-with-a-key) when necessary.
+>
+>Read our [blog post on avoiding derived state](/blog/2018/06/07/you-probably-dont-need-derived-state.html) to learn about what to do if you think you need some state to depend on the props.
+
+
+* * *
+
+### `componentDidMount()` {#componentdidmount}
+
+```javascript
+componentDidMount()
+```
+
+`componentDidMount()` is invoked immediately after a component is mounted (inserted into the tree). Initialization that requires DOM nodes should go here. If you need to load data from a remote endpoint, this is a good place to instantiate the network request.
+
+This method is a good place to set up any subscriptions. If you do that, don't forget to unsubscribe in `componentWillUnmount()`.
+
+You **may call `setState()` immediately** in `componentDidMount()`. It will trigger an extra rendering, but it will happen before the browser updates the screen. This guarantees that even though the `render()` will be called twice in this case, the user won't see the intermediate state. Use this pattern with caution because it often causes performance issues. In most cases, you should be able to assign the initial state in the `constructor()` instead. It can, however, be necessary for cases like modals and tooltips when you need to measure a DOM node before rendering something that depends on its size or position.
+
+* * *
+
+### `componentDidUpdate()` {#componentdidupdate}
+
+```javascript
+componentDidUpdate(prevProps, prevState, snapshot)
+```
+
+`componentDidUpdate()` is invoked immediately after updating occurs. This method is not called for the initial render.
+
+Use this as an opportunity to operate on the DOM when the component has been updated. This is also a good place to do network requests as long as you compare the current props to previous props (e.g. a network request may not be necessary if the props have not changed).
+
+```js
+componentDidUpdate(prevProps) {
+  // Typical usage (don't forget to compare props):
+  if (this.props.userID !== prevProps.userID) {
+    this.fetchData(this.props.userID);
+  }
+}
+```
+
+You **may call `setState()` immediately** in `componentDidUpdate()` but note that **it must be wrapped in a condition** like in the example above, or you'll cause an infinite loop. It would also cause an extra re-rendering which, while not visible to the user, can affect the component performance. If you're trying to "mirror" some state to a prop coming from above, consider using the prop directly instead. Read more about [why copying props into state causes bugs](/blog/2018/06/07/you-probably-dont-need-derived-state.html).
+
+If your component implements the `getSnapshotBeforeUpdate()` lifecycle (which is rare), the value it returns will be passed as a third "snapshot" parameter to `componentDidUpdate()`. Otherwise this parameter will be undefined.
+
+> Note
+>
+> `componentDidUpdate()` will not be invoked if [`shouldComponentUpdate()`](#shouldcomponentupdate) returns false.
+
+* * *
+
+### `componentWillUnmount()` {#componentwillunmount}
+
+```javascript
+componentWillUnmount()
+```
+
+`componentWillUnmount()` is invoked immediately before a component is unmounted and destroyed. Perform any necessary cleanup in this method, such as invalidating timers, canceling network requests, or cleaning up any subscriptions that were created in `componentDidMount()`.
+
+You **should not call `setState()`** in `componentWillUnmount()` because the component will never be re-rendered. Once a component instance is unmounted, it will never be mounted again.
+
+* * *
+
+### Rarely Used Lifecycle Methods {#rarely-used-lifecycle-methods}
+
+The methods in this section correspond to uncommon use cases. They're handy once in a while, but most of your components probably don't need any of them. **You can see most of the methods below on [this lifecycle diagram](http://projects.wojtekmaj.pl/react-lifecycle-methods-diagram/) if you click the "Show less common lifecycles" checkbox at the top of it.**
+
+
+### `shouldComponentUpdate()` {#shouldcomponentupdate}
+
+```javascript
+shouldComponentUpdate(nextProps, nextState)
+```
+
+Use `shouldComponentUpdate()` to let React know if a component's output is not affected by the current change in state or props. The default behavior is to re-render on every state change, and in the vast majority of cases you should rely on the default behavior.
+
+`shouldComponentUpdate()` is invoked before rendering when new props or state are being received. Defaults to `true`. This method is not called for the initial render or when `forceUpdate()` is used.
+
+This method only exists as a **[performance optimization](/docs/optimizing-performance.html).** Do not rely on it to "prevent" a rendering, as this can lead to bugs. **Consider using the built-in [`PureComponent`](/docs/react-api.html#reactpurecomponent)** instead of writing `shouldComponentUpdate()` by hand. `PureComponent` performs a shallow comparison of props and state, and reduces the chance that you'll skip a necessary update.
+
+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. Note that returning `false` does not prevent child components from re-rendering when *their* state changes.
+
+We do not recommend doing deep equality checks or using `JSON.stringify()` in `shouldComponentUpdate()`. It is very inefficient and will harm performance.
+
+Currently, if `shouldComponentUpdate()` returns `false`, then [`UNSAFE_componentWillUpdate()`](#unsafe_componentwillupdate), [`render()`](#render), and [`componentDidUpdate()`](#componentdidupdate) will not be invoked. 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.
+
+* * *
+
+### `static getDerivedStateFromProps()` {#static-getderivedstatefromprops}
+
+```js
+static getDerivedStateFromProps(props, state)
+```
+
+`getDerivedStateFromProps` is invoked right before calling the render method, both on the initial mount and on subsequent updates. It should return an object to update the state, or null to update nothing.
+
+This method exists for [rare use cases](/blog/2018/06/07/you-probably-dont-need-derived-state.html#when-to-use-derived-state) where the state depends on changes in props over time. For example, it might be handy for implementing a `<Transition>` component that compares its previous and next children to decide which of them to animate in and out.
+
+Deriving state leads to verbose code and makes your components difficult to think about.  
+[Make sure you're familiar with simpler alternatives:](/blog/2018/06/07/you-probably-dont-need-derived-state.html)
+
+* If you need to **perform a side effect** (for example, data fetching or an animation) in response to a change in props, use [`componentDidUpdate`](#componentdidupdate) lifecycle instead.
+
+* If you want to **re-compute some data only when a prop changes**, [use a memoization helper instead](/blog/2018/06/07/you-probably-dont-need-derived-state.html#what-about-memoization).
+
+* If you want to **"reset" some state when a prop changes**, consider either making a component [fully controlled](/blog/2018/06/07/you-probably-dont-need-derived-state.html#recommendation-fully-controlled-component) or [fully uncontrolled with a `key`](/blog/2018/06/07/you-probably-dont-need-derived-state.html#recommendation-fully-uncontrolled-component-with-a-key) instead.
+
+This method doesn't have access to the component instance. If you'd like, you can reuse some code between `getDerivedStateFromProps()` and the other class methods by extracting pure functions of the component props and state outside the class definition.
+
+Note that this method is fired on *every* render, regardless of the cause. This is in contrast to `UNSAFE_componentWillReceiveProps`, which only fires when the parent causes a re-render and not as a result of a local `setState`.
+
+* * *
+
+### `getSnapshotBeforeUpdate()` {#getsnapshotbeforeupdate}
+
+```javascript
+getSnapshotBeforeUpdate(prevProps, prevState)
+```
+
+`getSnapshotBeforeUpdate()` is invoked right before the most recently rendered output is committed to e.g. the DOM. It enables your component to capture some information from the DOM (e.g. scroll position) before it is potentially changed. Any value returned by this lifecycle will be passed as a parameter to `componentDidUpdate()`.
+
+This use case is not common, but it may occur in UIs like a chat thread that need to handle scroll position in a special way.
+
+A snapshot value (or `null`) should be returned.
+
+For example:
+
+`embed:react-component-reference/get-snapshot-before-update.js`
+
+In the above examples, it is important to read the `scrollHeight` property in `getSnapshotBeforeUpdate` because there may be delays between "render" phase lifecycles (like `render`) and "commit" phase lifecycles (like `getSnapshotBeforeUpdate` and `componentDidUpdate`).
+
+* * *
+
+### Error boundaries {#error-boundaries}
+
+[Error boundaries](/docs/error-boundaries.html) are React components that catch JavaScript errors anywhere in their child component tree, log those errors, and display a fallback UI instead of the component tree that crashed. Error boundaries catch errors during rendering, in lifecycle methods, and in constructors of the whole tree below them.
+
+A class component becomes an error boundary if it defines either (or both) of the lifecycle methods `static getDerivedStateFromError()` or `componentDidCatch()`. Updating state from these lifecycles lets you capture an unhandled JavaScript error in the below tree and display a fallback UI.
+
+Only use error boundaries for recovering from unexpected exceptions; **don't try to use them for control flow.**
+
+For more details, see [*Error Handling in React 16*](/blog/2017/07/26/error-handling-in-react-16.html).
+
+> Note
+> 
+> Error boundaries only catch errors in the components **below** them in the tree. An error boundary can’t catch an error within itself.
+
+### `static getDerivedStateFromError()` {#static-getderivedstatefromerror}
+```javascript
+static getDerivedStateFromError(error)
+```
+
+This lifecycle is invoked after an error has been thrown by a descendant component.
+It receives the error that was thrown as a parameter and should return a value to update state.
+
+```js{7-10,13-16}
+class ErrorBoundary extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(error) {
+    // Update state so the next render will show the fallback UI.
+    return { hasError: true };
+  }
+
+  render() {
+    if (this.state.hasError) {
+      // You can render any custom fallback UI
+      return <h1>Something went wrong.</h1>;
+    }
+
+    return this.props.children; 
+  }
+}
+```
+
+> Note
+>
+> `getDerivedStateFromError()` is called during the "render" phase, so side-effects are not permitted.
+For those use cases, use `componentDidCatch()` instead.
+
+* * *
+
+### `componentDidCatch()` {#componentdidcatch}
+
+```javascript
+componentDidCatch(error, info)
+```
+
+This lifecycle is invoked after an error has been thrown by a descendant component.
+It receives two parameters:
+
+1. `error` - The error that was thrown.
+2. `info` - An object with a `componentStack` key containing [information about which component threw the error](/docs/error-boundaries.html#component-stack-traces).
+
+
+`componentDidCatch()` is called during the "commit" phase, so side-effects are permitted.
+It should be used for things like logging errors:
+
+```js{12-19}
+class ErrorBoundary extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(error) {
+    // Update state so the next render will show the fallback UI.
+    return { hasError: true };
+  }
+
+  componentDidCatch(error, info) {
+    // Example "componentStack":
+    //   in ComponentThatThrows (created by App)
+    //   in ErrorBoundary (created by App)
+    //   in div (created by App)
+    //   in App
+    logComponentStackToMyService(info.componentStack);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      // You can render any custom fallback UI
+      return <h1>Something went wrong.</h1>;
+    }
+
+    return this.props.children; 
+  }
+}
+```
+
+> Note
+> 
+> In the event of an error, you can render a fallback UI with `componentDidCatch()` by calling `setState`, but this will be deprecated in a future release.
+> Use `static getDerivedStateFromError()` to handle fallback rendering instead.
+
+* * *
+
+### Legacy Lifecycle Methods {#legacy-lifecycle-methods}
+
+The lifecycle methods below are marked as "legacy". They still work, but we don't recommend using them in the new code. You can learn more about migrating away from legacy lifecycle methods in [this blog post](/blog/2018/03/27/update-on-async-rendering.html).
+
+### `UNSAFE_componentWillMount()` {#unsafe_componentwillmount}
+
+```javascript
+UNSAFE_componentWillMount()
+```
+
+> Note
+>
+> This lifecycle was previously named `componentWillMount`. That name will continue to work until version 17. Use the [`rename-unsafe-lifecycles` codemod](https://github.com/reactjs/react-codemod#rename-unsafe-lifecycles) to automatically update your components.
+
+`UNSAFE_componentWillMount()` is invoked just before mounting occurs. It is called before `render()`, therefore calling `setState()` synchronously in this method will not trigger an extra rendering. Generally, we recommend using the `constructor()` instead for initializing state.
+
+Avoid introducing any side-effects or subscriptions in this method. For those use cases, use `componentDidMount()` instead.
+
+This is the only lifecycle method called on server rendering.
+
+* * *
+
+### `UNSAFE_componentWillReceiveProps()` {#unsafe_componentwillreceiveprops}
+
+```javascript
+UNSAFE_componentWillReceiveProps(nextProps)
+```
+
+> Note
+>
+> This lifecycle was previously named `componentWillReceiveProps`. That name will continue to work until version 17. Use the [`rename-unsafe-lifecycles` codemod](https://github.com/reactjs/react-codemod#rename-unsafe-lifecycles) to automatically update your components.
+
+> Note:
+>
+> Using this lifecycle method often leads to bugs and inconsistencies
+>
+> * If you need to **perform a side effect** (for example, data fetching or an animation) in response to a change in props, use [`componentDidUpdate`](#componentdidupdate) lifecycle instead.
+> * If you used `componentWillReceiveProps` for **re-computing some data only when a prop changes**, [use a memoization helper instead](/blog/2018/06/07/you-probably-dont-need-derived-state.html#what-about-memoization).
+> * If you used `componentWillReceiveProps` to **"reset" some state when a prop changes**, consider either making a component [fully controlled](/blog/2018/06/07/you-probably-dont-need-derived-state.html#recommendation-fully-controlled-component) or [fully uncontrolled with a `key`](/blog/2018/06/07/you-probably-dont-need-derived-state.html#recommendation-fully-uncontrolled-component-with-a-key) instead.
+>
+> For other use cases, [follow the recommendations in this blog post about derived state](/blog/2018/06/07/you-probably-dont-need-derived-state.html).
+
+`UNSAFE_componentWillReceiveProps()` is invoked before a mounted component receives new props. If you need to update the state in response to prop changes (for example, to reset it), you may compare `this.props` and `nextProps` and perform state transitions using `this.setState()` in this method.
+
+Note that if a parent component causes your component to re-render, this method will be called even if props have not changed. Make sure to compare the current and next values if you only want to handle changes.
+
+React doesn't call `UNSAFE_componentWillReceiveProps()` with initial props during [mounting](#mounting). It only calls this method if some of component's props may update. Calling `this.setState()` generally doesn't trigger `UNSAFE_componentWillReceiveProps()`.
+
+* * *
+
+### `UNSAFE_componentWillUpdate()` {#unsafe_componentwillupdate}
+
+```javascript
+UNSAFE_componentWillUpdate(nextProps, nextState)
+```
+
+> Note
+>
+> This lifecycle was previously named `componentWillUpdate`. That name will continue to work until version 17. Use the [`rename-unsafe-lifecycles` codemod](https://github.com/reactjs/react-codemod#rename-unsafe-lifecycles) to automatically update your components.
+
+`UNSAFE_componentWillUpdate()` is invoked just before rendering when new props or state are being received. Use this as an opportunity to perform preparation before an update occurs. This method is not called for the initial render.
+
+Note that you cannot call `this.setState()` here; nor should you do anything else (e.g. dispatch a Redux action) that would trigger an update to a React component before `UNSAFE_componentWillUpdate()` returns.
+
+Typically, this method can be replaced by `componentDidUpdate()`. If you were reading from the DOM in this method (e.g. to save a scroll position), you can move that logic to `getSnapshotBeforeUpdate()`.
+
+> Note
+>
+> `UNSAFE_componentWillUpdate()` will not be invoked if [`shouldComponentUpdate()`](#shouldcomponentupdate) returns false.
+
+* * *
+
+## Other APIs {#other-apis-1}
+
+Unlike the lifecycle methods above (which React calls for you), the methods below are the methods *you* can call from your components.
+
+There are just two of them: `setState()` and `forceUpdate()`.
+
+### `setState()` {#setstate}
+
+```javascript
+setState(updater[, callback])
+```
+
+`setState()` enqueues changes to the component state and tells React that this component and its children need to be re-rendered with the updated state. This is the primary method you use to update the user interface in response to event handlers and server responses.
+
+Think of `setState()` as a *request* rather than an immediate command to update the component. For better perceived performance, React may delay it, and then update several components in a single pass. React does not guarantee that the state changes are applied immediately.
+
+`setState()` does not always immediately update the component. It may batch or defer the update until later. This makes reading `this.state` right after calling `setState()` a potential pitfall. Instead, use `componentDidUpdate` or a `setState` callback (`setState(updater, callback)`), either of which are guaranteed to fire after the update has been applied. If you need to set the state based on the previous state, read about the `updater` argument below.
+
+`setState()` will always lead to a re-render unless `shouldComponentUpdate()` returns `false`. If mutable objects are being used and conditional rendering logic cannot be implemented in `shouldComponentUpdate()`, calling `setState()` only when the new state differs from the previous state will avoid unnecessary re-renders.
+
+The first argument is an `updater` function with the signature:
+
+```javascript
+(state, props) => stateChange
+```
+
+`state` is a reference to the component state at the time the change is being applied. It should not be directly mutated. Instead, changes should be represented by building a new object based on the input from `state` and `props`. For instance, suppose we wanted to increment a value in state by `props.step`:
+
+```javascript
+this.setState((state, props) => {
+  return {counter: state.counter + props.step};
+});
+```
+
+Both `state` and `props` received by the updater function are guaranteed to be up-to-date. The output of the updater is shallowly merged with `state`.
+
+The second parameter to `setState()` is an optional callback function that will be executed once `setState` is completed and the component is re-rendered. Generally we recommend using `componentDidUpdate()` for such logic instead.
+
+You may optionally pass an object as the first argument to `setState()` instead of a function:
+
+```javascript
+setState(stateChange[, callback])
+```
+
+This performs a shallow merge of `stateChange` into the new state, e.g., to adjust a shopping cart item quantity:
+
+```javascript
+this.setState({quantity: 2})
+```
+
+This form of `setState()` is also asynchronous, and multiple calls during the same cycle may be batched together. For example, if you attempt to increment an item quantity more than once in the same cycle, that will result in the equivalent of:
+
+```javaScript
+Object.assign(
+  previousState,
+  {quantity: state.quantity + 1},
+  {quantity: state.quantity + 1},
+  ...
+)
+```
+
+Subsequent calls will override values from previous calls in the same cycle, so the quantity will only be incremented once. If the next state depends on the current state, we recommend using the updater function form, instead:
+
+```js
+this.setState((state) => {
+  return {quantity: state.quantity + 1};
+});
+```
+
+For more detail, see:
+
+* [State and Lifecycle guide](/docs/state-and-lifecycle.html)
+* [In depth: When and why are `setState()` calls batched?](https://stackoverflow.com/a/48610973/458193)
+* [In depth: Why isn't `this.state` updated immediately?](https://github.com/facebook/react/issues/11527#issuecomment-360199710)
+
+* * *
+
+### `forceUpdate()` {#forceupdate}
+
+```javascript
+component.forceUpdate(callback)
+```
+
+By default, when your component's state or props change, your component will re-render. If your `render()` method depends on some other data, you can tell React that the component needs re-rendering by calling `forceUpdate()`.
+
+Calling `forceUpdate()` will cause `render()` to be called on the component, skipping `shouldComponentUpdate()`. This will trigger the normal lifecycle methods for child components, including the `shouldComponentUpdate()` method of each child. React will still only update the DOM if the markup changes.
+
+Normally you should try to avoid all uses of `forceUpdate()` and only read from `this.props` and `this.state` in `render()`.
+
+* * *
+
+## Class Properties {#class-properties-1}
+
+### `defaultProps` {#defaultprops}
+
+`defaultProps` can be defined as a property on the component class itself, to set the default props for the class. This is used for undefined props, but not for null props. For example:
+
+```js
+class CustomButton extends React.Component {
+  // ...
+}
+
+CustomButton.defaultProps = {
+  color: 'blue'
+};
+```
+
+If `props.color` is not provided, it will be set by default to `'blue'`:
+
+```js
+  render() {
+    return <CustomButton /> ; // props.color will be set to blue
+  }
+```
+
+If `props.color` is set to null, it will remain null:
+
+```js
+  render() {
+    return <CustomButton color={null} /> ; // props.color will remain null
+  }
+```
+
+* * *
+
+### `displayName` {#displayname}
+
+The `displayName` string is used in debugging messages. Usually, you don't need to set it explicitly because it's inferred from the name of the function or class that defines the component. You might want to set it explicitly if you want to display a different name for debugging purposes or when you create a higher-order component, see [Wrap the Display Name for Easy Debugging](/docs/higher-order-components.html#convention-wrap-the-display-name-for-easy-debugging) for details.
+
+* * *
+
+## Instance Properties {#instance-properties-1}
+
+### `props` {#props}
+
+`this.props` contains the props that were defined by the caller of this component. See [Components and Props](/docs/components-and-props.html) for an introduction to props.
+
+In particular, `this.props.children` is a special prop, typically defined by the child tags in the JSX expression rather than in the tag itself.
+
+### `state` {#state}
+
+The state contains data specific to this component that may change over time. The state is user-defined, and it should be a plain JavaScript object.
+
+If some value isn't used for rendering or data flow (for example, a timer ID), you don't have to put it in the state. Such values can be defined as fields on the component instance.
+
+See [State and Lifecycle](/docs/state-and-lifecycle.html) for more information about the state.
+
+Never mutate `this.state` directly, as calling `setState()` afterwards may replace the mutation you made. Treat `this.state` as if it were immutable.
diff --git a/reference-react-dom-server.md b/reference-react-dom-server.md
new file mode 100644
index 000000000..80c030377
--- /dev/null
+++ b/reference-react-dom-server.md
@@ -0,0 +1,92 @@
+---
+id: react-dom-server
+title: ReactDOMServer
+layout: docs
+category: Reference
+permalink: docs/react-dom-server.html
+---
+
+The `ReactDOMServer` object enables you to render components to static markup. Typically, it's used on a Node server:
+
+```js
+// ES modules
+import ReactDOMServer from 'react-dom/server';
+// CommonJS
+var ReactDOMServer = require('react-dom/server');
+```
+
+## Overview {#overview}
+
+The following methods can be used in both the server and browser environments:
+
+- [`renderToString()`](#rendertostring)
+- [`renderToStaticMarkup()`](#rendertostaticmarkup)
+
+These additional methods depend on a package (`stream`) that is **only available on the server**, and won't work in the browser.
+
+- [`renderToNodeStream()`](#rendertonodestream)
+- [`renderToStaticNodeStream()`](#rendertostaticnodestream)
+
+* * *
+
+## Reference {#reference}
+
+### `renderToString()` {#rendertostring}
+
+```javascript
+ReactDOMServer.renderToString(element)
+```
+
+Render a React element to its initial HTML. React will return an HTML string. 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.
+
+* * *
+
+### `renderToStaticMarkup()` {#rendertostaticmarkup}
+
+```javascript
+ReactDOMServer.renderToStaticMarkup(element)
+```
+
+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.
+
+* * *
+
+### `renderToNodeStream()` {#rendertonodestream}
+
+```javascript
+ReactDOMServer.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. 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 at a project like [iconv-lite](https://www.npmjs.com/package/iconv-lite), which provides transform streams for transcoding text.
+
+* * *
+
+### `renderToStaticNodeStream()` {#rendertostaticnodestream}
+
+```javascript
+ReactDOMServer.renderToStaticNodeStream(element)
+```
+
+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 at a project like [iconv-lite](https://www.npmjs.com/package/iconv-lite), which provides transform streams for transcoding text.
diff --git a/reference-react-dom.md b/reference-react-dom.md
new file mode 100644
index 000000000..3732ebe8d
--- /dev/null
+++ b/reference-react-dom.md
@@ -0,0 +1,114 @@
+---
+id: react-dom
+title: ReactDOM
+layout: docs
+category: Reference
+permalink: docs/react-dom.html
+---
+
+If you load React from a `<script>` tag, these top-level APIs are available on the `ReactDOM` global. If you use ES6 with npm, you can write `import ReactDOM from 'react-dom'`. If you use ES5 with npm, you can write `var ReactDOM = require('react-dom')`.
+
+## Overview {#overview}
+
+The `react-dom` package provides DOM-specific methods that can be used at the top level of your app and as an escape hatch to get outside of the React model if you need to. Most of your components should not need to use this module.
+
+- [`render()`](#render)
+- [`hydrate()`](#hydrate)
+- [`unmountComponentAtNode()`](#unmountcomponentatnode)
+- [`findDOMNode()`](#finddomnode)
+- [`createPortal()`](#createportal)
+
+### Browser Support {#browser-support}
+
+React supports all popular browsers, including Internet Explorer 9 and above, although [some polyfills are required](/docs/javascript-environment-requirements.html) for older browsers such as IE 9 and IE 10.
+
+> Note
+>
+> We don't support older browsers that don't support ES5 methods, but you may find that your apps do work in older browsers if polyfills such as [es5-shim and es5-sham](https://github.com/es-shims/es5-shim) are included in the page. You're on your own if you choose to take this path.
+
+* * *
+
+## Reference {#reference}
+
+### `render()` {#render}
+
+```javascript
+ReactDOM.render(element, container[, callback])
+```
+
+Render a React element into the DOM in the supplied `container` and return a [reference](/docs/more-about-refs.html) to the component (or returns `null` for [stateless components](/docs/components-and-props.html#functional-and-class-components)).
+
+If the React element was previously rendered into `container`, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React element.
+
+If the optional callback is provided, it will be executed after the component is rendered or updated.
+
+> Note:
+>
+> `ReactDOM.render()` controls the contents of the container node you pass in. Any existing DOM elements inside are replaced when first called. Later calls use React’s DOM diffing algorithm for efficient updates.
+>
+> `ReactDOM.render()` does not modify the container node (only modifies the children of the container). It may be possible to insert a component to an existing DOM node without overwriting the existing children.
+>
+> `ReactDOM.render()` currently returns a reference to the root `ReactComponent` instance. However, using this return value is legacy
+> and should be avoided because future versions of React may render components asynchronously in some cases. If you need a reference to the root `ReactComponent` instance, the preferred solution is to attach a
+> [callback ref](/docs/more-about-refs.html#the-ref-callback-attribute) to the root element.
+>
+> Using `ReactDOM.render()` to hydrate a server-rendered container is deprecated and will be removed in React 17. Use [`hydrate()`](#hydrate) instead.
+
+* * *
+
+### `hydrate()` {#hydrate}
+
+```javascript
+ReactDOM.hydrate(element, container[, callback])
+```
+
+Same as [`render()`](#render), but is used to hydrate a container whose HTML contents were rendered by [`ReactDOMServer`](/docs/react-dom-server.html). React will attempt to attach event listeners to the existing markup.
+
+React expects that the rendered content is identical between the server and the client. It can patch up differences in text content, but you should treat mismatches as bugs and fix them. In development mode, React warns about mismatches during hydration. There are no guarantees that attribute differences will be patched up in case of mismatches. This is important for performance reasons because in most apps, mismatches are rare, and so validating all markup would be prohibitively expensive.
+
+If a single element's attribute or text content is unavoidably different between the server and the client (for example, a timestamp), you may silence the warning by adding `suppressHydrationWarning={true}` to the element. It only works one level deep, and is intended to be an escape hatch. Don't overuse it. Unless it's text content, React still won't attempt to patch it up, so it may remain inconsistent until future updates.
+
+If you intentionally need to render something different on the server and the client, you can do a two-pass rendering. Components that render something different on the client can read a state variable like `this.state.isClient`, which you can set to `true` in `componentDidMount()`. This way the initial render pass will render the same content as the server, avoiding mismatches, but an additional pass will happen synchronously right after hydration. Note that this approach will make your components slower because they have to render twice, so use it with caution.
+
+Remember to be mindful of user experience on slow connections. The JavaScript code may load significantly later than the initial HTML render, so if you render something different in the client-only pass, the transition can be jarring. However, if executed well, it may be beneficial to render a "shell" of the application on the server, and only show some of the extra widgets on the client. To learn how to do this without getting the markup mismatch issues, refer to the explanation in the previous paragraph.
+
+* * *
+
+### `unmountComponentAtNode()` {#unmountcomponentatnode}
+
+```javascript
+ReactDOM.unmountComponentAtNode(container)
+```
+
+Remove a mounted React component from the DOM and clean up its event handlers and state. If no component was mounted in the container, calling this function does nothing. Returns `true` if a component was unmounted and `false` if there was no component to unmount.
+
+* * *
+
+### `findDOMNode()` {#finddomnode}
+
+> Note:
+>
+> `findDOMNode` is an escape hatch used to access the underlying DOM node. In most cases, use of this escape hatch is discouraged because it pierces the component abstraction. [It has been deprecated in `StrictMode`.](/docs/strict-mode.html#warning-about-deprecated-finddomnode-usage)
+
+```javascript
+ReactDOM.findDOMNode(component)
+```
+If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements. **In most cases, you can attach a ref to the DOM node and avoid using `findDOMNode` at all.**
+
+When a component renders to `null` or `false`, `findDOMNode` returns `null`. When a component renders to a string, `findDOMNode` returns a text DOM node containing that value. As of React 16, a component may return a fragment with multiple children, in which case `findDOMNode` will return the DOM node corresponding to the first non-empty child.
+
+> Note:
+>
+> `findDOMNode` only works on mounted components (that is, components that have been placed in the DOM). If you try to call this on a component that has not been mounted yet (like calling `findDOMNode()` in `render()` on a component that has yet to be created) an exception will be thrown.
+>
+> `findDOMNode` cannot be used on function components.
+
+* * *
+
+### `createPortal()` {#createportal}
+
+```javascript
+ReactDOM.createPortal(child, container)
+```
+
+Creates a portal. Portals provide a way to [render children into a DOM node that exists outside the hierarchy of the DOM component](/docs/portals.html).
diff --git a/reference-react.md b/reference-react.md
new file mode 100644
index 000000000..cdb782dee
--- /dev/null
+++ b/reference-react.md
@@ -0,0 +1,360 @@
+---
+id: react-api
+title: React Top-Level API
+layout: docs
+category: Reference
+permalink: docs/react-api.html
+redirect_from:
+  - "docs/reference.html"
+  - "docs/clone-with-props.html"
+  - "docs/top-level-api.html"
+  - "docs/top-level-api-ja-JP.html"
+  - "docs/top-level-api-ko-KR.html"
+  - "docs/top-level-api-zh-CN.html"
+---
+
+`React` is the entry point to the React library. If you load React from a `<script>` tag, these top-level APIs are available on the `React` global. If you use ES6 with npm, you can write `import React from 'react'`. If you use ES5 with npm, you can write `var React = require('react')`.
+
+## Overview {#overview}
+
+### Components {#components}
+
+React components let you split the UI into independent, reusable pieces, and think about each piece in isolation. React components can be defined by subclassing `React.Component` or `React.PureComponent`.
+
+ - [`React.Component`](#reactcomponent)
+ - [`React.PureComponent`](#reactpurecomponent)
+
+If you don't use ES6 classes, you may use the `create-react-class` module instead. See [Using React without ES6](/docs/react-without-es6.html) for more information.
+
+React components can also be defined as functions which can be wrapped:
+
+- [`React.memo`](#reactmemo)
+
+### Creating React Elements {#creating-react-elements}
+
+We recommend [using JSX](/docs/introducing-jsx.html) to describe what your UI should look like. Each JSX element is just syntactic sugar for calling [`React.createElement()`](#createelement). You will not typically invoke the following methods directly if you are using JSX.
+
+- [`createElement()`](#createelement)
+- [`createFactory()`](#createfactory)
+
+See [Using React without JSX](/docs/react-without-jsx.html) for more information.
+
+### Transforming Elements {#transforming-elements}
+
+`React` provides several APIs for manipulating elements:
+
+- [`cloneElement()`](#cloneelement)
+- [`isValidElement()`](#isvalidelement)
+- [`React.Children`](#reactchildren)
+
+### Fragments {#fragments}
+
+`React` also provides a component for rendering multiple elements without a wrapper.
+
+- [`React.Fragment`](#reactfragment)
+
+### Refs {#refs}
+
+- [`React.createRef`](#reactcreateref)
+- [`React.forwardRef`](#reactforwardref)
+
+### Suspense {#suspense}
+
+Suspense lets components "wait" for something before rendering. Today, Suspense only supports one use case: [loading components dynamically with `React.lazy`](/docs/code-splitting.html#reactlazy). In the future, it will support other use cases like data fetching.
+
+- [`React.lazy`](#reactlazy)
+- [`React.Suspense`](#reactsuspense)
+
+### Hooks {#hooks}
+
+*Hooks* are a new addition in React 16.8. They let you use state and other React features without writing a class. Hooks have a [dedicated docs section](/docs/hooks-intro.html) and a separate API reference:
+
+- [Basic Hooks](/docs/hooks-reference.html#basic-hooks)
+  - [`useState`](/docs/hooks-reference.html#usestate)
+  - [`useEffect`](/docs/hooks-reference.html#useeffect)
+  - [`useContext`](/docs/hooks-reference.html#usecontext)
+- [Additional Hooks](/docs/hooks-reference.html#additional-hooks)
+  - [`useReducer`](/docs/hooks-reference.html#usereducer)
+  - [`useCallback`](/docs/hooks-reference.html#usecallback)
+  - [`useMemo`](/docs/hooks-reference.html#usememo)
+  - [`useRef`](/docs/hooks-reference.html#useref)
+  - [`useImperativeHandle`](/docs/hooks-reference.html#useimperativehandle)
+  - [`useLayoutEffect`](/docs/hooks-reference.html#uselayouteffect)
+  - [`useDebugValue`](/docs/hooks-reference.html#usedebugvalue)
+
+* * *
+
+## Reference {#reference}
+
+### `React.Component` {#reactcomponent}
+
+`React.Component` is the base class for React components when they are defined using [ES6 classes](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Classes):
+
+```javascript
+class Greeting extends React.Component {
+  render() {
+    return <h1>Hello, {this.props.name}</h1>;
+  }
+}
+```
+
+See the [React.Component API Reference](/docs/react-component.html) for a list of methods and properties related to the base `React.Component` class.
+
+* * *
+
+### `React.PureComponent` {#reactpurecomponent}
+
+`React.PureComponent` is similar to [`React.Component`](#reactcomponent). The difference between them is that [`React.Component`](#reactcomponent) doesn't implement [`shouldComponentUpdate()`](/docs/react-component.html#shouldcomponentupdate), but `React.PureComponent` implements it with a shallow prop and state comparison. 
+
+If your React component's `render()` function renders the same result given the same props and state, you can use `React.PureComponent` for a performance boost in some cases.
+
+> Note
+>
+> `React.PureComponent`'s `shouldComponentUpdate()` only shallowly compares the objects. If these contain complex data structures, it may produce false-negatives for deeper differences. Only extend `PureComponent` when you expect to have simple props and state, or use [`forceUpdate()`](/docs/react-component.html#forceupdate) when you know deep data structures have changed. Or, consider using [immutable objects](https://facebook.github.io/immutable-js/) to facilitate fast comparisons of nested data.
+>
+> Furthermore, `React.PureComponent`'s `shouldComponentUpdate()` skips prop updates for the whole component subtree. Make sure all the children components are also "pure".
+
+* * *
+
+### `React.memo` {#reactmemo}
+
+```javascript
+const MyComponent = React.memo(function MyComponent(props) {
+  /* render using props */
+});
+```
+
+`React.memo` is a [higher order component](/docs/higher-order-components.html). It's similar to [`React.PureComponent`](#reactpurecomponent) but for function components instead of classes.
+
+If your function component renders the same result given the same props, you can wrap it in a call to `React.memo` for a performance boost in some cases by memoizing the result. This means that React will skip rendering the component, and reuse the last rendered result.
+
+By default it will only shallowly compare complex objects in the props object. If you want control over the comparison, you can also provide a custom comparison function as the second argument.
+
+```javascript
+function MyComponent(props) {
+  /* render using props */
+}
+function areEqual(prevProps, nextProps) {
+  /*
+  return true if passing nextProps to render would return
+  the same result as passing prevProps to render,
+  otherwise return false
+  */
+}
+export default React.memo(MyComponent, areEqual);
+```
+
+This method only exists as a **[performance optimization](/docs/optimizing-performance.html).** Do not rely on it to "prevent" a render, as this can lead to bugs.
+
+> Note
+>
+> Unlike the [`shouldComponentUpdate()`](/docs/react-component.html#shouldcomponentupdate) method on class components, the `areEqual` function returns `true` if the props are equal and `false` if the props are not equal. This is the inverse from `shouldComponentUpdate`.
+
+* * *
+
+### `createElement()` {#createelement}
+
+```javascript
+React.createElement(
+  type,
+  [props],
+  [...children]
+)
+```
+
+Create and return a new [React element](/docs/rendering-elements.html) of the given type. The type argument can be either a tag name string (such as `'div'` or `'span'`), a [React component](/docs/components-and-props.html) type (a class or a function), or a [React fragment](#reactfragment) type.
+
+Code written with [JSX](/docs/introducing-jsx.html) will be converted to use `React.createElement()`. You will not typically invoke `React.createElement()` directly if you are using JSX. See [React Without JSX](/docs/react-without-jsx.html) to learn more.
+
+* * *
+
+### `cloneElement()` {#cloneelement}
+
+```
+React.cloneElement(
+  element,
+  [props],
+  [...children]
+)
+```
+
+Clone and return a new React element using `element` as the starting point. The resulting element will have the original element's props with the new props merged in shallowly. New children will replace existing children. `key` and `ref` from the original element will be preserved.
+
+`React.cloneElement()` is almost equivalent to:
+
+```js
+<element.type {...element.props} {...props}>{children}</element.type>
+```
+
+However, it also preserves `ref`s. This means that if you get a child with a `ref` on it, you won't accidentally steal it from your ancestor. You will get the same `ref` attached to your new element.
+
+This API was introduced as a replacement of the deprecated `React.addons.cloneWithProps()`.
+
+* * *
+
+### `createFactory()` {#createfactory}
+
+```javascript
+React.createFactory(type)
+```
+
+Return a function that produces React elements of a given type. Like [`React.createElement()`](#createelement), the type argument can be either a tag name string (such as `'div'` or `'span'`), a [React component](/docs/components-and-props.html) type (a class or a function), or a [React fragment](#reactfragment) type.
+
+This helper is considered legacy, and we encourage you to either use JSX or use `React.createElement()` directly instead.
+
+You will not typically invoke `React.createFactory()` directly if you are using JSX. See [React Without JSX](/docs/react-without-jsx.html) to learn more.
+
+* * *
+
+### `isValidElement()` {#isvalidelement}
+
+```javascript
+React.isValidElement(object)
+```
+
+Verifies the object is a React element. Returns `true` or `false`.
+
+* * *
+
+### `React.Children` {#reactchildren}
+
+`React.Children` provides utilities for dealing with the `this.props.children` opaque data structure.
+
+#### `React.Children.map` {#reactchildrenmap}
+
+```javascript
+React.Children.map(children, function[(thisArg)])
+```
+
+Invokes a function on every immediate child contained within `children` with `this` set to `thisArg`. If `children` is an array it will be traversed and the function will be called for each child in the array. If children is `null` or `undefined`, this method will return `null` or `undefined` rather than an array.
+
+> Note
+>
+> If `children` is a `Fragment` it will be treated as a single child and not traversed.
+
+#### `React.Children.forEach` {#reactchildrenforeach}
+
+```javascript
+React.Children.forEach(children, function[(thisArg)])
+```
+
+Like [`React.Children.map()`](#reactchildrenmap) but does not return an array.
+
+#### `React.Children.count` {#reactchildrencount}
+
+```javascript
+React.Children.count(children)
+```
+
+Returns the total number of components in `children`, equal to the number of times that a callback passed to `map` or `forEach` would be invoked.
+
+#### `React.Children.only` {#reactchildrenonly}
+
+```javascript
+React.Children.only(children)
+```
+
+Verifies that `children` has only one child (a React element) and returns it. Otherwise this method throws an error.
+
+> 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.
+
+#### `React.Children.toArray` {#reactchildrentoarray}
+
+```javascript
+React.Children.toArray(children)
+```
+
+Returns the `children` opaque data structure as a flat array with keys assigned to each child. Useful if you want to manipulate collections of children in your render methods, especially if you want to reorder or slice `this.props.children` before passing it down.
+
+> Note:
+>
+> `React.Children.toArray()` changes keys to preserve the semantics of nested arrays when flattening lists of children. That is, `toArray` prefixes each key in the returned array so that each element's key is scoped to the input array containing it.
+
+* * *
+
+### `React.Fragment` {#reactfragment}
+
+The `React.Fragment` component lets you return multiple elements in a `render()` method without creating an additional DOM element:
+
+```javascript
+render() {
+  return (
+    <React.Fragment>
+      Some text.
+      <h2>A heading</h2>
+    </React.Fragment>
+  );
+}
+```
+
+You can also use it with the shorthand `<></>` syntax. For more information, see [React v16.2.0: Improved Support for Fragments](/blog/2017/11/28/react-v16.2.0-fragment-support.html).
+
+
+### `React.createRef` {#reactcreateref}
+
+`React.createRef` creates a [ref](/docs/refs-and-the-dom.html) that can be attached to React elements via the ref attribute.
+`embed:16-3-release-blog-post/create-ref-example.js`
+
+### `React.forwardRef` {#reactforwardref}
+
+`React.forwardRef` creates a React component that forwards the [ref](/docs/refs-and-the-dom.html) attribute it receives to another component below in the tree. This technique is not very common but is particularly useful in two scenarios:
+
+* [Forwarding refs to DOM components](/docs/forwarding-refs.html#forwarding-refs-to-dom-components)
+* [Forwarding refs in higher-order-components](/docs/forwarding-refs.html#forwarding-refs-in-higher-order-components)
+
+`React.forwardRef` accepts a rendering function as an argument. React will call this function with `props` and `ref` as two arguments. This function should return a React node.
+
+`embed:reference-react-forward-ref.js`
+
+In the above example, React passes a `ref` given to `<FancyButton ref={ref}>` element as a second argument to the rendering function inside the `React.forwardRef` call. This rendering function passes the `ref` to the `<button ref={ref}>` element.
+
+As a result, after React attaches the ref, `ref.current` will point directly to the `<button>` DOM element instance.
+
+For more information, see [forwarding refs](/docs/forwarding-refs.html).
+
+### `React.lazy` {#reactlazy}
+
+`React.lazy()` lets you define a component that is loaded dynamically. This helps reduce the bundle size to delay loading components that aren't used during the initial render.
+
+You can learn how to use it from our [code splitting documentation](/docs/code-splitting.html#reactlazy). You might also want to check out [this article](https://medium.com/@pomber/lazy-loading-and-preloading-components-in-react-16-6-804de091c82d) explaining how to use it in more detail.
+
+```js
+// This component is loaded dynamically
+const SomeComponent = React.lazy(() => import('./SomeComponent'));
+```
+
+Note that rendering `lazy` components requires that there's a `<React.Suspense>` component higher in the rendering tree. This is how you specify a loading indicator.
+
+> **Note**
+>
+> Using `React.lazy`with dynamic import requires Promises to be available in the JS environment. This requires a polyfill on IE11 and below.
+
+### `React.Suspense` {#reactsuspense}
+
+`React.Suspense` lets you specify the loading indicator in case some components in the tree below it are not yet ready to render. Today, lazy loading components is the **only** use case supported by `<React.Suspense>`:
+
+```js
+// This component is loaded dynamically
+const OtherComponent = React.lazy(() => import('./OtherComponent'));
+
+function MyComponent() {
+  return (
+    // Displays <Spinner> until OtherComponent loads
+    <React.Suspense fallback={<Spinner />}>
+      <div>
+        <OtherComponent />
+      </div>
+    </React.Suspense>
+  );
+}
+```
+
+It is documented in our [code splitting guide](/docs/code-splitting.html#reactlazy). Note that `lazy` components can be deep inside the `Suspense` tree -- it doesn't have to wrap every one of them. The best practice is to place `<Suspense>` where you want to see a loading indicator, but to use `lazy()` wherever you want to do code splitting.
+
+While this is not supported today, in the future we plan to let `Suspense` handle more scenarios such as data fetching. You can read about this in [our roadmap](/blog/2018/11/27/react-16-roadmap.html).
+
+>Note:
+>
+>`React.lazy()` and `<React.Suspense>` are not yet supported by `ReactDOMServer`. This is a known limitation that will be resolved in the future.
diff --git a/reference-test-renderer.md b/reference-test-renderer.md
new file mode 100644
index 000000000..89312ca8c
--- /dev/null
+++ b/reference-test-renderer.md
@@ -0,0 +1,314 @@
+---
+id: test-renderer
+title: Test Renderer
+permalink: docs/test-renderer.html
+layout: docs
+category: Reference
+---
+
+**Importing**
+
+```javascript
+import TestRenderer from 'react-test-renderer'; // ES6
+const TestRenderer = require('react-test-renderer'); // ES5 with npm
+```
+
+## Overview {#overview}
+
+This package provides a React renderer that can be used to render React components to pure JavaScript objects, without depending on the DOM or a native mobile environment.
+
+Essentially, this package makes it easy to grab a snapshot of the platform view hierarchy (similar to a DOM tree) rendered by a React DOM or React Native component without using a browser or [jsdom](https://github.com/tmpvar/jsdom).
+
+Example:
+
+```javascript
+import TestRenderer from 'react-test-renderer';
+
+function Link(props) {
+  return <a href={props.page}>{props.children}</a>;
+}
+
+const testRenderer = TestRenderer.create(
+  <Link page="https://www.facebook.com/">Facebook</Link>
+);
+
+console.log(testRenderer.toJSON());
+// { type: 'a',
+//   props: { href: 'https://www.facebook.com/' },
+//   children: [ 'Facebook' ] }
+```
+
+You can use Jest's snapshot testing feature to automatically save a copy of the JSON tree to a file and check in your tests that it hasn't changed: [Learn more about it](https://jestjs.io/docs/en/snapshot-testing).
+
+You can also traverse the output to find specific nodes and make assertions about them.
+
+```javascript
+import TestRenderer from 'react-test-renderer';
+
+function MyComponent() {
+  return (
+    <div>
+      <SubComponent foo="bar" />
+      <p className="my">Hello</p>
+    </div>
+  )
+}
+
+function SubComponent() {
+  return (
+    <p className="sub">Sub</p>
+  );
+}
+
+const testRenderer = TestRenderer.create(<MyComponent />);
+const testInstance = testRenderer.root;
+
+expect(testInstance.findByType(SubComponent).props.foo).toBe('bar');
+expect(testInstance.findByProps({className: "sub"}).children).toEqual(['Sub']);
+```
+
+### TestRenderer {#testrenderer}
+
+* [`TestRenderer.create()`](#testrenderercreate)
+* [`TestRenderer.act()`](#testrendereract)
+
+### TestRenderer instance {#testrenderer-instance}
+
+* [`testRenderer.toJSON()`](#testrenderertojson)
+* [`testRenderer.toTree()`](#testrenderertotree)
+* [`testRenderer.update()`](#testrendererupdate)
+* [`testRenderer.unmount()`](#testrendererunmount)
+* [`testRenderer.getInstance()`](#testrenderergetinstance)
+* [`testRenderer.root`](#testrendererroot)
+
+### TestInstance {#testinstance}
+
+* [`testInstance.find()`](#testinstancefind)
+* [`testInstance.findByType()`](#testinstancefindbytype)
+* [`testInstance.findByProps()`](#testinstancefindbyprops)
+* [`testInstance.findAll()`](#testinstancefindall)
+* [`testInstance.findAllByType()`](#testinstancefindallbytype)
+* [`testInstance.findAllByProps()`](#testinstancefindallbyprops)
+* [`testInstance.instance`](#testinstanceinstance)
+* [`testInstance.type`](#testinstancetype)
+* [`testInstance.props`](#testinstanceprops)
+* [`testInstance.parent`](#testinstanceparent)
+* [`testInstance.children`](#testinstancechildren)
+
+## Reference {#reference}
+
+### `TestRenderer.create()` {#testrenderercreate}
+
+```javascript
+TestRenderer.create(element, options);
+```
+
+Create a `TestRenderer` instance with the passed React element. It doesn't use the real DOM, but it still fully renders the component tree into memory so you can make assertions about it. Returns a [TestRenderer instance](#testrenderer-instance).
+
+### `TestRenderer.act()` {#testrendereract}
+
+```javascript
+TestRenderer.act(callback);
+```
+
+Similar to the [`act()` helper from `react-dom/test-utils`](/docs/test-utils.html#act), `TestRenderer.act` prepares a component for assertions. Use this version of `act()` to wrap calls to `TestRenderer.create` and `testRenderer.update`.
+
+```javascript
+import {create, act} from 'react-test-renderer';
+import App from './app.js'; // The component being tested
+
+// render the component
+let root; 
+act(() => {
+  root = create(<App value={1}/>)
+});
+
+// make assertions on root 
+expect(root.toJSON()).toMatchSnapshot();
+
+// update with some different props
+act(() => {
+  root = root.update(<App value={2}/>);
+})
+
+// make assertions on root 
+expect(root.toJSON()).toMatchSnapshot();
+```
+
+### `testRenderer.toJSON()` {#testrenderertojson}
+
+```javascript
+testRenderer.toJSON()
+```
+
+Return an object representing the rendered tree. This tree only contains the platform-specific nodes like `<div>` or `<View>` and their props, but doesn't contain any user-written components. This is handy for [snapshot testing](https://facebook.github.io/jest/docs/en/snapshot-testing.html#snapshot-testing-with-jest).
+
+### `testRenderer.toTree()` {#testrenderertotree}
+
+```javascript
+testRenderer.toTree()
+```
+
+Return an object representing the rendered tree. The representation is more detailed than the one provided by `toJSON()`, and includes the user-written components. You probably don't need this method unless you're writing your own assertion library on top of the test renderer.
+
+### `testRenderer.update()` {#testrendererupdate}
+
+```javascript
+testRenderer.update(element)
+```
+
+Re-render the in-memory tree with a new root element. This simulates a React update at the root. If the new element has the same type and key as the previous element, the tree will be updated; otherwise, it will re-mount a new tree.
+
+### `testRenderer.unmount()` {#testrendererunmount}
+
+```javascript
+testRenderer.unmount()
+```
+
+Unmount the in-memory tree, triggering the appropriate lifecycle events.
+
+### `testRenderer.getInstance()` {#testrenderergetinstance}
+
+```javascript
+testRenderer.getInstance()
+```
+
+Return the instance corresponding to the root element, if available. This will not work if the root element is a function component because they don't have instances.
+
+### `testRenderer.root` {#testrendererroot}
+
+```javascript
+testRenderer.root
+```
+
+Returns the root "test instance" object that is useful for making assertions about specific nodes in the tree. You can use it to find other "test instances" deeper below.
+
+### `testInstance.find()` {#testinstancefind}
+
+```javascript
+testInstance.find(test)
+```
+
+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()` {#testinstancefindbytype}
+
+```javascript
+testInstance.findByType(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()` {#testinstancefindbyprops}
+
+```javascript
+testInstance.findByProps(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.
+
+### `testInstance.findAll()` {#testinstancefindall}
+
+```javascript
+testInstance.findAll(test)
+```
+
+Find all descendant test instances for which `test(testInstance)` returns `true`.
+
+### `testInstance.findAllByType()` {#testinstancefindallbytype}
+
+```javascript
+testInstance.findAllByType(type)
+```
+
+Find all descendant test instances with the provided `type`.
+
+### `testInstance.findAllByProps()` {#testinstancefindallbyprops}
+
+```javascript
+testInstance.findAllByProps(props)
+```
+
+Find all descendant test instances with the provided `props`.
+
+### `testInstance.instance` {#testinstanceinstance}
+
+```javascript
+testInstance.instance
+```
+
+The component instance corresponding to this test instance. It is only available for class components, as function components don't have instances. It matches the `this` value inside the given component.
+
+### `testInstance.type` {#testinstancetype}
+
+```javascript
+testInstance.type
+```
+
+The component type corresponding to this test instance. For example, a `<Button />` component has a type of `Button`.
+
+### `testInstance.props` {#testinstanceprops}
+
+```javascript
+testInstance.props
+```
+
+The props corresponding to this test instance. For example, a `<Button size="small" />` component has `{size: 'small'}` as props.
+
+### `testInstance.parent` {#testinstanceparent}
+
+```javascript
+testInstance.parent
+```
+
+The parent test instance of this test instance.
+
+### `testInstance.children` {#testinstancechildren}
+
+```javascript
+testInstance.children
+```
+
+The children test instances of this test instance.
+
+## Ideas {#ideas}
+
+You can pass `createNodeMock` function to `TestRenderer.create` as the option, which allows for custom mock refs.
+`createNodeMock` accepts the current element and should return a mock ref object.
+This is useful when you test a component that relies on refs.
+
+```javascript
+import TestRenderer from 'react-test-renderer';
+
+class MyComponent extends React.Component {
+  constructor(props) {
+    super(props);
+    this.input = null;
+  }
+  componentDidMount() {
+    this.input.focus();
+  }
+  render() {
+    return <input type="text" ref={el => this.input = el} />
+  }
+}
+
+let focused = false;
+TestRenderer.create(
+  <MyComponent />,
+  {
+    createNodeMock: (element) => {
+      if (element.type === 'input') {
+        // mock a focus function
+        return {
+          focus: () => {
+            focused = true;
+          }
+        };
+      }
+      return null;
+    }
+  }
+);
+expect(focused).toBe(true);
+```
diff --git a/refs-and-the-dom.md b/refs-and-the-dom.md
new file mode 100644
index 000000000..9b56fcc9f
--- /dev/null
+++ b/refs-and-the-dom.md
@@ -0,0 +1,290 @@
+---
+id: refs-and-the-dom
+title: Refs and the DOM
+redirect_from:
+  - "docs/working-with-the-browser.html"
+  - "docs/more-about-refs.html"
+  - "docs/more-about-refs-ko-KR.html"
+  - "docs/more-about-refs-zh-CN.html"
+  - "tips/expose-component-functions.html"
+  - "tips/children-undefined.html"
+permalink: docs/refs-and-the-dom.html
+---
+
+Refs provide a way to access DOM nodes or React elements created in the render method.
+
+In the typical React dataflow, [props](/docs/components-and-props.html) are the only way that parent components interact with their children. To modify a child, you re-render it with new props. However, there are a few cases where you need to imperatively modify a child outside of the typical dataflow. The child to be modified could be an instance of a React component, or it could be a DOM element. For both of these cases, React provides an escape hatch.
+
+### When to Use Refs {#when-to-use-refs}
+
+There are a few good use cases for refs:
+
+* Managing focus, text selection, or media playback.
+* Triggering imperative animations.
+* Integrating with third-party DOM libraries.
+
+Avoid using refs for anything that can be done declaratively.
+
+For example, instead of exposing `open()` and `close()` methods on a `Dialog` component, pass an `isOpen` prop to it.
+
+### Don't Overuse Refs {#dont-overuse-refs}
+
+Your first inclination may be to use refs to "make things happen" in your app. If this is the case, take a moment and think more critically about where state should be owned in the component hierarchy. Often, it becomes clear that the proper place to "own" that state is at a higher level in the hierarchy. See the [Lifting State Up](/docs/lifting-state-up.html) guide for examples of this.
+
+> Note
+>
+> The examples below have been updated to use the `React.createRef()` API introduced in React 16.3. If you are using an earlier release of React, we recommend using [callback refs](#callback-refs) instead.
+
+### Creating Refs {#creating-refs}
+
+Refs are created using `React.createRef()` and attached to React elements via the `ref` attribute. Refs are commonly assigned to an instance property when a component is constructed so they can be referenced throughout the component.
+
+```javascript{4,7}
+class MyComponent extends React.Component {
+  constructor(props) {
+    super(props);
+    this.myRef = React.createRef();
+  }
+  render() {
+    return <div ref={this.myRef} />;
+  }
+}
+```
+
+### Accessing Refs {#accessing-refs}
+
+When a ref is passed to an element in `render`, a reference to the node becomes accessible at the `current` attribute of the ref.
+
+```javascript
+const node = this.myRef.current;
+```
+
+The value of the ref differs depending on the type of the node:
+
+- When the `ref` attribute is used on an HTML element, the `ref` created in the constructor with `React.createRef()` receives the underlying DOM element as its `current` property.
+- When the `ref` attribute is used on a custom class component, the `ref` object receives the mounted instance of the component as its `current`.
+- **You may not use the `ref` attribute on function components** because they don't have instances.
+
+The examples below demonstrate the differences.
+
+#### Adding a Ref to a DOM Element {#adding-a-ref-to-a-dom-element}
+
+This code uses a `ref` to store a reference to a DOM node:
+
+```javascript{5,12,22}
+class CustomTextInput extends React.Component {
+  constructor(props) {
+    super(props);
+    // create a ref to store the textInput DOM element
+    this.textInput = React.createRef();
+    this.focusTextInput = this.focusTextInput.bind(this);
+  }
+
+  focusTextInput() {
+    // Explicitly focus the text input using the raw DOM API
+    // Note: we're accessing "current" to get the DOM node
+    this.textInput.current.focus();
+  }
+
+  render() {
+    // tell React that we want to associate the <input> ref
+    // with the `textInput` that we created in the constructor
+    return (
+      <div>
+        <input
+          type="text"
+          ref={this.textInput} />
+        <input
+          type="button"
+          value="Focus the text input"
+          onClick={this.focusTextInput}
+        />
+      </div>
+    );
+  }
+}
+```
+
+React will assign the `current` property with the DOM element when the component mounts, and assign it back to `null` when it unmounts. `ref` updates happen before `componentDidMount` or `componentDidUpdate` lifecycle methods.
+
+#### Adding a Ref to a Class Component {#adding-a-ref-to-a-class-component}
+
+If we wanted to wrap the `CustomTextInput` above to simulate it being clicked immediately after mounting, we could use a ref to get access to the custom input and call its `focusTextInput` method manually:
+
+```javascript{4,8,13}
+class AutoFocusTextInput extends React.Component {
+  constructor(props) {
+    super(props);
+    this.textInput = React.createRef();
+  }
+
+  componentDidMount() {
+    this.textInput.current.focusTextInput();
+  }
+
+  render() {
+    return (
+      <CustomTextInput ref={this.textInput} />
+    );
+  }
+}
+```
+
+Note that this only works if `CustomTextInput` is declared as a class:
+
+```js{1}
+class CustomTextInput extends React.Component {
+  // ...
+}
+```
+
+#### Refs and Function Components {#refs-and-function-components}
+
+**You may not use the `ref` attribute on function components** because they don't have instances:
+
+```javascript{1,8,13}
+function MyFunctionComponent() {
+  return <input />;
+}
+
+class Parent extends React.Component {
+  constructor(props) {
+    super(props);
+    this.textInput = React.createRef();
+  }
+  render() {
+    // This will *not* work!
+    return (
+      <MyFunctionComponent ref={this.textInput} />
+    );
+  }
+}
+```
+
+You should convert the component to a class if you need a ref to it, just like you do when you need lifecycle methods or state.
+
+You can, however, **use the `ref` attribute inside a function component** as long as you refer to a DOM element or a class component:
+
+```javascript{2,3,6,13}
+function CustomTextInput(props) {
+  // textInput must be declared here so the ref can refer to it
+  let textInput = React.createRef();
+
+  function handleClick() {
+    textInput.current.focus();
+  }
+
+  return (
+    <div>
+      <input
+        type="text"
+        ref={textInput} />
+      <input
+        type="button"
+        value="Focus the text input"
+        onClick={handleClick}
+      />
+    </div>
+  );
+}
+```
+
+### Exposing DOM Refs to Parent Components {#exposing-dom-refs-to-parent-components}
+
+In rare cases, you might want to have access to a child's DOM node from a parent component. This is generally not recommended because it breaks component encapsulation, but it can occasionally be useful for triggering focus or measuring the size or position of a child DOM node.
+
+While you could [add a ref to the child component](#adding-a-ref-to-a-class-component), this is not an ideal solution, as you would only get a component instance rather than a DOM node. Additionally, this wouldn't work with function components.
+
+If you use React 16.3 or higher, we recommend to use [ref forwarding](/docs/forwarding-refs.html) for these cases. **Ref forwarding lets components opt into exposing any child component's ref as their own**. You can find a detailed example of how to expose a child's DOM node to a parent component [in the ref forwarding documentation](/docs/forwarding-refs.html#forwarding-refs-to-dom-components).
+
+If you use React 16.2 or lower, or if you need more flexibility than provided by ref forwarding, you can use [this alternative approach](https://gist.github.com/gaearon/1a018a023347fe1c2476073330cc5509) and explicitly pass a ref as a differently named prop.
+
+When possible, we advise against exposing DOM nodes, but it can be a useful escape hatch. Note that this approach requires you to add some code to the child component. If you have absolutely no control over the child component implementation, your last option is to use [`findDOMNode()`](/docs/react-dom.html#finddomnode), but it is discouraged and deprecated in [`StrictMode`](/docs/strict-mode.html#warning-about-deprecated-finddomnode-usage).
+
+### Callback Refs {#callback-refs}
+
+React also supports another way to set refs called "callback refs", which gives more fine-grain control over when refs are set and unset.
+
+Instead of passing a `ref` attribute created by `createRef()`, you pass a function. The function receives the React component instance or HTML DOM element as its argument, which can be stored and accessed elsewhere. 
+
+The example below implements a common pattern: using the `ref` callback to store a reference to a DOM node in an instance property.
+
+```javascript{5,7-9,11-14,19,29,34}
+class CustomTextInput extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.textInput = null;
+
+    this.setTextInputRef = element => {
+      this.textInput = element;
+    };
+
+    this.focusTextInput = () => {
+      // Focus the text input using the raw DOM API
+      if (this.textInput) this.textInput.focus();
+    };
+  }
+
+  componentDidMount() {
+    // autofocus the input on mount
+    this.focusTextInput();
+  }
+
+  render() {
+    // Use the `ref` callback to store a reference to the text input DOM
+    // element in an instance field (for example, this.textInput).
+    return (
+      <div>
+        <input
+          type="text"
+          ref={this.setTextInputRef}
+        />
+        <input
+          type="button"
+          value="Focus the text input"
+          onClick={this.focusTextInput}
+        />
+      </div>
+    );
+  }
+}
+```
+
+React will call the `ref` callback with the DOM element when the component mounts, and call it with `null` when it unmounts. Refs are guaranteed to be up-to-date before `componentDidMount` or `componentDidUpdate` fires.
+
+You can pass callback refs between components like you can with object refs that were created with `React.createRef()`.
+
+```javascript{4,13}
+function CustomTextInput(props) {
+  return (
+    <div>
+      <input ref={props.inputRef} />
+    </div>
+  );
+}
+
+class Parent extends React.Component {
+  render() {
+    return (
+      <CustomTextInput
+        inputRef={el => this.inputElement = el}
+      />
+    );
+  }
+}
+```
+
+In the example above, `Parent` passes its ref callback as an `inputRef` prop to the `CustomTextInput`, and the `CustomTextInput` passes the same function as a special `ref` attribute to the `<input>`. As a result, `this.inputElement` in `Parent` will be set to the DOM node corresponding to the `<input>` element in the `CustomTextInput`.
+
+### Legacy API: String Refs {#legacy-api-string-refs}
+
+If you worked with React before, you might be familiar with an older API where the `ref` attribute is a string, like `"textInput"`, and the DOM node is accessed as `this.refs.textInput`. We advise against it because string refs have [some issues](https://github.com/facebook/react/pull/8333#issuecomment-271648615), are considered legacy, and **are likely to be removed in one of the future releases**. 
+
+> Note
+>
+> If you're currently using `this.refs.textInput` to access refs, we recommend using either the [callback pattern](#callback-refs) or the [`createRef` API](#creating-refs) instead.
+
+### Caveats with callback refs {#caveats-with-callback-refs}
+
+If the `ref` callback is defined as an inline function, it will get called twice during updates, first with `null` and then again with the DOM element. This is because a new instance of the function is created with each render, so React needs to clear the old ref and set up the new one. You can avoid this by defining the `ref` callback as a bound method on the class, but note that it shouldn't matter in most cases.
diff --git a/render-props.md b/render-props.md
new file mode 100644
index 000000000..f680cb724
--- /dev/null
+++ b/render-props.md
@@ -0,0 +1,325 @@
+---
+id: render-props
+title: Render Props
+permalink: docs/render-props.html
+---
+
+The term ["render prop"](https://cdb.reacttraining.com/use-a-render-prop-50de598f11ce) refers to a technique for sharing code between React components using a prop whose value is a function.
+
+A component with a render prop takes a function that returns a React element and calls it instead of implementing its own render logic.
+
+```jsx
+<DataProvider render={data => (
+  <h1>Hello {data.target}</h1>
+)}/>
+```
+
+Libraries that use render props include [React Router](https://reacttraining.com/react-router/web/api/Route/render-func), [Downshift](https://github.com/paypal/downshift) and [Formik](https://github.com/jaredpalmer/formik).
+
+In this document, we’ll discuss why render props are useful, and how to write your own.
+
+## Use Render Props for Cross-Cutting Concerns {#use-render-props-for-cross-cutting-concerns}
+
+Components are the primary unit of code reuse in React, but it's not always obvious how to share the state or behavior that one component encapsulates to other components that need that same state.
+
+For example, the following component tracks the mouse position in a web app:
+
+```js
+class MouseTracker extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleMouseMove = this.handleMouseMove.bind(this);
+    this.state = { x: 0, y: 0 };
+  }
+
+  handleMouseMove(event) {
+    this.setState({
+      x: event.clientX,
+      y: event.clientY
+    });
+  }
+
+  render() {
+    return (
+      <div style={{ height: '100%' }} onMouseMove={this.handleMouseMove}>
+        <h1>Move the mouse around!</h1>
+        <p>The current mouse position is ({this.state.x}, {this.state.y})</p>
+      </div>
+    );
+  }
+}
+```
+
+As the cursor moves around the screen, the component displays its (x, y) coordinates in a `<p>`.
+
+Now the question is: How can we reuse this behavior in another component? In other words, if another component needs to know about the cursor position, can we encapsulate that behavior so that we can easily share it with that component?
+
+Since components are the basic unit of code reuse in React, let's try refactoring the code a bit to use a `<Mouse>` component that encapsulates the behavior we need to reuse elsewhere.
+
+```js
+// The <Mouse> component encapsulates the behavior we need...
+class Mouse extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleMouseMove = this.handleMouseMove.bind(this);
+    this.state = { x: 0, y: 0 };
+  }
+
+  handleMouseMove(event) {
+    this.setState({
+      x: event.clientX,
+      y: event.clientY
+    });
+  }
+
+  render() {
+    return (
+      <div style={{ height: '100%' }} onMouseMove={this.handleMouseMove}>
+
+        {/* ...but how do we render something other than a <p>? */}
+        <p>The current mouse position is ({this.state.x}, {this.state.y})</p>
+      </div>
+    );
+  }
+}
+
+class MouseTracker extends React.Component {
+  render() {
+    return (
+      <div>
+        <h1>Move the mouse around!</h1>
+        <Mouse />
+      </div>
+    );
+  }
+}
+```
+
+Now the `<Mouse>` component encapsulates all behavior associated with listening for `mousemove` events and storing the (x, y) position of the cursor, but it's not yet truly reusable.
+
+For example, let's say we have a `<Cat>` component that renders the image of a cat chasing the mouse around the screen. We might use a `<Cat mouse={{ x, y }}>` prop to tell the component the coordinates of the mouse so it knows where to position the image on the screen.
+
+As a first pass, you might try rendering the `<Cat>` *inside `<Mouse>`'s `render` method*, like this:
+
+```js
+class Cat extends React.Component {
+  render() {
+    const mouse = this.props.mouse;
+    return (
+      <img src="/cat.jpg" style={{ position: 'absolute', left: mouse.x, top: mouse.y }} />
+    );
+  }
+}
+
+class MouseWithCat extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleMouseMove = this.handleMouseMove.bind(this);
+    this.state = { x: 0, y: 0 };
+  }
+
+  handleMouseMove(event) {
+    this.setState({
+      x: event.clientX,
+      y: event.clientY
+    });
+  }
+
+  render() {
+    return (
+      <div style={{ height: '100%' }} onMouseMove={this.handleMouseMove}>
+
+        {/*
+          We could just swap out the <p> for a <Cat> here ... but then
+          we would need to create a separate <MouseWithSomethingElse>
+          component every time we need to use it, so <MouseWithCat>
+          isn't really reusable yet.
+        */}
+        <Cat mouse={this.state} />
+      </div>
+    );
+  }
+}
+
+class MouseTracker extends React.Component {
+  render() {
+    return (
+      <div>
+        <h1>Move the mouse around!</h1>
+        <MouseWithCat />
+      </div>
+    );
+  }
+}
+```
+
+This approach will work for our specific use case, but we haven't achieved the objective of truly encapsulating the behavior in a reusable way. Now, every time we want the mouse position for a different use case, we have to create a new component (i.e. essentially another `<MouseWithCat>`) that renders something specifically for that use case.
+
+Here's where the render prop comes in: Instead of hard-coding a `<Cat>` inside a `<Mouse>` component, and effectively changing its rendered output, we can provide `<Mouse>` with a function prop that it uses to dynamically determine what to render–a render prop.
+
+```js
+class Cat extends React.Component {
+  render() {
+    const mouse = this.props.mouse;
+    return (
+      <img src="/cat.jpg" style={{ position: 'absolute', left: mouse.x, top: mouse.y }} />
+    );
+  }
+}
+
+class Mouse extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleMouseMove = this.handleMouseMove.bind(this);
+    this.state = { x: 0, y: 0 };
+  }
+
+  handleMouseMove(event) {
+    this.setState({
+      x: event.clientX,
+      y: event.clientY
+    });
+  }
+
+  render() {
+    return (
+      <div style={{ height: '100%' }} onMouseMove={this.handleMouseMove}>
+
+        {/*
+          Instead of providing a static representation of what <Mouse> renders,
+          use the `render` prop to dynamically determine what to render.
+        */}
+        {this.props.render(this.state)}
+      </div>
+    );
+  }
+}
+
+class MouseTracker extends React.Component {
+  render() {
+    return (
+      <div>
+        <h1>Move the mouse around!</h1>
+        <Mouse render={mouse => (
+          <Cat mouse={mouse} />
+        )}/>
+      </div>
+    );
+  }
+}
+```
+
+Now, instead of effectively cloning the `<Mouse>` component and hard-coding something else in its `render` method to solve for a specific use case, we provide a `render` prop that `<Mouse>` can use to dynamically determine what it renders.
+
+More concretely, **a render prop is a function prop that a component uses to know what to render.**
+
+This technique makes the behavior that we need to share extremely portable. To get that behavior, render a `<Mouse>` with a `render` prop that tells it what to render with the current (x, y) of the cursor.
+
+One interesting thing to note about render props is that you can implement most [higher-order components](/docs/higher-order-components.html) (HOC) using a regular component with a render prop. For example, if you would prefer to have a `withMouse` HOC instead of a `<Mouse>` component, you could easily create one using a regular `<Mouse>` with a render prop:
+
+```js
+// If you really want a HOC for some reason, you can easily
+// create one using a regular component with a render prop!
+function withMouse(Component) {
+  return class extends React.Component {
+    render() {
+      return (
+        <Mouse render={mouse => (
+          <Component {...this.props} mouse={mouse} />
+        )}/>
+      );
+    }
+  }
+}
+```
+
+So using a render prop makes it possible to use either pattern.
+
+## Using Props Other Than `render` {#using-props-other-than-render}
+
+It's important to remember that just because the pattern is called "render props" you don't *have to use a prop named `render` to use this pattern*. In fact, [*any* prop that is a function that a component uses to know what to render is technically a "render prop"](https://cdb.reacttraining.com/use-a-render-prop-50de598f11ce).
+
+Although the examples above use `render`, we could just as easily use the `children` prop!
+
+```js
+<Mouse children={mouse => (
+  <p>The mouse position is {mouse.x}, {mouse.y}</p>
+)}/>
+```
+
+And remember, the `children` prop doesn't actually need to be named in the list of "attributes" in your JSX element. Instead, you can put it directly *inside* the element!
+
+```js
+<Mouse>
+  {mouse => (
+    <p>The mouse position is {mouse.x}, {mouse.y}</p>
+  )}
+</Mouse>
+```
+
+You'll see this technique used in the [react-motion](https://github.com/chenglou/react-motion) API.
+
+Since this technique is a little unusual, you'll probably want to explicitly state that `children` should be a function in your `propTypes` when designing an API like this.
+
+```js
+Mouse.propTypes = {
+  children: PropTypes.func.isRequired
+};
+```
+
+## Caveats {#caveats}
+
+### Be careful when using Render Props with React.PureComponent {#be-careful-when-using-render-props-with-reactpurecomponent}
+
+Using a render prop can negate the advantage that comes from using [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) if you create the function inside a `render` method. This is because the shallow prop comparison will always return `false` for new props, and each `render` in this case will generate a new value for the render prop.
+
+For example, continuing with our `<Mouse>` component from above, if `Mouse` were to extend `React.PureComponent` instead of `React.Component`, our example would look like this:
+
+```js
+class Mouse extends React.PureComponent {
+  // Same implementation as above...
+}
+
+class MouseTracker extends React.Component {
+  render() {
+    return (
+      <div>
+        <h1>Move the mouse around!</h1>
+
+        {/*
+          This is bad! The value of the `render` prop will
+          be different on each render.
+        */}
+        <Mouse render={mouse => (
+          <Cat mouse={mouse} />
+        )}/>
+      </div>
+    );
+  }
+}
+```
+
+In this example, each time `<MouseTracker>` renders, it generates a new function as the value of the `<Mouse render>` prop, thus negating the effect of `<Mouse>` extending `React.PureComponent` in the first place!
+
+To get around this problem, you can sometimes define the prop as an instance method, like so:
+
+```js
+class MouseTracker extends React.Component {
+  // Defined as an instance method, `this.renderTheCat` always
+  // refers to *same* function when we use it in render
+  renderTheCat(mouse) {
+    return <Cat mouse={mouse} />;
+  }
+
+  render() {
+    return (
+      <div>
+        <h1>Move the mouse around!</h1>
+        <Mouse render={this.renderTheCat} />
+      </div>
+    );
+  }
+}
+```
+
+In cases where you cannot define the prop statically (e.g. because you need to close over the component's props and/or state) `<Mouse>` should extend `React.Component` instead.
diff --git a/rendering-elements.md b/rendering-elements.md
new file mode 100644
index 000000000..9ae99c92f
--- /dev/null
+++ b/rendering-elements.md
@@ -0,0 +1,76 @@
+---
+id: rendering-elements
+title: रेंडरिंग एलिमेंट्स
+permalink: docs/rendering-elements.html
+redirect_from:
+  - "docs/displaying-data.html"
+prev: introducing-jsx.html
+next: components-and-props.html
+---
+
+एलिमेंट्स रिएक्ट ऐप्स के सबसे छोटे बिल्डिंग ब्लॉक हैं।
+
+एक एलिमेंट वर्णन करता है कि आप स्क्रीन पर क्या देखना चाहते हैं:      
+
+```js
+const element = <h1>Hello, world</h1>;
+```
+
+ब्राउज़र DOM एलिमेंट्स के विपरीत, React एलिमेंट्स प्लेन ऑब्जेक्ट है और इन्हें बनाना आसान है। React DOM React एलिमेंट्स के अनुसार DOM को अपडेट रखता है।
+
+>**ध्यान दें:**
+>
+> आप एलिमेंट्स को बहुचर्चित "कौम्पोनॅन्टस" समझ कर भ्रमित हो सकते है, हम कौम्पोनॅन्टस के बारे में [अगले भाग](/docs/components-and-props.html) में बतायेंगे। एलिमेंट्स वो है जिनका उपयोग करके एक कौम्पोनॅन्ट को बनाया जाता है। आगे बढ़ने से पहले हम इस भाग को पड़ने की सलाह देते हैं।
+
+## DOM में एक एलिमेंट रेंडर करना {#rendering-an-element-into-the-dom}
+
+मान लीजिए की आपकी HTML फ़ाइल में कहीं एक `<div>` है:
+
+```html
+<div id="root"></div>
+```
+
+हम इसे "रूट" DOM नोड कहते है क्यूँकि इसके अंदर की सारी चीज़ें React DOM के द्वारा संचालित होगी।
+
+
+React के उपयोग से बने ज़्यादातर ऐप्लिकेशन में एक ही रूट DOM नोड होता है। परंतु यदि आप React को किसी पहले से बने हुए app में उपयोग करना चाहते है तो आप कितने भी अलग अलग रूट DOM नोड बना सकते है।
+
+एक React एलिमेंट्स को DOM नोड में दर्शाने के लिए, आपको इन दोनो को `ReactDOM.render()` में भेजना पड़ेगा:
+
+`embed:rendering-elements/render-an-element.js`
+
+[](codepen://rendering-elements/render-an-element)
+
+ये "Hello world" को पेज पर दर्शाता है।
+
+## पहले से बने एलेमेंट को अपडेट करना {#updating-the-rendered-element}
+
+React एलिमेंट्स [अचल](https://en.wikipedia.org/wiki/Immutable_object) होते है। एक बार एलेमेंट के बनने के बाद, आप उसके चिल्ड्रन या ऐट्रिब्यूट्स में परिवर्तन नहीं कर सकते। एक एलेमेंट एक चलचित्र के एक दृश्य के समान है, ये UI को एक निश्चित समय के लिए दर्शाता है।
+
+हमारे अब तक के ज्ञान के अनुसार, UI में परिवर्तन करने का एक ही तरीक़ा है। इसके लिए हमें एक नया एलेमेंट बना कर उसे `ReactDOM.render()` को भेजना पड़ेगा।
+
+इस टिकिंग घड़ी उदाहरण पर विचार करें:
+
+`embed:rendering-elements/update-rendered-element.js`
+
+[](codepen://rendering-elements/update-rendered-element)
+
+ये `ReactDOM.render()` को प्रत्येक सेकंड [`setInterval()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/setInterval) callback से कॉल करता है।
+
+>**ध्यान दें:**
+>
+>व्यवहार में, ज़्यादातर React ऍप्स `ReactDOM.render()` को एक ही बार कॉल करते है। अगले भाग में हम ये सीखेंगे कि कैसे इस तरह के कोड को [stateful components](/docs/state-and-lifecycle.html) में एन्काप्सुलेट करते है।
+>
+>हम अनुशंसा करते हैं कि आप विषयों को छोड़ें नहीं क्योंकि वे एक-दूसरे पर निर्माण करते हैं।
+
+## React वही अपडेट करता है जो आवश्यक है {#react-only-updates-whats-necessary}
+
+React, DOM एलिमेंट्स और उसके चिल्डरेंस की तुलना उसके पहले की अवस्था से करता है और केवल उन्ही चीज़ों में परिवर्तन करता जिससे की DOM अपने चाहे state में आ जाए। 
+
+आप ब्राउज़र टूलस की सहायता से [अंतिम उदाहरण](codepen://rendering-elements/update-rendered-element) का निरीक्षण करके सत्यापित कर सकते हैं:
+
+![DOM inspector showing granular updates](../images/docs/granular-dom-updates.gif)
+
+भले ही हम हर टिक पर पूरे UI ट्री का वर्णन करने वाला एक एलेमेंट बनाते हैं, लेकिन केवल टेक्स्ट नोड जिसकी सामग्री बदल गई है वह React DOM द्वारा अपडेट हो जाता है।
+
+हमारे अनुभव से, UI को कैसे अप्डेट करना है के बिपरीत यदि हम ये सोचे की UI को किसी समय कैसे दिखाना है तो हम बहुत सारी बग से बच सकते है।
diff --git a/state-and-lifecycle.md b/state-and-lifecycle.md
new file mode 100644
index 000000000..e3ddafa28
--- /dev/null
+++ b/state-and-lifecycle.md
@@ -0,0 +1,467 @@
+---
+id: state-and-lifecycle
+title: State and Lifecycle
+permalink: docs/state-and-lifecycle.html
+redirect_from:
+  - "docs/interactivity-and-dynamic-uis.html"
+prev: components-and-props.html
+next: handling-events.html
+---
+
+This page introduces the concept of state and lifecycle in a React component. You can find a [detailed component API reference here](/docs/react-component.html).
+
+Consider the ticking clock example from [one of the previous sections](/docs/rendering-elements.html#updating-the-rendered-element). In [Rendering Elements](/docs/rendering-elements.html#rendering-an-element-into-the-dom), we have only learned one way to update the UI. We call `ReactDOM.render()` to change the rendered output:
+
+```js{8-11}
+function tick() {
+  const element = (
+    <div>
+      <h1>Hello, world!</h1>
+      <h2>It is {new Date().toLocaleTimeString()}.</h2>
+    </div>
+  );
+  ReactDOM.render(
+    element,
+    document.getElementById('root')
+  );
+}
+
+setInterval(tick, 1000);
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/gwoJZk?editors=0010)
+
+In this section, we will learn how to make the `Clock` component truly reusable and encapsulated. It will set up its own timer and update itself every second.
+
+We can start by encapsulating how the clock looks:
+
+```js{3-6,12}
+function Clock(props) {
+  return (
+    <div>
+      <h1>Hello, world!</h1>
+      <h2>It is {props.date.toLocaleTimeString()}.</h2>
+    </div>
+  );
+}
+
+function tick() {
+  ReactDOM.render(
+    <Clock date={new Date()} />,
+    document.getElementById('root')
+  );
+}
+
+setInterval(tick, 1000);
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/dpdoYR?editors=0010)
+
+However, it misses a crucial requirement: the fact that the `Clock` sets up a timer and updates the UI every second should be an implementation detail of the `Clock`.
+
+Ideally we want to write this once and have the `Clock` update itself:
+
+```js{2}
+ReactDOM.render(
+  <Clock />,
+  document.getElementById('root')
+);
+```
+
+To implement this, we need to add "state" to the `Clock` component.
+
+State is similar to props, but it is private and fully controlled by the component.
+
+## Converting a Function to a Class {#converting-a-function-to-a-class}
+
+You can convert a function component like `Clock` to a class in five steps:
+
+1. Create an [ES6 class](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Classes), with the same name, that extends `React.Component`.
+
+2. Add a single empty method to it called `render()`.
+
+3. Move the body of the function into the `render()` method.
+
+4. Replace `props` with `this.props` in the `render()` body.
+
+5. Delete the remaining empty function declaration.
+
+```js
+class Clock extends React.Component {
+  render() {
+    return (
+      <div>
+        <h1>Hello, world!</h1>
+        <h2>It is {this.props.date.toLocaleTimeString()}.</h2>
+      </div>
+    );
+  }
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/zKRGpo?editors=0010)
+
+`Clock` is now defined as a class rather than a function.
+
+The `render` method will be called each time an update happens, but as long as we render `<Clock />` into the same DOM node, only a single instance of the `Clock` class will be used. This lets us use additional features such as local state and lifecycle methods.
+
+## Adding Local State to a Class {#adding-local-state-to-a-class}
+
+We will move the `date` from props to state in three steps:
+
+1) Replace `this.props.date` with `this.state.date` in the `render()` method:
+
+```js{6}
+class Clock extends React.Component {
+  render() {
+    return (
+      <div>
+        <h1>Hello, world!</h1>
+        <h2>It is {this.state.date.toLocaleTimeString()}.</h2>
+      </div>
+    );
+  }
+}
+```
+
+2) Add a [class constructor](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Classes#Constructor) that assigns the initial `this.state`:
+
+```js{4}
+class Clock extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {date: new Date()};
+  }
+
+  render() {
+    return (
+      <div>
+        <h1>Hello, world!</h1>
+        <h2>It is {this.state.date.toLocaleTimeString()}.</h2>
+      </div>
+    );
+  }
+}
+```
+
+Note how we pass `props` to the base constructor:
+
+```js{2}
+  constructor(props) {
+    super(props);
+    this.state = {date: new Date()};
+  }
+```
+
+Class components should always call the base constructor with `props`.
+
+3) Remove the `date` prop from the `<Clock />` element:
+
+```js{2}
+ReactDOM.render(
+  <Clock />,
+  document.getElementById('root')
+);
+```
+
+We will later add the timer code back to the component itself.
+
+The result looks like this:
+
+```js{2-5,11,18}
+class Clock extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {date: new Date()};
+  }
+
+  render() {
+    return (
+      <div>
+        <h1>Hello, world!</h1>
+        <h2>It is {this.state.date.toLocaleTimeString()}.</h2>
+      </div>
+    );
+  }
+}
+
+ReactDOM.render(
+  <Clock />,
+  document.getElementById('root')
+);
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/KgQpJd?editors=0010)
+
+Next, we'll make the `Clock` set up its own timer and update itself every second.
+
+## Adding Lifecycle Methods to a Class {#adding-lifecycle-methods-to-a-class}
+
+In applications with many components, it's very important to free up resources taken by the components when they are destroyed.
+
+We want to [set up a timer](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/setInterval) whenever the `Clock` is rendered to the DOM for the first time. This is called "mounting" in React.
+
+We also want to [clear that timer](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/clearInterval) whenever the DOM produced by the `Clock` is removed. This is called "unmounting" in React.
+
+We can declare special methods on the component class to run some code when a component mounts and unmounts:
+
+```js{7-9,11-13}
+class Clock extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {date: new Date()};
+  }
+
+  componentDidMount() {
+
+  }
+
+  componentWillUnmount() {
+
+  }
+
+  render() {
+    return (
+      <div>
+        <h1>Hello, world!</h1>
+        <h2>It is {this.state.date.toLocaleTimeString()}.</h2>
+      </div>
+    );
+  }
+}
+```
+
+These methods are called "lifecycle methods".
+
+The `componentDidMount()` method runs after the component output has been rendered to the DOM. This is a good place to set up a timer:
+
+```js{2-5}
+  componentDidMount() {
+    this.timerID = setInterval(
+      () => this.tick(),
+      1000
+    );
+  }
+```
+
+Note how we save the timer ID right on `this` (`this.timerID`).
+
+While `this.props` is set up by React itself and `this.state` has a special meaning, you are free to add additional fields to the class manually if you need to store something that doesn’t participate in the data flow (like a timer ID).
+
+We will tear down the timer in the `componentWillUnmount()` lifecycle method:
+
+```js{2}
+  componentWillUnmount() {
+    clearInterval(this.timerID);
+  }
+```
+
+Finally, we will implement a method called `tick()` that the `Clock` component will run every second.
+
+It will use `this.setState()` to schedule updates to the component local state:
+
+```js{18-22}
+class Clock extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {date: new Date()};
+  }
+
+  componentDidMount() {
+    this.timerID = setInterval(
+      () => this.tick(),
+      1000
+    );
+  }
+
+  componentWillUnmount() {
+    clearInterval(this.timerID);
+  }
+
+  tick() {
+    this.setState({
+      date: new Date()
+    });
+  }
+
+  render() {
+    return (
+      <div>
+        <h1>Hello, world!</h1>
+        <h2>It is {this.state.date.toLocaleTimeString()}.</h2>
+      </div>
+    );
+  }
+}
+
+ReactDOM.render(
+  <Clock />,
+  document.getElementById('root')
+);
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/amqdNA?editors=0010)
+
+Now the clock ticks every second.
+
+Let's quickly recap what's going on and the order in which the methods are called:
+
+1) When `<Clock />` is passed to `ReactDOM.render()`, React calls the constructor of the `Clock` component. Since `Clock` needs to display the current time, it initializes `this.state` with an object including the current time. We will later update this state.
+
+2) React then calls the `Clock` component's `render()` method. This is how React learns what should be displayed on the screen. React then updates the DOM to match the `Clock`'s render output.
+
+3) When the `Clock` output is inserted in the DOM, React calls the `componentDidMount()` lifecycle method. Inside it, the `Clock` component asks the browser to set up a timer to call the component's `tick()` method once a second.
+
+4) Every second the browser calls the `tick()` method. Inside it, the `Clock` component schedules a UI update by calling `setState()` with an object containing the current time. Thanks to the `setState()` call, React knows the state has changed, and calls the `render()` method again to learn what should be on the screen. This time, `this.state.date` in the `render()` method will be different, and so the render output will include the updated time. React updates the DOM accordingly.
+
+5) If the `Clock` component is ever removed from the DOM, React calls the `componentWillUnmount()` lifecycle method so the timer is stopped.
+
+## Using State Correctly {#using-state-correctly}
+
+There are three things you should know about `setState()`.
+
+### Do Not Modify State Directly {#do-not-modify-state-directly}
+
+For example, this will not re-render a component:
+
+```js
+// Wrong
+this.state.comment = 'Hello';
+```
+
+Instead, use `setState()`:
+
+```js
+// Correct
+this.setState({comment: 'Hello'});
+```
+
+The only place where you can assign `this.state` is the constructor.
+
+### State Updates May Be Asynchronous {#state-updates-may-be-asynchronous}
+
+React may batch multiple `setState()` calls into a single update for performance.
+
+Because `this.props` and `this.state` may be updated asynchronously, you should not rely on their values for calculating the next state.
+
+For example, this code may fail to update the counter:
+
+```js
+// Wrong
+this.setState({
+  counter: this.state.counter + this.props.increment,
+});
+```
+
+To fix it, use a second form of `setState()` that accepts a function rather than an object. That function will receive the previous state as the first argument, and the props at the time the update is applied as the second argument:
+
+```js
+// Correct
+this.setState((state, props) => ({
+  counter: state.counter + props.increment
+}));
+```
+
+We used an [arrow function](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Functions/Arrow_functions) above, but it also works with regular functions:
+
+```js
+// Correct
+this.setState(function(state, props) {
+  return {
+    counter: state.counter + props.increment
+  };
+});
+```
+
+### State Updates are Merged {#state-updates-are-merged}
+
+When you call `setState()`, React merges the object you provide into the current state.
+
+For example, your state may contain several independent variables:
+
+```js{4,5}
+  constructor(props) {
+    super(props);
+    this.state = {
+      posts: [],
+      comments: []
+    };
+  }
+```
+
+Then you can update them independently with separate `setState()` calls:
+
+```js{4,10}
+  componentDidMount() {
+    fetchPosts().then(response => {
+      this.setState({
+        posts: response.posts
+      });
+    });
+
+    fetchComments().then(response => {
+      this.setState({
+        comments: response.comments
+      });
+    });
+  }
+```
+
+The merging is shallow, so `this.setState({comments})` leaves `this.state.posts` intact, but completely replaces `this.state.comments`.
+
+## The Data Flows Down {#the-data-flows-down}
+
+Neither parent nor child components can know if a certain component is stateful or stateless, and they shouldn't care whether it is defined as a function or a class.
+
+This is why state is often called local or encapsulated. It is not accessible to any component other than the one that owns and sets it.
+
+A component may choose to pass its state down as props to its child components:
+
+```js
+<h2>It is {this.state.date.toLocaleTimeString()}.</h2>
+```
+
+This also works for user-defined components:
+
+```js
+<FormattedDate date={this.state.date} />
+```
+
+The `FormattedDate` component would receive the `date` in its props and wouldn't know whether it came from the `Clock`'s state, from the `Clock`'s props, or was typed by hand:
+
+```js
+function FormattedDate(props) {
+  return <h2>It is {props.date.toLocaleTimeString()}.</h2>;
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/zKRqNB?editors=0010)
+
+This is commonly called a "top-down" or "unidirectional" data flow. Any state is always owned by some specific component, and any data or UI derived from that state can only affect components "below" them in the tree.
+
+If you imagine a component tree as a waterfall of props, each component's state is like an additional water source that joins it at an arbitrary point but also flows down.
+
+To show that all components are truly isolated, we can create an `App` component that renders three `<Clock>`s:
+
+```js{4-6}
+function App() {
+  return (
+    <div>
+      <Clock />
+      <Clock />
+      <Clock />
+    </div>
+  );
+}
+
+ReactDOM.render(
+  <App />,
+  document.getElementById('root')
+);
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/vXdGmd?editors=0010)
+
+Each `Clock` sets up its own timer and updates independently.
+
+In React apps, whether a component is stateful or stateless is considered an implementation detail of the component that may change over time. You can use stateless components inside stateful components, and vice versa.
diff --git a/static-type-checking.md b/static-type-checking.md
new file mode 100644
index 000000000..ed35a9503
--- /dev/null
+++ b/static-type-checking.md
@@ -0,0 +1,333 @@
+---
+id: static-type-checking
+title: Static Type Checking
+permalink: docs/static-type-checking.html
+---
+
+Static type checkers like [Flow](https://flow.org/) and [TypeScript](https://www.typescriptlang.org/) identify certain types of problems before you even run your code. They can also improve developer workflow by adding features like auto-completion. For this reason, we recommend using Flow or TypeScript instead of `PropTypes` for larger code bases.
+
+## Flow {#flow}
+
+[Flow](https://flow.org/) is a static type checker for your JavaScript code. It is developed at Facebook and is often used with React. It lets you annotate the variables, functions, and React components with a special type syntax, and catch mistakes early. You can read an [introduction to Flow](https://flow.org/en/docs/getting-started/) to learn its basics.
+
+To use Flow, you need to:
+
+* Add Flow to your project as a dependency.
+* Ensure that Flow syntax is stripped from the compiled code.
+* Add type annotations and run Flow to check them.
+
+We will explain these steps below in detail.
+
+### Adding Flow to a Project {#adding-flow-to-a-project}
+
+First, navigate to your project directory in the terminal. You will need to run the following command:
+
+If you use [Yarn](https://yarnpkg.com/), run:
+
+```bash
+yarn add --dev flow-bin
+```
+
+If you use [npm](https://www.npmjs.com/), run:
+
+```bash
+npm install --save-dev flow-bin
+```
+
+This command installs the latest version of Flow into your project.
+
+Now, add `flow` to the `"scripts"` section of your `package.json` to be able to use this from the terminal:
+
+```js{4}
+{
+  // ...
+  "scripts": {
+    "flow": "flow",
+    // ...
+  },
+  // ...
+}
+```
+
+Finally, run one of the following commands:
+
+If you use [Yarn](https://yarnpkg.com/), run:
+
+```bash
+yarn run flow init
+```
+
+If you use [npm](https://www.npmjs.com/), run:
+
+```bash
+npm run flow init
+```
+
+This command will create a Flow configuration file that you will need to commit.
+
+### Stripping Flow Syntax from the Compiled Code {#stripping-flow-syntax-from-the-compiled-code}
+
+Flow extends the JavaScript language with a special syntax for type annotations. However, browsers aren't aware of this syntax, so we need to make sure it doesn't end up in the compiled JavaScript bundle that is sent to the browser.
+
+The exact way to do this depends on the tools you use to compile JavaScript.
+
+#### Create React App {#create-react-app}
+
+If your project was set up using [Create React App](https://github.com/facebookincubator/create-react-app), congratulations! The Flow annotations are already being stripped by default so you don't need to do anything else in this step.
+
+#### Babel {#babel}
+
+>Note:
+>
+>These instructions are *not* for Create React App users. Even though Create React App uses Babel under the hood, it is already configured to understand Flow. Only follow this step if you *don't* use Create React App.
+
+If you manually configured Babel for your project, you will need to install a special preset for Flow.
+
+If you use Yarn, run:
+
+```bash
+yarn add --dev @babel/preset-flow
+```
+
+If you use npm, run:
+
+```bash
+npm install --save-dev @babel/preset-flow
+```
+
+Then add the `flow` preset to your [Babel configuration](https://babeljs.io/docs/usage/babelrc/). For example, if you configure Babel through `.babelrc` file, it could look like this:
+
+```js{3}
+{
+  "presets": [
+    "@babel/preset-flow",
+    "react"
+  ]
+}
+```
+
+This will let you use the Flow syntax in your code.
+
+>Note:
+>
+>Flow does not require the `react` preset, but they are often used together. Flow itself understands JSX syntax out of the box.
+
+#### Other Build Setups {#other-build-setups}
+
+If you don't use either Create React App or Babel, you can use [flow-remove-types](https://github.com/flowtype/flow-remove-types) to strip the type annotations.
+
+### Running Flow {#running-flow}
+
+If you followed the instructions above, you should be able to run Flow for the first time.
+
+```bash
+yarn flow
+```
+
+If you use npm, run:
+
+```bash
+npm run flow
+```
+
+You should see a message like:
+
+```
+No errors!
+✨  Done in 0.17s.
+```
+
+### Adding Flow Type Annotations {#adding-flow-type-annotations}
+
+By default, Flow only checks the files that include this annotation:
+
+```js
+// @flow
+```
+
+Typically it is placed at the top of a file. Try adding it to some files in your project and run `yarn flow` or `npm run flow` to see if Flow already found any issues.
+
+There is also [an option](https://flow.org/en/docs/config/options/#toc-all-boolean) to force Flow to check *all* files regardless of the annotation. This can be too noisy for existing projects, but is reasonable for a new project if you want to fully type it with Flow.
+
+Now you're all set! We recommend to check out the following resources to learn more about Flow:
+
+* [Flow Documentation: Type Annotations](https://flow.org/en/docs/types/)
+* [Flow Documentation: Editors](https://flow.org/en/docs/editors/)
+* [Flow Documentation: React](https://flow.org/en/docs/react/)
+* [Linting in Flow](https://medium.com/flow-type/linting-in-flow-7709d7a7e969)
+
+## TypeScript {#typescript}
+
+[TypeScript](https://www.typescriptlang.org/) is a programming language developed by Microsoft. It is a typed superset of JavaScript, and includes its own compiler. Being a typed language, TypeScript can catch errors and bugs at build time, long before your app goes live. You can learn more about using TypeScript with React [here](https://github.com/Microsoft/TypeScript-React-Starter#typescript-react-starter).
+
+To use TypeScript, you need to:
+* Add TypeScript as a dependency to your project
+* Configure the TypeScript compiler options
+* Use the right file extensions
+* Add definitions for libraries you use
+
+Let's go over these in detail.
+
+### Using TypeScript with Create React App {#using-typescript-with-create-react-app}
+
+Create React App supports TypeScript out of the box.
+
+To create a **new project** with TypeScript support, run:
+
+```bash
+npx create-react-app my-app --typescript
+```
+
+You can also add it to an **existing Create React App project**, [as documented here](https://facebook.github.io/create-react-app/docs/adding-typescript).
+
+>Note:
+>
+>If you use Create React App, you can **skip the rest of this page**. It describes the manual setup which doesn't apply to Create React App users.
+
+
+### Adding TypeScript to a Project {#adding-typescript-to-a-project}
+It all begins with running one command in your terminal.
+
+If you use [Yarn](https://yarnpkg.com/), run:
+
+```bash
+yarn add --dev typescript
+```
+
+If you use [npm](https://www.npmjs.com/), run:
+
+```bash
+npm install --save-dev typescript
+```
+
+Congrats! You've installed the latest version of TypeScript into your project. Installing TypeScript gives us access to the `tsc` command. Before configuration, let's add `tsc` to the "scripts" section in our `package.json`:
+
+```js{4}
+{
+  // ...
+  "scripts": {
+    "build": "tsc",
+    // ...
+  },
+  // ...
+}
+```
+
+### Configuring the TypeScript Compiler {#configuring-the-typescript-compiler}
+The compiler is of no help to us until we tell it what to do. In TypeScript, these rules are defined in a special file called `tsconfig.json`. To generate this file:
+
+If you use [Yarn](https://yarnpkg.com/), run:
+
+```bash
+yarn run tsc --init
+```
+
+If you use [npm](https://www.npmjs.com/), run:
+
+```bash
+npx tsc --init
+```
+
+Looking at the now generated `tsconfig.json`, you can see that there are many options you can use to configure the compiler. For a detailed description of all the options, check [here](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
+
+Of the many options, we'll look at `rootDir` and `outDir`. In its true fashion, the compiler will take in typescript files and generate javascript files. However we don't want to get confused with our source files and the generated output.
+
+We'll address this in two steps:
+* Firstly, let's arrange our project structure like this. We'll place all our source code in the `src` directory.
+
+```
+├── package.json
+├── src
+│   └── index.ts
+└── tsconfig.json
+```
+
+* Next, we'll tell the compiler where our source code is and where the output should go.
+
+```js{6,7}
+// tsconfig.json
+
+{
+  "compilerOptions": {
+    // ...
+    "rootDir": "src",
+    "outDir": "build"
+    // ...
+  },
+}
+```
+
+Great! Now when we run our build script the compiler will output the generated javascript to the `build` folder. The [TypeScript React Starter](https://github.com/Microsoft/TypeScript-React-Starter/blob/master/tsconfig.json) provides a `tsconfig.json` with a good set of rules to get you started.
+
+Generally, you don't want to keep the generated javascript in your source control, so be sure to add the build folder to your `.gitignore`.
+
+### File extensions {#file-extensions}
+In React, you most likely write your components in a `.js` file. In TypeScript we have 2 file extensions:
+
+`.ts` is the default file extension while `.tsx` is a special extension used for files which contain `JSX`.
+
+### Running TypeScript {#running-typescript}
+
+If you followed the instructions above, you should be able to run TypeScript for the first time.
+
+```bash
+yarn build
+```
+
+If you use npm, run:
+
+```bash
+npm run build
+```
+
+If you see no output, it means that it completed successfully.
+
+
+### Type Definitions {#type-definitions}
+To be able to show errors and hints from other packages, the compiler relies on declaration files. A declaration file provides all the type information about a library. This enables us to use javascript libraries like those on npm in our project. 
+
+There are two main ways to get declarations for a library:
+
+__Bundled__ - The library bundles its own declaration file. This is great for us, since all we need to do is install the library, and we can use it right away. To check if a library has bundled types, look for an `index.d.ts` file in the project. Some libraries will have it specified in their `package.json` under the `typings` or `types` field.
+
+__[DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped)__ - DefinitelyTyped is a huge repository of declarations for libraries that don't bundle a declaration file. The declarations are crowd-sourced and managed by Microsoft and open source contributors. React for example doesn't bundle its own declaration file. Instead we can get it from DefinitelyTyped. To do so enter this command in your terminal.
+
+```bash
+# yarn
+yarn add --dev @types/react
+
+# npm
+npm i --save-dev @types/react
+```
+
+__Local Declarations__
+Sometimes the package that you want to use doesn't bundle declarations nor is it available on DefinitelyTyped. In that case, we can have a local declaration file. To do this, create a `declarations.d.ts` file in the root of your source directory. A simple declaration could look like this:
+
+```typescript
+declare module 'querystring' {
+  export function stringify(val: object): string
+  export function parse(val: string): object
+}
+```
+
+You are now ready to code! We recommend to check out the following resources to learn more about TypeScript:
+
+* [TypeScript Documentation: Basic Types](https://www.typescriptlang.org/docs/handbook/basic-types.html)
+* [TypeScript Documentation: Migrating from Javascript](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html)
+* [TypeScript Documentation: React and Webpack](https://www.typescriptlang.org/docs/handbook/react-&-webpack.html)
+
+## Reason {#reason}
+
+[Reason](https://reasonml.github.io/) is not a new language; it's a new syntax and toolchain powered by the battle-tested language, [OCaml](https://ocaml.org/). Reason gives OCaml a familiar syntax geared toward JavaScript programmers, and caters to the existing NPM/Yarn workflow folks already know.
+
+Reason is developed at Facebook, and is used in some of its products like Messenger. It is still somewhat experimental but it has [dedicated React bindings](https://reasonml.github.io/reason-react/) maintained by Facebook and a [vibrant community](https://reasonml.github.io/docs/en/community.html).
+
+## Kotlin {#kotlin}
+
+[Kotlin](https://kotlinlang.org/) is a statically typed language developed by JetBrains. Its target platforms include the JVM, Android, LLVM, and [JavaScript](https://kotlinlang.org/docs/reference/js-overview.html). 
+
+JetBrains develops and maintains several tools specifically for the React community: [React bindings](https://github.com/JetBrains/kotlin-wrappers) as well as [Create React Kotlin App](https://github.com/JetBrains/create-react-kotlin-app). The latter helps you start building React apps with Kotlin with no build configuration.
+
+## Other Languages {#other-languages}
+
+Note there are other statically typed languages that compile to JavaScript and are thus React compatible. For example, [F#/Fable](https://fable.io/) with [elmish-react](https://elmish.github.io/react). Check out their respective sites for more information, and feel free to add more statically typed languages that work with React to this page!
diff --git a/strict-mode.md b/strict-mode.md
new file mode 100644
index 000000000..e803a32d4
--- /dev/null
+++ b/strict-mode.md
@@ -0,0 +1,124 @@
+---
+id: strict-mode
+title: Strict Mode
+permalink: docs/strict-mode.html
+---
+
+`StrictMode` is a tool for highlighting potential problems in an application. Like `Fragment`, `StrictMode` does not render any visible UI. It activates additional checks and warnings for its descendants.
+
+> Note:
+>
+> Strict mode checks are run in development mode only; _they do not impact the production build_.
+
+You can enable strict mode for any part of your application. For example:
+`embed:strict-mode/enabling-strict-mode.js`
+
+In the above example, strict mode checks will *not* be run against the `Header` and `Footer` components. However, `ComponentOne` and `ComponentTwo`, as well as all of their descendants, will have the checks.
+
+`StrictMode` currently helps with:
+* [Identifying components with unsafe lifecycles](#identifying-unsafe-lifecycles)
+* [Warning about legacy string ref API usage](#warning-about-legacy-string-ref-api-usage)
+* [Warning about deprecated findDOMNode usage](#warning-about-deprecated-finddomnode-usage)
+* [Detecting unexpected side effects](#detecting-unexpected-side-effects)
+* [Detecting legacy context API](#detecting-legacy-context-api)
+
+Additional functionality will be added with future releases of React.
+
+### Identifying unsafe lifecycles {#identifying-unsafe-lifecycles}
+
+As explained [in this blog post](/blog/2018/03/27/update-on-async-rendering.html), certain legacy lifecycle methods are unsafe for use in async React applications. However, if your application uses third party libraries, it can be difficult to ensure that these lifecycles aren't being used. Fortunately, strict mode can help with this!
+
+When strict mode is enabled, React compiles a list of all class components using the unsafe lifecycles, and logs a warning message with information about these components, like so:
+
+![](../images/blog/strict-mode-unsafe-lifecycles-warning.png)
+
+Addressing the issues identified by strict mode _now_ will make it easier for you to take advantage of async rendering in future releases of React.
+
+### Warning about legacy string ref API usage {#warning-about-legacy-string-ref-api-usage}
+
+Previously, React provided two ways for managing refs: the legacy string ref API and the callback API. Although the string ref API was the more convenient of the two, it had [several downsides](https://github.com/facebook/react/issues/1373) and so our official recommendation was to [use the callback form instead](/docs/refs-and-the-dom.html#legacy-api-string-refs).
+
+React 16.3 added a third option that offers the convenience of a string ref without any of the downsides:
+`embed:16-3-release-blog-post/create-ref-example.js`
+
+Since object refs were largely added as a replacement for string refs, strict mode now warns about usage of string refs.
+
+> **Note:**
+>
+> Callback refs will continue to be supported in addition to the new `createRef` API.
+>
+> You don't need to replace callback refs in your components. They are slightly more flexible, so they will remain as an advanced feature.
+
+[Learn more about the new `createRef` API here.](/docs/refs-and-the-dom.html)
+
+### Warning about deprecated findDOMNode usage {#warning-about-deprecated-finddomnode-usage}
+
+React used to support `findDOMNode` to search the tree for a DOM node given a class instance. Normally you don't need this because you can [attach a ref directly to a DOM node](/docs/refs-and-the-dom.html#creating-refs).
+
+`findDOMNode` can also be used on class components but this was breaking abstraction levels by allowing a parent to demand that certain children was rendered. It creates a refactoring hazard where you can't change the implementation details of a component because a parent might be reaching into its DOM node. `findDOMNode` only returns the first child, but with the use of Fragments, it is possible for a component to render multiple DOM nodes. `findDOMNode` is a one time read API. It only gave you an answer when you asked for it. If a child component renders a different node, there is no way to handle this change. Therefore `findDOMNode` only worked if components always return a single DOM node that never changes.
+
+You can instead make this explicit by passing a ref to your custom component and pass that along to the DOM using [ref forwarding](/docs/forwarding-refs.html#forwarding-refs-to-dom-components).
+
+You can also add a wrapper DOM node in your component and attach a ref directly to it.
+
+```javascript{4,7}
+class MyComponent extends React.Component {
+  constructor(props) {
+    super(props);
+    this.wrapper = React.createRef();
+  }
+  render() {
+    return <div ref={this.wrapper}>{this.props.children}</div>;
+  }
+}
+```
+
+> Note:
+>
+> In CSS, the [`display: contents`](https://developer.mozilla.org/en-US/docs/Web/CSS/display#display_contents) attribute can be used if you don't want the node to be part of the layout.
+
+### Detecting unexpected side effects {#detecting-unexpected-side-effects}
+
+Conceptually, React does work in two phases:
+* The **render** phase determines what changes need to be made to e.g. the DOM. During this phase, React calls `render` and then compares the result to the previous render.
+* The **commit** phase is when React applies any changes. (In the case of React DOM, this is when React inserts, updates, and removes DOM nodes.) React also calls lifecycles like `componentDidMount` and `componentDidUpdate` during this phase.
+
+The commit phase is usually very fast, but rendering can be slow. For this reason, the upcoming async mode (which is not enabled by default yet) breaks the rendering work into pieces, pausing and resuming the work to avoid blocking the browser. This means that React may invoke render phase lifecycles more than once before committing, or it may invoke them without committing at all (because of an error or a higher priority interruption).
+
+Render phase lifecycles include the following class component methods:
+* `constructor`
+* `componentWillMount`
+* `componentWillReceiveProps`
+* `componentWillUpdate`
+* `getDerivedStateFromProps`
+* `shouldComponentUpdate`
+* `render`
+* `setState` updater functions (the first argument)
+
+Because the above methods might be called more than once, it's important that they do not contain side-effects. Ignoring this rule can lead to a variety of problems, including memory leaks and invalid application state. Unfortunately, it can be difficult to detect these problems as they can often be [non-deterministic](https://en.wikipedia.org/wiki/Deterministic_algorithm).
+
+Strict mode can't automatically detect side effects for you, but it can help you spot them by making them a little more deterministic. This is done by intentionally double-invoking the following methods:
+
+* Class component `constructor` method
+* The `render` method
+* `setState` updater functions (the first argument)
+* The static `getDerivedStateFromProps` lifecycle
+
+> Note:
+>
+> This only applies to development mode. _Lifecycles will not be double-invoked in production mode._
+
+For example, consider the following code:
+`embed:strict-mode/side-effects-in-constructor.js`
+
+At first glance, this code might not seem problematic. But if `SharedApplicationState.recordEvent` is not [idempotent](https://en.wikipedia.org/wiki/Idempotence#Computer_science_meaning), then instantiating this component multiple times could lead to invalid application state. This sort of subtle bug might not manifest during development, or it might do so inconsistently and so be overlooked.
+
+By intentionally double-invoking methods like the component constructor, strict mode makes patterns like this easier to spot.
+
+### Detecting legacy context API {#detecting-legacy-context-api}
+
+The legacy context API is error-prone, and will be removed in a future major version. It still works for all 16.x releases but will show this warning message in strict mode:
+
+![](../images/blog/warn-legacy-context-in-strict-mode.png)
+
+Read the [new context API documentation](/docs/context.html) to help migrate to the new version.
diff --git a/testing-environments.md b/testing-environments.md
new file mode 100644
index 000000000..5120a4f6d
--- /dev/null
+++ b/testing-environments.md
@@ -0,0 +1,58 @@
+---
+id: testing-environments
+title: Testing Environments
+permalink: docs/testing-environments.html
+prev: testing-recipes.html
+---
+
+<!-- This document is intended for folks who are comfortable with JavaScript, and have probably written tests with it. It acts as a reference for the differences in testing environments for React components, and how those differences affect the tests that they write. This document also assumes a slant towards web-based react-dom components, but has notes for other renderers. -->
+
+This document goes through the factors that can affect your environment and recommendations for some scenarios.
+
+### Test runners {#test-runners}
+
+Test runners like [Jest](https://jestjs.io/), [mocha](https://mochajs.org/), [ava](https://github.com/avajs/ava) let you write test suites as regular JavaScript, and run them as part of your development process. Additionally, test suites are run as part of continuous integration.
+
+- Jest is widely compatible with React projects, supporting features like mocked [modules](#mocking-modules) and [timers](#mocking-timers), and [`jsdom`](#mocking-a-rendering-surface) support. **If you use Create React App, [Jest is already included out of the box](https://facebook.github.io/create-react-app/docs/running-tests) with useful defaults.**
+- Libraries like [mocha](https://mochajs.org/#running-mocha-in-the-browser) work well in real browser environments, and could help for tests that explicitly need it.
+- End-to-end tests are used for testing longer flows across multiple pages, and require a [different setup](#end-to-end-tests-aka-e2e-tests).
+
+### Mocking a rendering surface {#mocking-a-rendering-surface}
+
+Tests often run in an environment without access to a real rendering surface like a browser. For these environments, we recommend simulating a browser with [`jsdom`](https://github.com/jsdom/jsdom), a lightweight browser implementation that runs inside Node.js.
+
+In most cases, jsdom behaves like a regular browser would, but doesn't have features like [layout and navigation](https://github.com/jsdom/jsdom#unimplemented-parts-of-the-web-platform). This is still useful for most web-based component tests, since it runs quicker than having to start up a browser for each test. It also runs in the same process as your tests, so you can write code to examine and assert on the rendered DOM.
+
+Just like in a real browser, jsdom lets us model user interactions; tests can dispatch events on DOM nodes, and then observe and assert on the side effects of these actions [<small>(example)</small>](/docs/testing-recipes.html#events).
+
+A large portion of UI tests can be written with the above setup: using Jest as a test runner, rendered to jsdom, with user interactions specified as sequences of browser events, powered by the `act()` helper [<small>(example)</small>](/docs/testing-recipes.html). For example, a lot of React's own tests are written with this combination.
+
+If you're writing a library that tests mostly browser-specific behavior, and requires native browser behavior like layout or real inputs, you could use a framework like [mocha.](https://mochajs.org/)
+
+In an environment where you _can't_ simulate a DOM (e.g. testing React Native components on Node.js), you could use [event simulation helpers](https://reactjs.org/docs/test-utils.html#simulate) to simulate interactions with elements. Alternately, you could use the `fireEvent` helper from [`@testing-library/react-native`](https://testing-library.com/docs/native-testing-library).
+
+Frameworks like [Cypress](https://www.cypress.io/), [puppeteer](https://github.com/GoogleChrome/puppeteer) and [webdriver](https://www.seleniumhq.org/projects/webdriver/) are useful for running [end-to-end tests](#end-to-end-tests-aka-e2e-tests).
+
+### Mocking functions {#mocking-functions}
+
+When writing tests, we'd like to mock out the parts of our code that don't have equivalents inside our testing environment (e.g. checking `navigator.onLine` status inside Node.js). Tests could also spy on some functions, and observe how other parts of the test interact with them. It is then useful to be able to selectively mock these functions with test-friendly versions.
+
+This is especially useful for data fetching. It is usually preferable to use "fake" data for tests to avoid the slowness and flakiness due to fetching from real API endpoints [<small>(example)</small>](/docs/testing-recipes.html#data-fetching). This helps make the tests predictable. Libraries like [Jest](https://jestjs.io/) and [sinon](https://sinonjs.org/), among others, support mocked functions. For end-to-end tests, mocking network can be more difficult, but you might also want to test the real API endpoints in them anyway.
+
+### Mocking modules {#mocking-modules}
+
+Some components have dependencies for modules that may not work well in test environments, or aren't essential to our tests. It can be useful to selectively mock these modules out with suitable replacements [<small>(example)</small>](/docs/testing-recipes.html#mocking-modules).
+
+On Node.js, runners like Jest [support mocking modules](https://jestjs.io/docs/en/manual-mocks). You could also use libraries like [`mock-require`](https://www.npmjs.com/package/mock-require).
+
+### Mocking timers {#mocking-timers}
+
+Components might be using time-based functions like `setTimeout`, `setInterval`, or `Date.now`. In testing environments, it can be helpful to mock these functions out with replacements that let you manually "advance" time. This is great for making sure your tests run fast! Tests that are dependent on timers would still resolve in order, but quicker [<small>(example)</small>](/docs/testing-recipes.html#timers). Most frameworks, including [Jest](https://jestjs.io/docs/en/timer-mocks), [sinon](https://sinonjs.org/releases/v7.3.2/fake-timers/) and [lolex](https://github.com/sinonjs/lolex), let you mock timers in your tests.
+
+Sometimes, you may not want to mock timers. For example, maybe you're testing an animation, or interacting with an endpoint that's sensitive to timing (like an API rate limiter). Libraries with timer mocks let you enable and disable them on a per test/suite basis, so you can explicitly choose how these tests would run.
+
+### End-to-end tests {#end-to-end-tests-aka-e2e-tests}
+
+End-to-end tests are useful for testing longer workflows, especially when they're critical to your business (such as payments or signups). For these tests, you'd probably want to test both how a real browser renders the whole app, fetches data from the real API endpoints, uses sessions and cookies, navigates between different links. You might also likely want to make assertions not just on the DOM state, but on the backing data as well (e.g. to verify whether the updates have been persisted to the database).
+
+In this scenario, you would use a framework like [Cypress](https://www.cypress.io/) or a library like [puppeteer](https://github.com/GoogleChrome/puppeteer) so you can navigate between multiple routes and assert on side effects not just in the browser, but potentially on the backend as well.
diff --git a/testing-recipes.md b/testing-recipes.md
new file mode 100644
index 000000000..0ce5e205f
--- /dev/null
+++ b/testing-recipes.md
@@ -0,0 +1,626 @@
+---
+id: testing-recipes
+title: Testing Recipes
+permalink: docs/testing-recipes.html
+prev: testing.html
+next: testing-environments.html
+---
+
+Common testing patterns for React components.
+
+> Note:
+>
+> This page assumes you're using [Jest](https://jestjs.io/) as a test runner. If you use a different test runner, you may need to adjust the API, but the overall shape of the solution will likely be the same. Read more details on setting up a testing environment on the [Testing Environments](/docs/testing-environments.html) page.
+
+On this page, we will primarily use function components. However, these testing strategies don't depend on implementation details, and work just as well for class components too.
+
+- [Setup/Teardown](#setup--teardown)
+- [`act()`](#act)
+- [Rendering](#rendering)
+- [Data Fetching](#data-fetching)
+- [Mocking Modules](#mocking-modules)
+- [Events](#events)
+- [Timers](#timers)
+- [Snapshot Testing](#snapshot-testing)
+- [Multiple Renderers](#multiple-renderers)
+- [Something Missing?](#something-missing)
+
+---
+
+### Setup/Teardown {#setup--teardown}
+
+For each test, we usually want to render our React tree to a DOM element that's attached to `document`. This is important so that it can receive DOM events. When the test ends, we want to "clean up" and unmount the tree from the `document`.
+
+A common way to do it is to use a pair of `beforeEach` and `afterEach` blocks so that they'll always run and isolate the effects of a test to itself:
+
+```jsx
+import { unmountComponentAtNode } from "react-dom";
+
+let container = null;
+beforeEach(() => {
+  // setup a DOM element as a render target
+  container = document.createElement("div");
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  // cleanup on exiting
+  unmountComponentAtNode(container);
+  container.remove();
+  container = null;
+});
+```
+
+You may use a different pattern, but keep in mind that we want to execute the cleanup _even if a test fails_. Otherwise, tests can become "leaky", and one test can change the behavior of another test. That makes them difficult to debug.
+
+---
+
+### `act()` {#act}
+
+When writing UI tests, tasks like rendering, user events, or data fetching can be considered as "units" of interaction with a user interface. React provides a helper called `act()` that makes sure all updates related to these "units" have been processed and applied to the DOM before you make any assertions:
+
+```js
+act(() => {
+  // render components
+});
+// make assertions
+```
+
+This helps make your tests run closer to what real users would experience when using your application. The rest of these examples use `act()` to make these guarantees.
+
+You might find using `act()` directly a bit too verbose. To avoid some of the boilerplate, you could use a library like [React Testing Library](https://testing-library.com/react), whose helpers are wrapped with `act()`.
+
+> Note:
+>
+> The name `act` comes from the [Arrange-Act-Assert](http://wiki.c2.com/?ArrangeActAssert) pattern.
+
+---
+
+### Rendering {#rendering}
+
+Commonly, you might want to test whether a component renders correctly for given props. Consider a simple component that renders a message based on a prop:
+
+```jsx
+// hello.js
+
+import React from "react";
+
+export default function Hello(props) {
+  if (props.name) {
+    return <h1>Hello, {props.name}!</h1>;
+  } else {
+    return <span>Hey, stranger</span>;
+  }
+}
+```
+
+We can write a test for this component:
+
+```jsx{24-27}
+// hello.test.js
+
+import React from "react";
+import { render, unmountComponentAtNode } from "react-dom";
+import { act } from "react-dom/test-utils";
+
+import Hello from "./hello";
+
+let container = null;
+beforeEach(() => {
+  // setup a DOM element as a render target
+  container = document.createElement("div");
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  // cleanup on exiting
+  unmountComponentAtNode(container);
+  container.remove();
+  container = null;
+});
+
+it("renders with or without a name", () => {
+  act(() => {
+    render(<Hello />, container);
+  });
+  expect(container.textContent).toBe("Hey, stranger");
+
+  act(() => {
+    render(<Hello name="Jenny" />, container);
+  });
+  expect(container.textContent).toBe("Hello, Jenny!");
+
+  act(() => {
+    render(<Hello name="Margaret" />, container);
+  });
+  expect(container.textContent).toBe("Hello, Margaret!");
+});
+```
+
+---
+
+### Data Fetching {#data-fetching}
+
+Instead of calling real APIs in all your tests, you can mock requests with dummy data. Mocking data fetching with "fake" data prevents flaky tests due to an unavailable backend, and makes them run faster. Note: you may still want to run a subset of tests using an ["end-to-end"](/docs/testing-environments.html#end-to-end-tests-aka-e2e-tests) framework that tells whether the whole app is working together.
+
+```jsx
+// user.js
+
+import React, { useState, useEffect } from "react";
+
+export default function User(props) {
+  const [user, setUser] = useState(null);
+
+  async function fetchUserData(id) {
+    const response = await fetch("/" + id);
+    setUser(await response.json());
+  }
+
+  useEffect(() => {
+    fetchUserData(props.id);
+  }, [props.id]);
+
+  if (!user) {
+    return "loading...";
+  }
+
+  return (
+    <details>
+      <summary>{user.name}</summary>
+      <strong>{user.age}</strong> years old
+      <br />
+      lives in {user.address}
+    </details>
+  );
+}
+```
+
+We can write tests for it:
+
+```jsx{23-33,44-45}
+// user.test.js
+
+import React from "react";
+import { render, unmountComponentAtNode } from "react-dom";
+import { act } from "react-dom/test-utils";
+import User from "./user";
+
+let container = null;
+beforeEach(() => {
+  // setup a DOM element as a render target
+  container = document.createElement("div");
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  // cleanup on exiting
+  unmountComponentAtNode(container);
+  container.remove();
+  container = null;
+});
+
+it("renders user data", async () => {
+  const fakeUser = {
+    name: "Joni Baez",
+    age: "32",
+    address: "123, Charming Avenue"
+  };
+
+  jest.spyOn(global, "fetch").mockImplementation(() =>
+    Promise.resolve({
+      json: () => Promise.resolve(fakeUser)
+    })
+  );
+
+  // Use the asynchronous version of act to apply resolved promises
+  await act(async () => {
+    render(<User id="123" />, container);
+  });
+
+  expect(container.querySelector("summary").textContent).toBe(fakeUser.name);
+  expect(container.querySelector("strong").textContent).toBe(fakeUser.age);
+  expect(container.textContent).toContain(fakeUser.address);
+
+  // remove the mock to ensure tests are completely isolated
+  global.fetch.mockRestore();
+});
+```
+
+---
+
+### Mocking Modules {#mocking-modules}
+
+Some modules might not work well inside a testing environment, or may not be as essential to the test itself. Mocking out these modules with dummy replacements can make it easier to write tests for your own code.
+
+Consider a `Contact` component that embeds a third-party `GoogleMap` component:
+
+```jsx
+// map.js
+
+import React from "react";
+
+import { LoadScript, GoogleMap } from "react-google-maps";
+export default function Map(props) {
+  return (
+    <LoadScript id="script-loader" googleMapsApiKey="YOUR_API_KEY">
+      <GoogleMap id="example-map" center={props.center} />
+    </LoadScript>
+  );
+}
+
+// contact.js
+
+import React from "react";
+import Map from "./map";
+
+function Contact(props) {
+  return (
+    <div>
+      <address>
+        Contact {props.name} via{" "}
+        <a data-testid="email" href={"mailto:" + props.email}>
+          email
+        </a>
+        or on their <a data-testid="site" href={props.site}>
+          website
+        </a>.
+      </address>
+      <Map center={props.center} />
+    </div>
+  );
+}
+```
+
+If we don't want to load this component in our tests, we can mock out the dependency itself to a dummy component, and run our tests:
+
+```jsx{10-18}
+// contact.test.js
+
+import React from "react";
+import { render, unmountComponentAtNode } from "react-dom";
+import { act } from "react-dom/test-utils";
+
+import Contact from "./contact";
+import MockedMap from "./map";
+
+jest.mock("./map", () => {
+  return function DummyMap(props) {
+    return (
+      <div data-testid="map">
+        {props.center.lat}:{props.center.long}
+      </div>
+    );
+  };
+});
+
+let container = null;
+beforeEach(() => {
+  // setup a DOM element as a render target
+  container = document.createElement("div");
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  // cleanup on exiting
+  unmountComponentAtNode(container);
+  container.remove();
+  container = null;
+});
+
+it("should render contact information", () => {
+  const center = { lat: 0, long: 0 };
+  act(() => {
+    render(
+      <Contact
+        name="Joni Baez"
+        email="test@example.com"
+        site="http://test.com"
+        center={center}
+      />,
+      container
+    );
+  });
+
+  expect(
+    container.querySelector("[data-testid='email']").getAttribute("href")
+  ).toEqual("mailto:test@example.com");
+
+  expect(
+    container.querySelector('[data-testid="site"]').getAttribute("href")
+  ).toEqual("http://test.com");
+
+  expect(container.querySelector('[data-testid="map"]').textContent).toEqual(
+    "0:0"
+  );
+});
+```
+
+---
+
+### Events {#events}
+
+We recommend dispatching real DOM events on DOM elements, and then asserting on the result. Consider a `Toggle` component:
+
+```jsx
+// toggle.js
+
+import React, { useState } from "react";
+
+export default function Toggle(props) {
+  const [state, setState] = useState(false);
+  return (
+    <button
+      onClick={() => {
+        setState(previousState => !previousState);
+        props.onChange(!state);
+      }}
+      data-testid="toggle"
+    >
+      {state === true ? "Turn off" : "Turn on"}
+    </button>
+  );
+}
+```
+
+We could write tests for it:
+
+```jsx{13-14,35,43}
+// toggle.test.js
+
+import React from "react";
+import { render, unmountComponentAtNode } from "react-dom";
+import { act } from "react-dom/test-utils";
+
+import Toggle from "./toggle";
+
+let container = null;
+beforeEach(() => {
+  // setup a DOM element as a render target
+  container = document.createElement("div");
+  // container *must* be attached to document so events work correctly.
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  // cleanup on exiting
+  unmountComponentAtNode(container);
+  container.remove();
+  container = null;
+});
+
+it("changes value when clicked", () => {
+  const onChange = jest.fn();
+  act(() => {
+    render(<Toggle onChange={onChange} />, container);
+  });
+
+  // get ahold of the button element, and trigger some clicks on it
+  const button = document.querySelector("[data-testid=toggle]");
+  expect(button.innerHTML).toBe("Turn off");
+
+  act(() => {
+    button.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+  });
+
+  expect(onChange).toHaveBeenCalledTimes(1);
+  expect(button.innerHTML).toBe("Turn on");
+
+  act(() => {
+    for (let i = 0; i < 5; i++) {
+      button.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    }
+  });
+
+  expect(onChange).toHaveBeenCalledTimes(6);
+  expect(button.innerHTML).toBe("Turn on");
+});
+```
+
+Different DOM events and their properties are described in [MDN](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent). Note that you need to pass `{ bubbles: true }` in each event you create for it to reach the React listener because React automatically delegates events to the document.
+
+> Note:
+>
+> React Testing Library offers a [more concise helper](https://testing-library.com/docs/dom-testing-library/api-events) for firing events.
+
+---
+
+### Timers {#timers}
+
+Your code might use timer-based functions like `setTimeout` to schedule more work in the future. In this example, a multiple choice panel waits for a selection and advances, timing out if a selection isn't made in 5 seconds:
+
+```jsx
+// card.js
+
+import React, { useEffect } from "react";
+
+export default function Card(props) {
+  useEffect(() => {
+    const timeoutID = setTimeout(() => {
+      props.onSelect(null);
+    }, 5000);
+    return () => {
+      clearTimeout(timeoutID);
+    };
+  }, [props.onSelect]);
+
+  return [1, 2, 3, 4].map(choice => (
+    <button
+      key={choice}
+      data-testid={choice}
+      onClick={() => props.onSelect(choice)}
+    >
+      {choice}
+    </button>
+  ));
+}
+```
+
+We can write tests for this component by leveraging [Jest's timer mocks](https://jestjs.io/docs/en/timer-mocks), and testing the different states it can be in.
+
+```jsx{7,31,37,49,59}
+// card.test.js
+
+import React from "react";
+import { render, unmountComponentAtNode } from "react-dom";
+import { act } from "react-dom/test-utils";
+
+jest.useFakeTimers();
+
+let container = null;
+beforeEach(() => {
+  // setup a DOM element as a render target
+  container = document.createElement("div");
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  // cleanup on exiting
+  unmountComponentAtNode(container);
+  container.remove();
+  container = null;
+});
+
+it("should select null after timing out", () => {
+  const onSelect = jest.fn();
+  act(() => {
+    render(<Card onSelect={onSelect} />, container);
+  });
+
+  // move ahead in time by 100ms
+  act(() => {
+    jest.advanceTimersByTime(100);
+  });
+  expect(onSelect).not.toHaveBeenCalled();
+
+  // and then move ahead by 5 seconds
+  act(() => {
+    jest.advanceTimersByTime(5000);
+  });
+  expect(onSelect).toHaveBeenCalledWith(null);
+});
+
+it("should cleanup on being removed", () => {
+  const onSelect = jest.fn();
+  act(() => {
+    render(<Card onSelect={onSelect} />, container);
+  });
+
+  act(() => {
+    jest.advanceTimersByTime(100);
+  });
+  expect(onSelect).not.toHaveBeenCalled();
+
+  // unmount the app
+  act(() => {
+    render(null, container);
+  });
+
+  act(() => {
+    jest.advanceTimersByTime(5000);
+  });
+  expect(onSelect).not.toHaveBeenCalled();
+});
+
+it("should accept selections", () => {
+  const onSelect = jest.fn();
+  act(() => {
+    render(<Card onSelect={onSelect} />, container);
+  });
+
+  act(() => {
+    container
+      .querySelector("[data-testid=2]")
+      .dispatchEvent(new MouseEvent("click", { bubbles: true }));
+  });
+
+  expect(onSelect).toHaveBeenCalledWith(2);
+});
+```
+
+You can use fake timers only in some tests. Above, we enabled them by calling `jest.useFakeTimers()`. The main advantage they provide is that your test doesn't actually have to wait five seconds to execute, and you also didn't need to make the component code more convoluted just for testing.
+
+---
+
+### Snapshot Testing {#snapshot-testing}
+
+Frameworks like Jest also let you save "snapshots" of data with [`toMatchSnapshot` / `toMatchInlineSnapshot`](https://jestjs.io/docs/en/snapshot-testing). With these, we can "save" the rendered component output and ensure that a change to it has to be explicitly committed as a change to the snapshot.
+
+In this example, we render a component and format the rendered HTML with the [`pretty`](https://www.npmjs.com/package/pretty) package, before saving it as an inline snapshot:
+
+```jsx{29-31}
+// hello.test.js, again
+
+import React from "react";
+import { render, unmountComponentAtNode } from "react-dom";
+import { act } from "react-dom/test-utils";
+import pretty from "pretty";
+
+import Hello from "./hello";
+
+let container = null;
+beforeEach(() => {
+  // setup a DOM element as a render target
+  container = document.createElement("div");
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  // cleanup on exiting
+  unmountComponentAtNode(container);
+  container.remove();
+  container = null;
+});
+
+it("should render a greeting", () => {
+  act(() => {
+    render(<Hello />, container);
+  });
+
+  expect(
+    pretty(container.innerHTML)
+  ).toMatchInlineSnapshot(); /* ... gets filled automatically by jest ... */
+
+  act(() => {
+    render(<Hello name="Jenny" />, container);
+  });
+
+  expect(
+    pretty(container.innerHTML)
+  ).toMatchInlineSnapshot(); /* ... gets filled automatically by jest ... */
+
+  act(() => {
+    render(<Hello name="Margaret" />, container);
+  });
+
+  expect(
+    pretty(container.innerHTML)
+  ).toMatchInlineSnapshot(); /* ... gets filled automatically by jest ... */
+});
+```
+
+It's typically better to make more specific assertions than to use snapshots. These kinds of tests include implementation details so they break easily, and teams can get desensitized to snapshot breakages. Selectively [mocking some child components](#mocking-modules) can help reduce the size of snapshots and keep them readable for the code review.
+
+---
+
+### Multiple Renderers {#multiple-renderers}
+
+In rare cases, you may be running a test on a component that uses multiple renderers. For example, you may be running snapshot tests on a component with `react-test-renderer`, that internally uses `ReactDOM.render` inside a child component to render some content. In this scenario, you can wrap updates with `act()`s corresponding to their renderers.
+
+```jsx
+import { act as domAct } from "react-dom/test-utils";
+import { act as testAct, create } from "react-test-renderer";
+// ...
+let root;
+domAct(() => {
+  testAct(() => {
+    root = create(<App />);
+  });
+});
+expect(root).toMatchSnapshot();
+```
+
+---
+
+### Something Missing? {#something-missing}
+
+If some common scenario is not covered, please let us know on the [issue tracker](https://github.com/reactjs/reactjs.org/issues) for the documentation website.
diff --git a/testing.md b/testing.md
new file mode 100644
index 000000000..5bccd1fc4
--- /dev/null
+++ b/testing.md
@@ -0,0 +1,40 @@
+---
+id: testing
+title: Testing Overview
+permalink: docs/testing.html
+redirect_from:
+  - "community/testing.html"
+next: testing-recipes.html
+---
+
+You can test React components similar to testing other JavaScript code.
+
+There are a few ways to test React components. Broadly, they divide into two categories:
+
+* **Rendering component trees** in a simplified test environment and asserting on their output.
+* **Running a complete app** in a realistic browser environment (also known as “end-to-end” tests).
+
+This documentation section focuses on testing strategies for the first case. While full end-to-end tests can be very useful to prevent regressions to important workflows, such tests are not concerned with React components in particular, and are out of scope of this section.
+
+### Tradeoffs {#tradeoffs}
+
+
+When choosing testing tools, it is worth considering a few tradeoffs:
+
+* **Iteration speed vs Realistic environment:** Some tools offer a very quick feedback loop between making a change and seeing the result, but don't model the browser behavior precisely. Other tools might use a real browser environment, but reduce the iteration speed and are flakier on a continuous integration server.
+* **How much to mock:** With components, the distinction between a "unit" and "integration" test can be blurry. If you're testing a form, should its test also test the buttons inside of it? Or should a button component have its own test suite? Should refactoring a button ever break the form test?
+
+Different answers may work for different teams and products.
+
+### Recommended Tools {#tools}
+
+**[Jest](https://facebook.github.io/jest/)** is a JavaScript test runner that lets you access the DOM via [`jsdom`](/docs/testing-environments.html#mocking-a-rendering-surface). While jsdom is only an approximation of how the browser works, it is often good enough for testing React components. Jest provides a great iteration speed combined with powerful features like mocking [modules](/docs/testing-environments.html#mocking-modules) and [timers](/docs/testing-environments.html#mocking-timers) so you can have more control over how the code executes.
+
+**[React Testing Library](https://testing-library.com/react)** is a set of helpers that let you test React components without relying on their implementation details. This approach makes refactoring a breeze and also nudges you towards best practices for accessibility. Although it doesn't provide a way to "shallowly" render a component without its children, a test runner like Jest lets you do this by [mocking](/docs/testing-recipes.html#mocking-modules).
+
+### Learn More {#learn-more}
+
+This section is divided in two pages:
+
+- [Recipes](/docs/testing-recipes.html): Common patterns when writing tests for React components.
+- [Environments](/docs/testing-environments.html): What to consider when setting up a testing environment for React components.
diff --git a/thinking-in-react.md b/thinking-in-react.md
new file mode 100644
index 000000000..6e5e7ed94
--- /dev/null
+++ b/thinking-in-react.md
@@ -0,0 +1,146 @@
+---
+id: thinking-in-react
+title: Thinking in React
+permalink: docs/thinking-in-react.html
+redirect_from:
+  - 'blog/2013/11/05/thinking-in-react.html'
+  - 'docs/thinking-in-react-zh-CN.html'
+prev: composition-vs-inheritance.html
+---
+
+React is, in our opinion, the premier way to build big, fast Web apps with JavaScript. It has scaled very well for us at Facebook and Instagram.
+
+One of the many great parts of React is how it makes you think about apps as you build them. In this document, we'll walk you through the thought process of building a searchable product data table using React.
+
+## Start With A Mock {#start-with-a-mock}
+
+Imagine that we already have a JSON API and a mock from our designer. The mock looks like this:
+
+![Mockup](../images/blog/thinking-in-react-mock.png)
+
+Our JSON API returns some data that looks like this:
+
+```
+[
+  {category: "Sporting Goods", price: "$49.99", stocked: true, name: "Football"},
+  {category: "Sporting Goods", price: "$9.99", stocked: true, name: "Baseball"},
+  {category: "Sporting Goods", price: "$29.99", stocked: false, name: "Basketball"},
+  {category: "Electronics", price: "$99.99", stocked: true, name: "iPod Touch"},
+  {category: "Electronics", price: "$399.99", stocked: false, name: "iPhone 5"},
+  {category: "Electronics", price: "$199.99", stocked: true, name: "Nexus 7"}
+];
+```
+
+## Step 1: Break The UI Into A Component Hierarchy {#step-1-break-the-ui-into-a-component-hierarchy}
+
+The first thing you'll want to do is to draw boxes around every component (and subcomponent) in the mock and give them all names. If you're working with a designer, they may have already done this, so go talk to them! Their Photoshop layer names may end up being the names of your React components!
+
+But how do you know what should be its own component? Use the same techniques for deciding if you should create a new function or object. One such technique is the [single responsibility principle](https://en.wikipedia.org/wiki/Single_responsibility_principle), that is, a component should ideally only do one thing. If it ends up growing, it should be decomposed into smaller subcomponents.
+
+Since you're often displaying a JSON data model to a user, you'll find that if your model was built correctly, your UI (and therefore your component structure) will map nicely. That's because UI and data models tend to adhere to the same *information architecture*. Separate your UI into components, where each component matches one piece of your data model.
+
+![Component diagram](../images/blog/thinking-in-react-components.png)
+
+You'll see here that we have five components in our app. We've italicized the data each component represents.
+
+  1. **`FilterableProductTable` (orange):** contains the entirety of the example
+  2. **`SearchBar` (blue):** receives all *user input*
+  3. **`ProductTable` (green):** displays and filters the *data collection* based on *user input*
+  4. **`ProductCategoryRow` (turquoise):** displays a heading for each *category*
+  5. **`ProductRow` (red):** displays a row for each *product*
+
+If you look at `ProductTable`, you'll see that the table header (containing the "Name" and "Price" labels) isn't its own component. This is a matter of preference, and there's an argument to be made either way. For this example, we left it as part of `ProductTable` because it is part of rendering the *data collection* which is `ProductTable`'s responsibility. However, if this header grows to be complex (e.g., if we were to add affordances for sorting), it would certainly make sense to make this its own `ProductTableHeader` component.
+
+Now that we've identified the components in our mock, let's arrange them into a hierarchy. Components that appear within another component in the mock should appear as a child in the hierarchy:
+
+  * `FilterableProductTable`
+    * `SearchBar`
+    * `ProductTable`
+      * `ProductCategoryRow`
+      * `ProductRow`
+
+## Step 2: Build A Static Version in React {#step-2-build-a-static-version-in-react}
+
+<p data-height="600" data-theme-id="0" data-slug-hash="BwWzwm" data-default-tab="js" data-user="lacker" data-embed-version="2" class="codepen">See the Pen <a href="https://codepen.io/gaearon/pen/BwWzwm">Thinking In React: Step 2</a> on <a href="https://codepen.io">CodePen</a>.</p>
+<script async src="https://production-assets.codepen.io/assets/embed/ei.js"></script>
+
+Now that you have your component hierarchy, it's time to implement your app. The easiest way is to build a version that takes your data model and renders the UI but has no interactivity. It's best to decouple these processes because building a static version requires a lot of typing and no thinking, and adding interactivity requires a lot of thinking and not a lot of typing. We'll see why.
+
+To build a static version of your app that renders your data model, you'll want to build components that reuse other components and pass data using *props*. *props* are a way of passing data from parent to child. If you're familiar with the concept of *state*, **don't use state at all** to build this static version. State is reserved only for interactivity, that is, data that changes over time. Since this is a static version of the app, you don't need it.
+
+You can build top-down or bottom-up. That is, you can either start with building the components higher up in the hierarchy (i.e. starting with `FilterableProductTable`) or with the ones lower in it (`ProductRow`). In simpler examples, it's usually easier to go top-down, and on larger projects, it's easier to go bottom-up and write tests as you build.
+
+At the end of this step, you'll have a library of reusable components that render your data model. The components will only have `render()` methods since this is a static version of your app. The component at the top of the hierarchy (`FilterableProductTable`) will take your data model as a prop. If you make a change to your underlying data model and call `ReactDOM.render()` again, the UI will be updated. You can see how your UI is updated and where to make changes. React's **one-way data flow** (also called *one-way binding*) keeps everything modular and fast.
+
+Refer to the [React docs](/docs/) if you need help executing this step.
+
+### A Brief Interlude: Props vs State {#a-brief-interlude-props-vs-state}
+
+There are two types of "model" data in React: props and state. It's important to understand the distinction between the two; skim [the official React docs](/docs/state-and-lifecycle.html) if you aren't sure what the difference is. See also [FAQ: What is the difference between state and props?](/docs/faq-state.html#what-is-the-difference-between-state-and-props)
+
+## Step 3: Identify The Minimal (but complete) Representation Of UI State {#step-3-identify-the-minimal-but-complete-representation-of-ui-state}
+
+To make your UI interactive, you need to be able to trigger changes to your underlying data model. React achieves this 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*](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, 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, take the length of the TODO items array.
+
+Think of all of the pieces of data in our example application. We have:
+
+  * The original list of products
+  * The search text the user has entered
+  * The value of the checkbox
+  * The filtered list of products
+
+Let's go through each one and figure out which one is state. Ask three questions about each piece of data:
+
+  1. Is it passed in from a parent via props? If so, it probably isn't state.
+  2. Does it remain unchanged over time? If so, it probably isn't state.
+  3. Can you compute it based on any other state or props in your component? If so, it isn't state.
+
+The original list of products is passed in as props, so that's not state. The search text and the checkbox seem to be state since they change over time and can't be computed from anything. And finally, the filtered list of products isn't state because it can be computed by combining the original list of products with the search text and value of the checkbox.
+
+So finally, our state is:
+
+  * The search text the user has entered
+  * The value of the checkbox
+
+## Step 4: Identify Where Your State Should Live {#step-4-identify-where-your-state-should-live}
+
+<p data-height="600" data-theme-id="0" data-slug-hash="qPrNQZ" data-default-tab="js" data-user="lacker" data-embed-version="2" class="codepen">See the Pen <a href="https://codepen.io/gaearon/pen/qPrNQZ">Thinking In React: Step 4</a> on <a href="https://codepen.io">CodePen</a>.</p>
+
+OK, so we've identified what the minimal set of app state is. Next, we need to identify which component mutates, or *owns*, this state.
+
+Remember: React is all about one-way data flow down the component hierarchy. It may not be immediately clear which component should own what state. **This is often the most challenging part for newcomers to understand,** so follow these steps to figure it out:
+
+For each piece of state in your application:
+
+  * Identify every component that renders something based on that state.
+  * Find a common owner component (a single component above all the components that need the state in the hierarchy).
+  * Either the common owner or another component higher up in the hierarchy should own the state.
+  * If you can't find a component where it makes sense to own the state, create a new component solely for holding the state and add it somewhere in the hierarchy above the common owner component.
+
+Let's run through this strategy for our application:
+
+  * `ProductTable` needs to filter the product list based on state and `SearchBar` needs to display the search text and checked state.
+  * The common owner component is `FilterableProductTable`.
+  * It conceptually makes sense for the filter text and checked value to live in `FilterableProductTable`
+
+Cool, so we've decided that our state lives in `FilterableProductTable`. First, add an instance property `this.state = {filterText: '', inStockOnly: false}` to `FilterableProductTable`'s `constructor` to reflect the initial state of your application. Then, pass `filterText` and `inStockOnly` to `ProductTable` and `SearchBar` as a prop. Finally, use these props to filter the rows in `ProductTable` and set the values of the form fields in `SearchBar`.
+
+You can start seeing how your application will behave: set `filterText` to `"ball"` and refresh your app. You'll see that the data table is updated correctly.
+
+## Step 5: Add Inverse Data Flow {#step-5-add-inverse-data-flow}
+
+<p data-height="600" data-theme-id="0" data-slug-hash="LzWZvb" data-default-tab="js,result" data-user="rohan10" data-embed-version="2" data-pen-title="Thinking In React: Step 5" class="codepen">See the Pen <a href="https://codepen.io/gaearon/pen/LzWZvb">Thinking In React: Step 5</a> on <a href="https://codepen.io">CodePen</a>.</p>
+
+So far, we've built an app that renders correctly as a function of props and state flowing down the hierarchy. Now it's time to support data flowing the other way: the form components deep in the hierarchy need to update the state in `FilterableProductTable`.
+
+React makes this data flow explicit to help you understand how your program works, but it does require a little more typing than traditional two-way data binding.
+
+If you try to type or check the box in the current version of the example, you'll see that React ignores your input. This is intentional, as we've set the `value` prop of the `input` to always be equal to the `state` passed in from `FilterableProductTable`.
+
+Let's think about what we want to happen. We want to make sure that whenever the user changes the form, we update the state to reflect the user input. Since components should only update their own state, `FilterableProductTable` will pass callbacks to `SearchBar` that will fire whenever the state should be updated. We can use the `onChange` event on the inputs to be notified of it. The callbacks passed by `FilterableProductTable` will call `setState()`, and the app will be updated.
+
+## And That's It {#and-thats-it}
+
+Hopefully, this gives you an idea of how to think about building components and applications with React. While it may be a little more typing than you're used to, remember that code is read far more than it's written, and it's less difficult to read this modular, explicit code. As you start to build large libraries of components, you'll appreciate this explicitness and modularity, and with code reuse, your lines of code will start to shrink. :)
diff --git a/typechecking-with-proptypes.md b/typechecking-with-proptypes.md
new file mode 100644
index 000000000..9034ba9dc
--- /dev/null
+++ b/typechecking-with-proptypes.md
@@ -0,0 +1,196 @@
+---
+id: typechecking-with-proptypes
+title: Typechecking With PropTypes
+permalink: docs/typechecking-with-proptypes.html
+redirect_from:
+  - "docs/react-api.html#typechecking-with-proptypes"
+---
+
+> Note:
+>
+> `React.PropTypes` has moved into a different package since React v15.5. Please use [the `prop-types` library instead](https://www.npmjs.com/package/prop-types).
+>
+>We provide [a codemod script](/blog/2017/04/07/react-v15.5.0.html#migrating-from-reactproptypes) to automate the conversion.
+
+As your app grows, you can catch a lot of bugs with typechecking. For some applications, you can use JavaScript extensions like [Flow](https://flow.org/) or [TypeScript](https://www.typescriptlang.org/) to typecheck your whole application. But even if you don't use those, React has some built-in typechecking abilities. To run typechecking on the props for a component, you can assign the special `propTypes` property:
+
+```javascript
+import PropTypes from 'prop-types';
+
+class Greeting extends React.Component {
+  render() {
+    return (
+      <h1>Hello, {this.props.name}</h1>
+    );
+  }
+}
+
+Greeting.propTypes = {
+  name: PropTypes.string
+};
+```
+
+`PropTypes` exports a range of validators that can be used to make sure the data you receive is valid. In this example, we're using `PropTypes.string`. When an invalid value is provided for a prop, a warning will be shown in the JavaScript console. For performance reasons, `propTypes` is only checked in development mode.
+
+### PropTypes {#proptypes}
+
+Here is an example documenting the different validators provided:
+
+```javascript
+import PropTypes from 'prop-types';
+
+MyComponent.propTypes = {
+  // You can declare that a prop is a specific JS type. By default, these
+  // are all optional.
+  optionalArray: PropTypes.array,
+  optionalBool: PropTypes.bool,
+  optionalFunc: PropTypes.func,
+  optionalNumber: PropTypes.number,
+  optionalObject: PropTypes.object,
+  optionalString: PropTypes.string,
+  optionalSymbol: PropTypes.symbol,
+
+  // Anything that can be rendered: numbers, strings, elements or an array
+  // (or fragment) containing these types.
+  optionalNode: PropTypes.node,
+
+  // A React element.
+  optionalElement: PropTypes.element,
+
+  // A React element type (ie. MyComponent).
+  optionalElementType: PropTypes.elementType,
+  
+  // You can also declare that a prop is an instance of a class. This uses
+  // JS's instanceof operator.
+  optionalMessage: PropTypes.instanceOf(Message),
+
+  // You can ensure that your prop is limited to specific values by treating
+  // it as an enum.
+  optionalEnum: PropTypes.oneOf(['News', 'Photos']),
+
+  // An object that could be one of many types
+  optionalUnion: PropTypes.oneOfType([
+    PropTypes.string,
+    PropTypes.number,
+    PropTypes.instanceOf(Message)
+  ]),
+
+  // An array of a certain type
+  optionalArrayOf: PropTypes.arrayOf(PropTypes.number),
+
+  // An object with property values of a certain type
+  optionalObjectOf: PropTypes.objectOf(PropTypes.number),
+
+  // An object taking on a particular shape
+  optionalObjectWithShape: PropTypes.shape({
+    color: PropTypes.string,
+    fontSize: PropTypes.number
+  }),
+  
+  // An object with warnings on extra properties
+  optionalObjectWithStrictShape: PropTypes.exact({
+    name: PropTypes.string,
+    quantity: PropTypes.number
+  }),   
+
+  // You can chain any of the above with `isRequired` to make sure a warning
+  // is shown if the prop isn't provided.
+  requiredFunc: PropTypes.func.isRequired,
+
+  // A value of any data type
+  requiredAny: PropTypes.any.isRequired,
+
+  // You can also specify a custom validator. It should return an Error
+  // object if the validation fails. Don't `console.warn` or throw, as this
+  // won't work inside `oneOfType`.
+  customProp: function(props, propName, componentName) {
+    if (!/matchme/.test(props[propName])) {
+      return new Error(
+        'Invalid prop `' + propName + '` supplied to' +
+        ' `' + componentName + '`. Validation failed.'
+      );
+    }
+  },
+
+  // You can also supply a custom validator to `arrayOf` and `objectOf`.
+  // It should return an Error object if the validation fails. The validator
+  // will be called for each key in the array or object. The first two
+  // arguments of the validator are the array or object itself, and the
+  // current item's key.
+  customArrayProp: PropTypes.arrayOf(function(propValue, key, componentName, location, propFullName) {
+    if (!/matchme/.test(propValue[key])) {
+      return new Error(
+        'Invalid prop `' + propFullName + '` supplied to' +
+        ' `' + componentName + '`. Validation failed.'
+      );
+    }
+  })
+};
+```
+
+### Requiring Single Child {#requiring-single-child}
+
+With `PropTypes.element` you can specify that only a single child can be passed to a component as children.
+
+```javascript
+import PropTypes from 'prop-types';
+
+class MyComponent extends React.Component {
+  render() {
+    // This must be exactly one element or it will warn.
+    const children = this.props.children;
+    return (
+      <div>
+        {children}
+      </div>
+    );
+  }
+}
+
+MyComponent.propTypes = {
+  children: PropTypes.element.isRequired
+};
+```
+
+### Default Prop Values {#default-prop-values}
+
+You can define default values for your `props` by assigning to the special `defaultProps` property:
+
+```javascript
+class Greeting extends React.Component {
+  render() {
+    return (
+      <h1>Hello, {this.props.name}</h1>
+    );
+  }
+}
+
+// Specifies the default values for props:
+Greeting.defaultProps = {
+  name: 'Stranger'
+};
+
+// Renders "Hello, Stranger":
+ReactDOM.render(
+  <Greeting />,
+  document.getElementById('example')
+);
+```
+
+If you are using a Babel transform like [transform-class-properties](https://babeljs.io/docs/plugins/transform-class-properties/) , you can also declare `defaultProps` as static property within a React component class. This syntax has not yet been finalized though and will require a compilation step to work within a browser. For more information, see the [class fields proposal](https://github.com/tc39/proposal-class-fields).
+
+```javascript
+class Greeting extends React.Component {
+  static defaultProps = {
+    name: 'stranger'
+  }
+
+  render() {
+    return (
+      <div>Hello, {this.props.name}</div>
+    )
+  }
+}
+```
+
+The `defaultProps` will be used to ensure that `this.props.name` will have a value if it was not specified by the parent component. The `propTypes` typechecking happens after `defaultProps` are resolved, so typechecking will also apply to the `defaultProps`.
diff --git a/uncontrolled-components.md b/uncontrolled-components.md
new file mode 100644
index 000000000..10b6eab28
--- /dev/null
+++ b/uncontrolled-components.md
@@ -0,0 +1,84 @@
+---
+id: uncontrolled-components
+title: Uncontrolled Components
+permalink: docs/uncontrolled-components.html
+---
+
+In most cases, we recommend using [controlled components](/docs/forms.html) to implement forms. In a controlled component, form data is handled by a React component. The alternative is uncontrolled components, where form data is handled by the DOM itself.
+
+To write an uncontrolled component, instead of writing an event handler for every state update, you can [use a ref](/docs/refs-and-the-dom.html) to get form values from the DOM.
+
+For example, this code accepts a single name in an uncontrolled component:
+
+```javascript{5,9,18}
+class NameForm extends React.Component {
+  constructor(props) {
+    super(props);
+    this.handleSubmit = this.handleSubmit.bind(this);
+    this.input = React.createRef();
+  }
+
+  handleSubmit(event) {
+    alert('A name was submitted: ' + this.input.current.value);
+    event.preventDefault();
+  }
+
+  render() {
+    return (
+      <form onSubmit={this.handleSubmit}>
+        <label>
+          Name:
+          <input type="text" ref={this.input} />
+        </label>
+        <input type="submit" value="Submit" />
+      </form>
+    );
+  }
+}
+```
+
+[**Try it on CodePen**](https://codepen.io/gaearon/pen/WooRWa?editors=0010)
+
+Since an uncontrolled component keeps the source of truth in the DOM, it is sometimes easier to integrate React and non-React code when using uncontrolled components. It can also be slightly less code if you want to be quick and dirty. Otherwise, you should usually use controlled components.
+
+If it's still not clear which type of component you should use for a particular situation, you might find [this article on controlled versus uncontrolled inputs](https://goshakkk.name/controlled-vs-uncontrolled-inputs-react/) to be helpful.
+
+### Default Values {#default-values}
+
+In the React rendering lifecycle, the `value` attribute on form elements will override the value in the DOM. With an uncontrolled component, you often want React to specify the initial value, but leave subsequent updates uncontrolled. To handle this case, you can specify a `defaultValue` attribute instead of `value`.
+
+```javascript{7}
+render() {
+  return (
+    <form onSubmit={this.handleSubmit}>
+      <label>
+        Name:
+        <input
+          defaultValue="Bob"
+          type="text"
+          ref={this.input} />
+      </label>
+      <input type="submit" value="Submit" />
+    </form>
+  );
+}
+```
+
+Likewise, `<input type="checkbox">` and `<input type="radio">` support `defaultChecked`, and `<select>` and `<textarea>` supports `defaultValue`.
+
+## The file input Tag {#the-file-input-tag}
+
+In HTML, an `<input type="file">` lets the user choose one or more files from their device storage to be uploaded to a server or manipulated by JavaScript via the [File API](https://developer.mozilla.org/en-US/docs/Web/API/File/Using_files_from_web_applications).
+
+```html
+<input type="file" />
+```
+
+In React, an `<input type="file" />` is always an uncontrolled component because its value can only be set by a user, and not programmatically.
+
+You should use the File API to interact with the files. The following example shows how to create a [ref to the DOM node](/docs/refs-and-the-dom.html) to access file(s) in a submit handler:
+
+`embed:uncontrolled-components/input-type-file.js`
+
+[](codepen://uncontrolled-components/input-type-file)
+
diff --git a/web-components.md b/web-components.md
new file mode 100644
index 000000000..1c5dcd278
--- /dev/null
+++ b/web-components.md
@@ -0,0 +1,62 @@
+---
+id: web-components
+title: Web Components
+permalink: docs/web-components.html
+redirect_from:
+  - "docs/webcomponents.html"
+---
+
+React and [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) are built to solve different problems.  Web Components provide strong encapsulation for reusable components, while React provides a declarative library that keeps the DOM in sync with your data. The two goals are complementary. As a developer, you are free to use React in your Web Components, or to use Web Components in React, or both.
+
+Most people who use React don't use Web Components, but you may want to, especially if you are using third-party UI components that are written using Web Components.
+
+## Using Web Components in React {#using-web-components-in-react}
+
+```javascript
+class HelloMessage extends React.Component {
+  render() {
+    return <div>Hello <x-search>{this.props.name}</x-search>!</div>;
+  }
+}
+```
+
+> Note:
+>
+> Web Components often expose an imperative API. For instance, a `video` Web Component might expose `play()` and `pause()` functions. To access the imperative APIs of a Web Component, you will need to use a ref to interact with the DOM node directly. If you are using third-party Web Components, the best solution is to write a React component that behaves as a wrapper for your Web Component.
+>
+> Events emitted by a Web Component may not properly propagate through a React render tree.
+> You will need to manually attach event handlers to handle these events within your React components.
+
+One common confusion is that Web Components use "class" instead of "className".
+
+```javascript
+function BrickFlipbox() {
+  return (
+    <brick-flipbox class="demo">
+      <div>front</div>
+      <div>back</div>
+    </brick-flipbox>
+  );
+}
+```
+
+## Using React in your Web Components {#using-react-in-your-web-components}
+
+```javascript
+class XSearch extends HTMLElement {
+  connectedCallback() {
+    const mountPoint = document.createElement('span');
+    this.attachShadow({ mode: 'open' }).appendChild(mountPoint);
+
+    const name = this.getAttribute('name');
+    const url = 'https://www.google.com/search?q=' + encodeURIComponent(name);
+    ReactDOM.render(<a href={url}>{name}</a>, mountPoint);
+  }
+}
+customElements.define('x-search', XSearch);
+```
+
+>Note:
+>
+>This code **will not** work if you transform classes with Babel. See [this issue](https://github.com/w3c/webcomponents/issues/587) for the discussion.
+>Include the [custom-elements-es5-adapter](https://github.com/webcomponents/polyfills/tree/master/packages/webcomponentsjs#custom-elements-es5-adapterjs) before you load your web components to fix this issue.