52b694eaae
Adds a new docs website, built with Gatsby JS, to replace the old Jekyll site. Source code for the new site lives in /www (although markdown and YML data still comes from the legacy /docs folder). Changes to either markdown or website source code can be previewed on Netlify. The react-js bot should automatically add comments to each PR with preview links. (This preview is generated by running the newly-added yarn build:docs command in the root package.json.) The majority of the changes in this PR are contained within the new /www directory. However some minor modifications have been made to existing content in the /docs directory: * Modified frontmatter author block to always be an array * Small markdown formatting tweaks
2.3 KiB
id, title, permalink, layout, category
| id | title | permalink | layout | category |
|---|---|---|---|---|
| create-fragment | Keyed Fragments | docs/create-fragment.html | docs | Add-Ons |
Importing
import createFragment from 'react-addons-create-fragment'; // ES6
var createFragment = require('react-addons-create-fragment'); // ES5 with npm
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:
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)
Instead of creating arrays, we write:
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 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.