Skip to content
Flattens React children and fragments to an array with predictable and stable keys
TypeScript
Branch: master
Clone or download
Latest commit d0eb647 Feb 11, 2020
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore Initial commit Nov 20, 2019
.prettierrc Initial commit Nov 20, 2019
.travis.yml
CHANGELOG.md 1.2.0 Feb 3, 2020
LICENSE Update README, add LICENSE Nov 20, 2019
README.md Update README Feb 11, 2020
index.spec.tsx Avoid adding extra first period at zero depth Nov 22, 2019
index.ts Avoid adding extra first period at zero depth Nov 22, 2019
package.json 1.2.0 Feb 3, 2020
tsconfig.json Initial commit Nov 20, 2019
yarn.lock Initial commit Nov 20, 2019

README.md

react-keyed-flatten-children

Build Status

Similar to React's built-in Children.toArray method, this utility takes children and returns them as an array for introspection or filtering. Different from Children.toArray, it will flatten arrays and React.Fragments into a regular, one-dimensional array while ensuring element and fragment keys are preserved, unique, and stable between renders.

getting started

npm install react-keyed-flatten-children
yarn add react-keyed-flatten-children

why?

From the documentation of Children.toArray:

[toArray] returns the children opaque data structure as a flat array with keys assigned to each child. Useful if you want to manipulate collections of children in your render methods, especially if you want to reorder or slice this.props.children before passing it down.

Unfortunately it has some thorny edges:

  • Children.toArray does not traverse into fragments, which limits flexibility of its use.
  • Existing solutions exist, but they do not preserve the keys of the children and fragments, which throws away valuable performance optimisations provided through React keys.
  • You're might be doing something a little wild, so you want the concept of "children" to as predictable as possible for you, and for the consumers of your library or component, to avoid issues like this down the line.

Some have proposed, soon after Fragments were introduced, that a built-in React.Children.toFlatArray would be useful, but

View the codesandbox here to get hands-on with how and when to utilise this module.

for using this in your app

I've written a more application-focussed explanation in my article "Addressing Children.toArray's thorny edges".

for library authors

In most cases react-keyed-flatten-children is a drop-in replacement for Children.toArray.

import flattenChildren from "react-keyed-flatten-children";

const MenuList = ({ children }) => {
  const [selectedKey, setSelectedKey] = useState(null);

  return (
    <div role="menu">
      {flattenChildren(props.children).map(child => {
        if (child.type === MenuItem) {
          return React.cloneElement(child, {
            selected: child.key === selectedKey,
            onClick: () => setSelectedKey(child.key)
          });
        }
        return child;
      })}
    </div>
  );
};

Now consumers can use arrays, fragments, or conditionally render items and your library will continue to work predictably.

<MenuList>
  <h2>Animals</h2>
  <MenuItem>Dogs</MenuItem>
  <MenuItem>Cats</MenuItem>

  <h2>Cars</h2>
  {CARS_ARRAY.map(car => (
    <MenuItem>{car}</MenuItem>
  ))}

  {isLoggedIn() && (
    <>
      <h2>User</h2>
      <MenuItem>You!</MenuItem>
      <MenuItem>Someone else!</MenuItem>
    </>
  )
</MenuList>

for everyone else

Work around libraries which don't support fragments passed into children.

import flattenChildren from "react-keyed-flatten-children";
import { Switch, Route } from "react-router";

// A <Switch> looks through its children <Routes>, but won't match <Routes> within fragments.
// <FlexibleSwitch> will flatten out its children so <Switch> is able to see all children.
const FlexibleSwitch = ({ children }) => (
  <Switch>{flattenChildren(children)}</Switch>
);

const AppRoutes = ({ user }) => (
  <Router>
    <GlobalNavigation user={user} />
    <Switch>
      <Route path="/about">
        <About />
      </Route>
      {user && (
        <>
          <Route path="/users">
            <Users />
          </Route>
          <Route path="/settings">
            <Settings />
          </Route>
        </>
      )}
      <Route path="/">
        <Home />
      </Route>
    </Switch>
  </Router>
);

license

MIT

You can’t perform that action at this time.