Merge pull request #392 from clemmy/fragment-docs

Add Fragment Documentation

content/docs/addons-create-fragment.md

@@ -6,7 +6,11 @@ layout: docs
 category: Add-Ons
 ---
 
-**Importing**
+> 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
 
 ```javascript
 import createFragment from 'react-addons-create-fragment'; // ES6

content/docs/fragments.md

@@ -0,0 +1,144 @@
+---
+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.
+
+Fragments look like empty JSX tags:
+
+```js
+render() {
+  return (
+    <>
+      <ChildA />
+      <ChildB />
+      <ChildC />
+    </>
+  );
+}
+```
+
+## 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>
+```
+
+So, we introduce `Fragments`.
+
+## Usage
+
+```jsx{4,7}
+class Columns extends React.Component {
+  render() {
+    return (
+      <>
+        <td>Hello</td>
+        <td>World</td>
+      </>
+    );
+  }
+}
+```
+
+which results in a correct `<Table />` output of:
+
+```jsx
+<table>
+  <tr>
+    <td>Hello</td>
+    <td>World</td>
+  </tr>
+</table>
+```
+
+You can use `<></>` the same way you'd use any other element.
+
+### Explicit Form
+
+Another way to use fragments is by using the `React.Fragment` component, which is available on the main React object.
+This may be necessary is your tooling doesn't support JSX fragments yet.
+Note that in React, `<></>` desugars to `<React.Fragment/>`.
+
+```jsx{4,7}
+class Columns extends React.Component {
+  render() {
+    return (
+      <React.Fragment>
+        <td>Hello</td>
+        <td>World</td>
+      </React.Fragment>
+    );
+  }
+}
+```
+
+### Keyed Fragments
+
+The `<></>` syntax does not accept keys nor attributes.
+
+If you need a keyed fragment, you can use `<React.Fragment />` directly. 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
+
+You can try out JSX fragment syntax with this [CodePen](https://codepen.io/reactjs/pen/VrEbjE?editors=1000).

content/docs/nav.yml

@@ -48,6 +48,8 @@
       title: Reconciliation
     - id: context
       title: Context
+    - id: fragments
+      title: Fragments
     - id: portals
       title: Portals
     - id: error-boundaries

content/docs/reference-react.md

@@ -37,12 +37,18 @@ See [Using React without JSX](/docs/react-without-jsx.html) for more information
 
 ### Transforming Elements
 
-`React` also provides some other APIs:
+`React` provides several APIs for manipulating elements:
 
 - [`cloneElement()`](#cloneelement)
 - [`isValidElement()`](#isvalidelement)
 - [`React.Children`](#reactchildren)
 
+### Fragments
+
+`React` also provides a component for rendering a multiple elements without a wrapper.
+
+- [`React.Fragment`](#reactfragment)
+
 * * *
 
 ## Reference
@@ -87,7 +93,7 @@ React.createElement(
 )
 ```
 
-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'`), or a [React component](/docs/components-and-props.html) type (a class or a function).
+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.
 
@@ -123,7 +129,7 @@ This API was introduced as a replacement of the deprecated `React.addons.cloneWi
 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'`), or a [React component](/docs/components-and-props.html) type (a class or a function).
+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.
 
@@ -192,3 +198,22 @@ Returns the `children` opaque data structure as a flat array with keys assigned
 > 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`
+
+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).