Skip to content

Commit 0e3e124

Browse files
acdliteacdlite
authored
Merge pull request #345 from clemmy/fragments-blog-post
Add release jsx fragment blog post
2 parents 5efca01 + cdde744 commit 0e3e124

File tree

3 files changed

+329
-1
lines changed

3 files changed

+329
-1
lines changed

‎content/authors.yml

+3
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,9 @@ benigeri:
1010
chenglou:
1111
name: Cheng Lou
1212
url: https://twitter.com/_chenglou
13+
clemmy:
14+
name: Clement Hoang
15+
url: https://twitter.com/c8hoang
1316
Daniel15:
1417
name: Daniel Lo Nigro
1518
url: http://dan.cx/

‎content/blog/2017-11-28-react-v16.2.0-fragment-support.md

+325
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,325 @@
1+
---
2+
title: "React v16.2.0: Improved Support for Fragments"
3+
author: [clemmy]
4+
---
5+
6+
React 16.2 is now available! The biggest addition is improved support for returning multiple children from a component's render method. We call this feature *fragments*:
7+
8+
Fragments look like empty JSX tags. They let you group a list of children without adding extra nodes to the DOM:
9+
10+
```js
11+
render() {
12+
return (
13+
<>
14+
<ChildA />
15+
<ChildB />
16+
<ChildC />
17+
</>
18+
);
19+
}
20+
```
21+
22+
This exciting new feature is made possible by additions to both React and JSX.
23+
24+
## What Are Fragments?
25+
26+
A common pattern is for a component to return a list of children. Take this example HTML:
27+
28+
```html
29+
Some text.
30+
<h2>A heading</h2>
31+
More text.
32+
<h2>Another heading</h2>
33+
Even more text.
34+
```
35+
36+
Prior to version 16, the only way to acheive this in React was by wrapping the children in an extra element, usually a `div` or `span`:
37+
38+
```js
39+
render() {
40+
return (
41+
// Extraneous div element :(
42+
<div>
43+
Some text.
44+
<h2>A heading</h2>
45+
More text.
46+
<h2>Another heading</h2>
47+
Even more text.
48+
</div>
49+
);
50+
}
51+
```
52+
53+
To address this limitation, React 16.0 added support for [returning an array of elements from a component's `render` method](https://reactjs.org/blog/2017/09/26/react-v16.0.html#new-render-return-types-fragments-and-strings). Instead of wrapping the children in a DOM element, you can put them into an array:
54+
55+
```jsx
56+
render() {
57+
return [
58+
"Some text.",
59+
<h2 key="heading-1">A heading</h2>,
60+
"More text."
61+
<h2 key="heading-2">Another heading</h2>,
62+
"Even more text."
63+
];
64+
}
65+
```
66+
67+
However, this has some confusing differences from normal JSX:
68+
69+
- Children in an array must be separated by commas.
70+
- Children in an array must have a key to prevent React's [key warning](https://reactjs.org/docs/lists-and-keys.html#keys).
71+
- Strings must be wrapped in quotes.
72+
73+
To provide a more consistent authoring experience for fragments, React now provides a first-class `Fragment` component that can be used in place of arrays.
74+
75+
```jsx{3,9}
76+
render() {
77+
return (
78+
<Fragment>
79+
Some text.
80+
<h2>A heading</h2>
81+
More text.
82+
<h2>Another heading</h2>
83+
Even more text.
84+
</Fragment>
85+
);
86+
}
87+
```
88+
89+
You can use `<Fragment />` the same way you'd use any other element, without changing the way you write JSX. No commas, no keys, no quotes.
90+
91+
The Fragment component is available on the main React object:
92+
93+
```js
94+
const Fragment = React.Fragment;
95+
96+
<Fragment>
97+
<ChildA />
98+
<ChildB />
99+
<ChildC />
100+
</Fragment>
101+
102+
// This also works
103+
<React.Fragment>
104+
<ChildA />
105+
<ChildB />
106+
<ChildC />
107+
</React.Fragment>
108+
```
109+
110+
## JSX Fragment Syntax
111+
112+
Fragments are a common pattern in our codebases at Facebook. We anticipate they'll be widely adopted by other teams, too. To make the authoring experience as convenient as possible, we're adding syntactical support for fragments to JSX:
113+
114+
```jsx{3,9}
115+
render() {
116+
return (
117+
<>
118+
Some text.
119+
<h2>A heading</h2>
120+
More text.
121+
<h2>Another heading</h2>
122+
Even more text.
123+
</>
124+
);
125+
}
126+
```
127+
128+
In React, this desugars to a `<React.Fragment/>` element, as in the example from the previous section. (Non-React frameworks that use JSX may compile to something different.)
129+
130+
Fragment syntax in JSX was inspired by prior art such as the `XMLList() <></>` constructor in [E4X](https://developer.mozilla.org/en-US/docs/Archive/Web/E4X/E4X_for_templating). Using a pair of empty tags is meant to represent the idea it won't add an actual element to the DOM.
131+
132+
### Keyed Fragments
133+
134+
Note that the `<></>` syntax does not accept attributes, including keys.
135+
136+
If you need a keyed fragment, you can use `<Fragment />` directly. An use case for this is mapping a collection to an array of fragments -- for example, to create a description list:
137+
138+
```jsx
139+
function Glossary(props) {
140+
return (
141+
<dl>
142+
{props.items.map(item => (
143+
// Without the `key`, React will fire a key warning
144+
<Fragment key={item.id}>
145+
<dt>{item.term}</li>
146+
<dd>{item.description}</li>
147+
</Fragment>
148+
)}
149+
</dl>
150+
);
151+
}
152+
```
153+
154+
`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.
155+
156+
### Live Demo
157+
158+
You can experiment with JSX fragment syntax with this [CodePen](https://codepen.io/reactjs/pen/VrEbjE?editors=1000).
159+
160+
## Support for Fragment Syntax
161+
162+
Support for fragment syntax in JSX will vary depending on the tools you use to build your app. Please be patient as the JSX community works to adopt the new syntax. We've been working closely with maintainers of the most popular projects:
163+
164+
### Create React App
165+
166+
Experimental support for fragment syntax will be added to Create React App within the next few days. A stable release may take a bit longer as we await adoption by upstream projects.
167+
168+
### Babel
169+
170+
Support for JSX fragments is available in [Babel v7.0.0-beta.31](https://github.com/babel/babel/releases/tag/v7.0.0-beta.31) and above! If you are already on Babel 7, simply update to the latest Babel and plugin transform:
171+
172+
```bash
173+
# for yarn users
174+
yarn upgrade @babel/core @babel/plugin-transform-react-jsx
175+
# for npm users
176+
npm update @babel/core @babel/plugin-transform-react-jsx
177+
```
178+
179+
Or if you are using the [react preset](https://www.npmjs.com/package/@babel/preset-react):
180+
181+
```bash
182+
# for yarn users
183+
yarn upgrade @babel/core @babel/preset-react
184+
# for npm users
185+
npm update @babel/core @babel/preset-react
186+
```
187+
188+
Note that Babel 7 is technically still in beta, but a [stable release is coming soon](https://babeljs.io/blog/2017/09/12/planning-for-7.0).
189+
190+
Unfortunately, support for Babel 6.x is not available, and there are currently no plans to backport.
191+
192+
#### Babel with Webpack (babel-loader)
193+
194+
If you are using Babel with [Webpack](https://webpack.js.org/), no additional steps are needed because [babel-loader](https://github.com/babel/babel-loader) will use your peer-installed version of Babel.
195+
196+
#### Babel with Other Frameworks
197+
198+
If you use JSX with a non-React framework like Inferno or Preact, there is a [pragma option available in babel-plugin-transform-react-jsx](https://github.com/babel/babel/tree/master/packages/babel-plugin-transform-react-jsx#pragmafrag) that configures the Babel compiler to de-sugar the `<></>` syntax to a custom identifier.
199+
200+
### TypeScript
201+
202+
TypeScript has full support for fragment syntax! Please upgrade to [version 2.6.2](https://github.com/Microsoft/TypeScript/releases/tag/v2.6.2). (Note that this is important even if you are already on version 2.6.1, since support was added as patch release in 2.6.2.)
203+
204+
Upgrade to the latest TypeScript with the command:
205+
206+
```bash
207+
# for yarn users
208+
yarn upgrade typescript
209+
# for npm users
210+
npm update typescript
211+
```
212+
213+
### Flow
214+
215+
[Flow](https://flow.org/) support for JSX fragments is available starting in [version 0.59](https://github.com/facebook/flow/releases/tag/v0.59.0)! Simply run
216+
217+
```bash
218+
# for yarn users
219+
yarn upgrade flow-bin
220+
# for npm users
221+
npm update flow-bin
222+
```
223+
224+
to update Flow to the latest version.
225+
226+
### Prettier
227+
228+
[Prettier](https://github.com/prettier/prettier) will have support for fragments in their upcoming [1.9 release](https://github.com/prettier/prettier/pull/3237).
229+
230+
### ESLint
231+
232+
JSX Fragments are supported by [ESLint](https://eslint.org/) via [babel-eslint](https://github.com/babel/babel-eslint)! If you are not currently using it, then install it:
233+
234+
```bash
235+
# for yarn users
236+
yarn add eslint@3.x babel-eslint@7
237+
# for npm users
238+
npm install eslint@3.x babel-eslint@7
239+
```
240+
241+
or if you already have it, then upgrade:
242+
243+
```bash
244+
# for yarn users
245+
yarn upgrade eslint@3.x babel-eslint@7
246+
# for npm users
247+
npm update eslint@3.x babel-eslint@7
248+
```
249+
250+
Ensure you have the following line inside your `.babelrc`:
251+
252+
```json
253+
"parser": "babel-eslint"
254+
```
255+
256+
That's it!
257+
258+
### Editor Support
259+
260+
It may take a while for fragment syntax to be supported in your text editor. Please be patient as the community works to adopt the latest changes. In the meantime, you may see errors or inconsistent highlighting if your editor does not yet support fragment syntax. Generally, these errors can be safely ignored.
261+
262+
#### TypeScript Editor Support
263+
264+
If you're a TypeScript user -- great news! Editor support for JSX fragments is already available in [Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48593), [Visual Studio 2017](https://www.microsoft.com/en-us/download/details.aspx?id=55258), and [Sublime Text via Package Control](https://packagecontrol.io/packages/TypeScript). Visual Studio Code will be updated soon, but [can be configured to use TypeScript 2.6.2 and later](https://code.visualstudio.com/Docs/languages/typescript#_using-newer-typescript-versions).
265+
266+
### Other Tools
267+
268+
For other tools, please check with the corresponding documentation to check if there is support available. However, if you're blocked by your tooling, you can always start with using the `<Fragment>` component and perform a codemod later to replace it with the shorthand syntax when the appropriate support is available.
269+
270+
## Installation
271+
272+
React v16.2.0 is available on the npm registry.
273+
274+
To install React 16 with Yarn, run:
275+
276+
```bash
277+
yarn add react@^16.2.0 react-dom@^16.2.0
278+
```
279+
280+
To install React 16 with npm, run:
281+
282+
```bash
283+
npm install --save react@^16.2.0 react-dom@^16.2.0
284+
```
285+
286+
We also provide UMD builds of React via a CDN:
287+
288+
```html
289+
<script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
290+
<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>
291+
```
292+
293+
Refer to the documentation for [detailed installation instructions](/docs/installation.html).
294+
295+
## Changelog
296+
297+
### React
298+
299+
* Add `Fragment` as named export to React. ([@clemmy](https://github.com/clemmy) in [#10783](https://github.com/facebook/react/pull/10783))
300+
* Support experimental Call/Return types in `React.Children` utilities. ([@MatteoVH](https://github.com/MatteoVH) in [#11422](https://github.com/facebook/react/pull/11422))
301+
302+
### React DOM
303+
304+
* Fix radio buttons not getting checked when using multiple lists of radios. ([@landvibe](https://github.com/landvibe) in [#11227](https://github.com/facebook/react/pull/11227))
305+
* Fix radio buttons not receiving the `onChange` event in some cases. ([@jquense](https://github.com/jquense) in [#11028](https://github.com/facebook/react/pull/11028))
306+
307+
### React Test Renderer
308+
309+
* Fix `setState()` callback firing too early when called from `componentWillMount`. ([@accordeiro](https://github.com/accordeiro) in [#11507](https://github.com/facebook/react/pull/11507))
310+
311+
### React Reconciler
312+
313+
* Expose `react-reconciler/reflection` with utilities useful to custom renderers. ([@rivenhk](https://github.com/rivenhk) in [#11683](https://github.com/facebook/react/pull/11683))
314+
315+
### Internal Changes
316+
317+
* Many tests were rewritten against the public API. Big thanks to [everyone who contributed](https://github.com/facebook/react/issues/11299)!
318+
319+
## Acknowledgments
320+
321+
This release was made possible by our open source contributors. A big thanks to everyone who filed issues, contributed to syntax discussions, reviewed pull requests, added support for JSX fragments in third party libraries, and more!
322+
323+
Special thanks to the [TypeScript](https://www.typescriptlang.org/) and [Flow](https://flow.org/) teams, as well as the [Babel](https://babeljs.io/) maintainers, who helped make tooling support for the new syntax go seamlessly.
324+
325+
Thanks to [Gajus Kuizinas](https://github.com/gajus/) and other contributors who prototyped the `Fragment` component in open source.

‎src/site-constants.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
// NOTE: We can't just use `location.toString()` because when we are rendering
1111
// the SSR part in node.js we won't have a proper location.
1212
const urlRoot = 'https://reactjs.org';
13-
const version = '16.1.1';
13+
const version = '16.2.0';
1414
const babelURL = '//unpkg.com/[email protected]/babel.min.js';
1515

1616
export {urlRoot, version, babelURL};

0 commit comments

Comments
 (0)