React Children Flattener

1.1.2 · active · verified Sun Apr 19

`react-flatten-children` is a lightweight React utility library designed to resolve challenges associated with React Fragments when processing component children. In React, fragments (`<></>` or `<React.Fragment>`) group multiple children but are treated as single children by their parent, which can disrupt components expecting direct access to all child elements (e.g., `react-router`'s `Switch` component looking for `Route` children). This package offers a single function, `flattenChildren`, which recursively traverses a component's `children` prop, extracts all valid React elements, and returns them as a flat array. This effectively "unwraps" fragments, ensuring all nested children are accessible. The current stable version is 1.1.2, with recent updates primarily adding TypeScript support in v1.1.0. Its primary value lies in simplifying child manipulation for library authors and application developers alike, preventing common issues where fragment usage can lead to unexpected component behavior or errors during child introspection. It helps maintain compatibility with user expectations of flexible fragment usage within component APIs.

Common errors

```
Type 'ReactNode' is not assignable to type 'ReactElement<any, string | JSXElementConstructor<any>>[]'.
```
cause In TypeScript, the `children` prop has a broad type (`ReactNode`) that includes fragments, `null`, `undefined`, etc. Direct assignment or iteration expecting `ReactElement[]` will fail if fragments are present.

fix Use `const flatChildren: ReactElement[] = flattenChildren(children);` to correctly type the flattened output as an array of React elements.
```
Error: `Router` may have only one child element at `Switch` (from React Router or similar libraries)
```
cause A component expects a single direct child, but it receives a React Fragment which contains multiple children, or it receives a fragment when it expects a specific element type directly.

fix Apply `flattenChildren(children)` to the children prop before passing it to the component that expects a flat list of direct children, like `<Switch>{flattenChildren(children)}</Switch>`.

Warnings

gotcha When building components that introspect or iterate over their children (e.g., React Router's Switch or a custom tab component), React Fragments (<>...</> or <React.Fragment>...</React.Fragment>) are treated as single children. This prevents the parent component from directly accessing the elements nested inside the fragment, leading to unexpected rendering or logic failures if the component expects a flat list of specific child types.
Fix: Always pass children through `flattenChildren(children)` before processing them to ensure a flat array of all nested elements, enabling proper child introspection.
gotcha Earlier versions of `react-flatten-children` (prior to v1.1.0) did not include native TypeScript type definitions. Developers using TypeScript would have needed to create their own declaration files or use type assertions, which could lead to type safety issues or additional maintenance overhead.
Fix: Upgrade to `react-flatten-children@^1.1.0` or newer to leverage official, built-in TypeScript types, improving type safety and developer experience.

Install

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

Imports

flattenChildren
wrong:
```
import { flattenChildren } from 'react-flatten-children';
```
correct:
```
import flattenChildren from 'react-flatten-children';
```
'flattenChildren' is the default export of the library. Attempting to destructure it as a named import will result in 'undefined'.
flattenChildren (CJS)
```
const flattenChildren = require('react-flatten-children');
```
This is the CommonJS import pattern suitable for Node.js environments or older build systems.

FlatChildren (TypeScript Type)

import flattenChildren, { FlatChildren } from 'react-flatten-children';

function MyComponent({ children }: { children: React.ReactNode }) {
  const flatChildren: FlatChildren = flattenChildren(children);
  // flatChildren is now typed as ReactElement[]
}

TypeScript type definitions, including the 'FlatChildren' type for the returned array, were officially added in v1.1.0. Prior versions required manual type declarations.

Quickstart

This example demonstrates how to use `flattenChildren` to make a `react-router` Switch component compatible with React Fragments, allowing routes to be conditionally grouped within fragments.

import React from 'react';
import { Switch as BaseSwitch, Route, Redirect } from 'react-router';
import flattenChildren from 'react-flatten-children';

// Imagine these are your page components
const PublicHome = () => <div>Public Home</div>;
const PrivateHome = () => <div>Private Home</div>;
const Account = () => <div>Account Page</div>;
const Login = () => <div>Login Page</div>;
const About = () => <div>About Page</div>;

// Create a fragment-ready Switch component that can handle nested fragments
const Switch = ({ children }) => (
  <BaseSwitch>{flattenChildren(children)}</BaseSwitch>
);

const Routes = ({ isLoggedIn }) => (
  <Switch>
    {isLoggedIn ? (
      <>
        <Route exact path="/" component={PrivateHome} />
        <Route path="/account" component={Account} />
      </>
    ) : (
      <>
        <Route exact path="/" component={PublicHome} />
        <Route path="/login" component={Login} />
      </>
    )}
    <Route path="/about" component={About} />
    <Redirect to="/" />
  </Switch>
);

export default Routes;

view raw JSON →