0
# React Addons Create Fragment
1

2
React Addons Create Fragment is a legacy React addon that provides functionality for creating fragments with keys to preserve element identity during reorders. This utility was designed to solve a specific problem in React 15.x where reordering two sets of children required preserving component identity without adding wrapper elements.
3

4
**Note**: This package is deprecated and no longer maintained. Modern React versions provide better alternatives through explicit key props on array elements and React.Fragment.
5

6
## Package Information
7

8
- **Package Name**: react-addons-create-fragment
9
- **Package Type**: npm
10
- **Language**: JavaScript (CommonJS)
11
- **Installation**: `npm install react-addons-create-fragment`
12
- **Status**: Deprecated (React 15.x legacy addon)
13

14
## Core Imports
15

16
ES6:
17
```javascript
18
import createFragment from 'react-addons-create-fragment';
19
```
20

21
CommonJS:
22
```javascript
23
const createFragment = require('react-addons-create-fragment');
24
```
25

26
Browser script tag (after loading React):
27
```html
28
<!-- development version -->
29
<script src="https://unpkg.com/react-addons-create-fragment/react-addons-create-fragment.js"></script>
30

31
<!-- production version -->
32
<script src="https://unpkg.com/react-addons-create-fragment/react-addons-create-fragment.min.js"></script>
33
```
34

35
When loaded via script tag, the function is available as `React.addons.createFragment`:
36

37
```javascript
38
// After loading React and the addon script
39
const fragment = React.addons.createFragment({
40
  first: React.createElement('span', null, 'First'),
41
  second: React.createElement('span', null, 'Second')
42
});
43
```
44

45
## Basic Usage
46

47
The primary use case is creating keyed fragments to preserve element identity when reordering two sets of children:
48

49
```javascript
50
import createFragment from 'react-addons-create-fragment';
51
import React from 'react';
52

53
function Swapper(props) {
54
  let children;
55
  if (props.swapped) {
56
    children = createFragment({
57
      right: props.rightChildren,
58
      left: props.leftChildren
59
    });
60
  } else {
61
    children = createFragment({
62
      left: props.leftChildren, 
63
      right: props.rightChildren
64
    });
65
  }
66
  return React.createElement('div', null, children);
67
}
68

69
// Usage
70
const leftContent = React.createElement('span', {key: 'left'}, 'Left Content');
71
const rightContent = React.createElement('span', {key: 'right'}, 'Right Content');
72

73
const swapper = React.createElement(Swapper, {
74
  leftChildren: leftContent,
75
  rightChildren: rightContent,
76
  swapped: false
77
});
78
```
79

80
## Capabilities
81

82
### Fragment Creation
83

84
Creates a React fragment from an object, assigning keys to preserve element identity during reorders.
85

86
```javascript { .api }
87
/**
88
 * Creates a React fragment from an object where keys become React keys
89
 * and values are React elements or components.
90
 * 
91
 * Note: The actual function is named createReactFragment internally but is
92
 * exported as the default export, making it available as createFragment when imported.
93
 * When loaded via script tag, it's available as React.addons.createFragment.
94
 * 
95
 * @param {Object} object - Object with keys as React keys and values as React elements
96
 * @returns {Array<ReactNode>} Array of React elements with proper keys assigned
97
 */
98
function createFragment(object);
99
```
100

101
**Parameters:**
102
- `object` (Object): An object where:
103
  - Keys become React keys for element identity preservation
104
  - Values are React elements, components, or renderable content
105
  - Must be a single object (not array, null, undefined, or ReactElement)
106

107
**Return Value:**
108
- `Array<ReactNode>`: An opaque array of React elements with assigned keys
109
- The returned array should be treated as opaque and used directly as React children
110
- Individual elements maintain their identity through the assigned keys
111

112
**Behavior:**
113
- Iterates through object properties in enumeration order (relies on JavaScript engine object key ordering)
114
- Assigns object keys as React keys to preserve element identity during reorders
115
- Validates input to ensure it's a proper object (not array, null, or ReactElement)
116
- Handles nested React elements and maintains key hierarchy
117
- Processes children recursively to ensure proper key assignment throughout the tree
118

119
**Error Handling:**
120
- **Invalid Input**: Warns and returns original value for arrays, null, undefined
121
  - Warning: "React.addons.createFragment only accepts a single object. Got: [value]"
122
- **ReactElement Input**: Warns against passing ReactElements without wrapper objects
123
  - Warning: "React.addons.createFragment does not accept a ReactElement without a wrapper object."
124
- **DOM Elements**: Throws invariant error if DOM elements are detected as children
125
  - Error: "React.addons.createFragment(...): Encountered an invalid child; DOM elements are not valid children of React components."
126
- **Numeric Keys**: Warns when object has numeric keys (ordering preservation concerns)
127
  - Warning: "React.addons.createFragment(...): Child objects should have non-numeric keys so ordering is preserved."
128
- **Invalid Children**: Throws invariant error for objects that aren't valid React children
129

130
**Usage Examples:**
131

132
Basic fragment creation:
133
```javascript
134
import createFragment from 'react-addons-create-fragment';
135
import React from 'react';
136

137
const fragment = createFragment({
138
  header: React.createElement('h2', null, 'Title'),
139
  content: React.createElement('p', null, 'Content'),
140
  footer: React.createElement('small', null, 'Footer')
141
});
142

143
// Use as children
144
const container = React.createElement('div', null, fragment);
145
```
146

147
Reordering scenario:
148
```javascript
149
function ReorderableList(props) {
150
  const { items, reversed } = props;
151
  
152
  if (reversed) {
153
    return createFragment({
154
      second: items[1],
155
      first: items[0]
156
    });
157
  } else {
158
    return createFragment({
159
      first: items[0],
160
      second: items[1] 
161
    });
162
  }
163
}
164
```
165

166
Complex nested content:
167
```javascript
168
const complexFragment = createFragment({
169
  sidebar: React.createElement('aside', null, [
170
    React.createElement('nav', {key: 'nav'}, 'Navigation'),
171
    React.createElement('ul', {key: 'menu'}, 'Menu items')
172
  ]),
173
  main: React.createElement('main', null, [
174
    React.createElement('article', {key: 'article'}, 'Article content'),
175
    React.createElement('section', {key: 'comments'}, 'Comments')
176
  ])
177
});
178
```
179

180
## Dependencies
181

182
**Runtime Dependencies:**
183
- `react` (peer dependency) - Core React library for element creation and validation
184
- `fbjs` - Facebook JavaScript utilities
185
  - `fbjs/lib/emptyFunction` - Empty function utilities
186
  - `fbjs/lib/invariant` - Assertion and error handling
187
  - `fbjs/lib/warning` - Development warnings
188
- `object-assign` - Object assignment polyfill for older environments
189
- `loose-envify` - Environment variable transformation for builds
190

191
## Browser Compatibility
192

193
- **Node.js**: All versions supported by React 15.x
194
- **Browsers**: All browsers supported by React 15.x
195
- **Build**: Includes UMD builds for browser usage
196
- **Environment**: Works in both development and production builds