React Addons Create Fragment

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.

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.

Package Information

• Package Name: react-addons-create-fragment
• Package Type: npm
• Language: JavaScript (CommonJS)
• Installation: npm install react-addons-create-fragment
• Status: Deprecated (React 15.x legacy addon)

Core Imports

ES6:

import createFragment from 'react-addons-create-fragment';

CommonJS:

const createFragment = require('react-addons-create-fragment');

Browser script tag (after loading React):

<!-- development version -->
<script src="https://unpkg.com/react-addons-create-fragment/react-addons-create-fragment.js"></script>

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

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

// After loading React and the addon script
const fragment = React.addons.createFragment({
  first: React.createElement('span', null, 'First'),
  second: React.createElement('span', null, 'Second')
});

Basic Usage

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

import createFragment from 'react-addons-create-fragment';
import React from 'react';

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 React.createElement('div', null, children);
}

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

const swapper = React.createElement(Swapper, {
  leftChildren: leftContent,
  rightChildren: rightContent,
  swapped: false
});

Capabilities

Fragment Creation

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

/**
 * Creates a React fragment from an object where keys become React keys
 * and values are React elements or components.
 * 
 * Note: The actual function is named createReactFragment internally but is
 * exported as the default export, making it available as createFragment when imported.
 * When loaded via script tag, it's available as React.addons.createFragment.
 * 
 * @param {Object} object - Object with keys as React keys and values as React elements
 * @returns {Array<ReactNode>} Array of React elements with proper keys assigned
 */
function createFragment(object);

Parameters:

• object (Object): An object where:
  • Keys become React keys for element identity preservation
  • Values are React elements, components, or renderable content
  • Must be a single object (not array, null, undefined, or ReactElement)

Return Value:

• Array<ReactNode>: An opaque array of React elements with assigned keys
• The returned array should be treated as opaque and used directly as React children
• Individual elements maintain their identity through the assigned keys

Behavior:

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

Error Handling:

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

Usage Examples:

Basic fragment creation:

import createFragment from 'react-addons-create-fragment';
import React from 'react';

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

// Use as children
const container = React.createElement('div', null, fragment);

Reordering scenario:

function ReorderableList(props) {
  const { items, reversed } = props;
  
  if (reversed) {
    return createFragment({
      second: items[1],
      first: items[0]
    });
  } else {
    return createFragment({
      first: items[0],
      second: items[1] 
    });
  }
}

Complex nested content:

const complexFragment = createFragment({
  sidebar: React.createElement('aside', null, [
    React.createElement('nav', {key: 'nav'}, 'Navigation'),
    React.createElement('ul', {key: 'menu'}, 'Menu items')
  ]),
  main: React.createElement('main', null, [
    React.createElement('article', {key: 'article'}, 'Article content'),
    React.createElement('section', {key: 'comments'}, 'Comments')
  ])
});

Dependencies

Runtime Dependencies:

• react (peer dependency) - Core React library for element creation and validation
• fbjs - Facebook JavaScript utilities
  • fbjs/lib/emptyFunction - Empty function utilities
  • fbjs/lib/invariant - Assertion and error handling
  • fbjs/lib/warning - Development warnings
• object-assign - Object assignment polyfill for older environments
• loose-envify - Environment variable transformation for builds

Browser Compatibility

• Node.js: All versions supported by React 15.x
• Browsers: All browsers supported by React 15.x
• Build: Includes UMD builds for browser usage
• Environment: Works in both development and production builds