From f829d8da088cf2c1e46aca4333920646fa0ebf4c Mon Sep 17 00:00:00 2001
From: David McCabe <davemccabe@gmail.com>
Date: Thu, 25 Aug 2022 21:10:40 +0100
Subject: [PATCH] Create Fragment API reference page (#4927)

* Create Fragment API reference page

* Minor formatting changes

Co-authored-by: Dave McCabe <davemccabe@fb.com>
Co-authored-by: Rick Hanlon <rickhanlonii@fb.com>
---
 beta/src/pages/apis/react/Fragment.md | 110 ++++++++++++++++++++++----
 beta/src/sidebarReference.json        |   3 +-
 2 files changed, 97 insertions(+), 16 deletions(-)

diff --git a/beta/src/pages/apis/react/Fragment.md b/beta/src/pages/apis/react/Fragment.md
index c7dfbbc8a..fd213d516 100644
--- a/beta/src/pages/apis/react/Fragment.md
+++ b/beta/src/pages/apis/react/Fragment.md
@@ -2,30 +2,112 @@
 title: React.Fragment
 ---
 
-<Wip>
-
-This section is incomplete, please see the old docs for [React.Fragment](https://reactjs.org/docs/react-api.html#reactfragment).
-
-</Wip>
-
-
 <Intro>
 
-The `React.Fragment` component lets you return multiple elements without creating an additional DOM element:
+The `React.Fragment` component, which can be used with a special `<></>` syntax, lets you use multiple elements in place of one, without wrapping them in any other container element:
 
 ```
 function Component() {
   return (
-    <React.Fragment>
-      Some text.
-      <h2>A heading</h2>
+    <>
+      <OneChild />
+      <AnotherChild />
+    </>
+  );
+}
+```
+
+`Fragment` is useful because grouping elements with `Fragment` has no effect on layout or styles, unlike if you wrapped the elements in some other container such as a DOM element.
+
+</Intro>
+
+- [Usage](#usage)
+  - [Returning multiple elements](#returning-multiple-elements)
+  - [Assigning multiple elements to a variable](#assigning-multiple-elements-to-a-variable)
+  - [Grouping elements with text](#grouping-elements-with-text)
+  - [Rendering a list of Fragments](#rendering-a-list-of-fragments)
+- [Reference](#reference)
+  - [React.Fragment](#react-fragment) 
+
+---
+
+## Usage {/*usage*/}
+
+### Returning multiple elements {/*returning-multiple-elements*/}
+
+Use `Fragment` to group multiple elements together. You can use it to put multiple elements in any place where a single element can go. For example, a component can only return one element, but by using `Fragment` you can group multiple elements together and then return them as a group:
+
+```
+function Notification() {
+  return (
+    <>
+      <NotificationTitle />
+      <NotificationBody />
+    </>
+  );
+}
+```
+
+You usually use `Fragment` with a special syntax, the empty JSX tag `<></>`, that is equivalent to writing `<React.Fragment></React.Fragment>`.
+
+### Assigning multiple elements to a variable {/*assigning-multiple-elements-to-a-variable*/}
+
+Like any other element, you can assign `Fragment` elements to variables, pass them as props, and so on:
+
+```
+function CloseDialog() {
+  const buttons = (
+    <>
+      <OKButton />
+      <CancelButton />
+    </>
+  );
+  return (
+    <AlertDialog buttons={buttons}>
+      Are you sure you want to leave this page?
+    </AlertDialog>
+  );
+}
+```
+
+### Grouping elements with text {/*grouping-elements-with-text*/}
+
+You can use `Fragment` to group text together with components:
+
+```
+function DateRangePicker({start, end}) {
+  return (
+    <>
+      From
+      <DatePicker date={start} />
+      to
+      <DatePicker date={end} />
+    </>
+  );
+}
+```
+
+### Rendering a list of Fragments {/*rendering-a-list-of-fragments*/}
+
+Here's a situation where you need to write `React.Fragment` explicitly instead of using the `<></>` syntax: When you [render multiple elements in a loop](/learn/rendering-lists), you need to assign a `key` to each element. If the elements within the loop are Fragments, you need to use the normal JSX element syntax in order to provide the `key` attribute:
+
+```
+function BlogPosts(posts) {
+  return posts.map(() =>
+    <React.Fragment key={post.id}>
+      <Heading>{post.title}</Heading>
+      <BlogPostBody post={post} />
     </React.Fragment>
   );
 }
 ```
 
-You can also use it with the shorthand `<></>` syntax.
+## Reference {/*reference*/}
 
-For more information, see [React v16.2.0: Improved Support for Fragments](https://reactjs.org/blog/2017/11/28/react-v16.2.0-fragment-support.html).
+### `React.Fragment` {/*react-fragment*/}
 
-</Intro>
+Wrap elements in `<React.Fragment>` to group them together in situations where you need a single element. Grouping elements in `Fragment` has no effect on the resulting DOM; it is the same as if the elements were not grouped. The empty JSX tag `<></>` is shorthand for `<React.Fragment></React.Fragment>` in most cases.
+
+#### Props {/*reference-props*/}
+
+- **optional** `key`: Fragments declared with the explicit `<React.Fragment>` syntax may have [keys](https://beta.reactjs.org/learn/rendering-lists#keeping-list-items-in-order-with-key).
diff --git a/beta/src/sidebarReference.json b/beta/src/sidebarReference.json
index 562cc2dc4..1be5fbe3e 100644
--- a/beta/src/sidebarReference.json
+++ b/beta/src/sidebarReference.json
@@ -52,8 +52,7 @@
             },
             {
               "title": "Fragment",
-              "path": "/apis/react/Fragment",
-              "wip": true
+              "path": "/apis/react/Fragment"
             },
             {
               "title": "isValidElement",