Lodash _.flattenDeep() method
What you’ll learn
- How
_.flattenDeep(array)walks arbitrary nesting and returns a single-level result. - When to choose it over _.flatten() or a bounded
_.flattenDepth. - How it compares to
array.flat(Infinity)and what pitfalls to watch for. - Try each example in the editor (
?tryit=1,2,3) with Lodash from a CDN.
Prerequisites
Read _.flatten() on this site so the difference between one level and full recursion is clear.
- You are comfortable with nested array literals and recursion as a concept (even if Lodash implements the walk for you).
- You can run snippets in Node or open the Try-it labs in a browser.
Overview
_.flattenDeep is the “keep going” variant: every nested array is opened until only non-array values remain. Use it for JSON trees, CSV rows parsed as nested lists, or legacy APIs that return unpredictable bracket depth.
Full depth
No manual loop counting how many times to call flatten.
New array
The original nested arrays are untouched; you get a flat copy of leaf values in order.
Leaves only
Objects, numbers, and strings are not split; only array wrappers disappear.
Syntax
_.flattenDeep(array)- array: collection that may contain nested arrays at any depth (array-like values are coerced).
- Returns: a new array containing every non-array element in depth-first order after all array wrappers are removed.
Arbitrary nesting
Multiple bracket layers collapse into one linear list while preserving numeric order.
import flattenDeep from "lodash/flattenDeep";
flattenDeep([1, [2, [3, [4]]]]);
// [1, 2, 3, 4]Empty inner arrays
Empty brackets add no elements; they vanish instead of producing undefined slots.
import flattenDeep from "lodash/flattenDeep";
flattenDeep([[], [1], [[2, 3]]]);
// [1, 2, 3]Objects are not flattened
Only arrays are unwrapped. Plain objects stay as single values in the result.
import flattenDeep from "lodash/flattenDeep";
flattenDeep([{ id: 1 }, [[{ id: 2 }]]]);
// [{ id: 1 }, { id: 2 }]📋 _.flattenDeep vs _.flatten vs native
| API | Depth | Note |
|---|---|---|
_.flattenDeep(array) | All nested arrays | Best when depth is unknown or varies per payload |
_.flatten(array) | One level | Faster and clearer when you know the shape is at most one array deep |
array.flat(Infinity) | All nested arrays | Native ES2019; similar outcome on real arrays |
_.flattenDepth(array, n) | Exactly n levels | Middle ground between the two extremes |
Pitfalls to avoid
Very deep trees
Extreme nesting can stress the engine stack or heap. For hostile input, validate depth before flattening.
Circular references
A structure that points back at itself is not a valid tree; flattening can loop or throw. Sanitize untrusted data first.
Not a structural clone
You still share object references with the source. Use a dedicated clone utility if you need isolation.
❓ FAQ
Summary
- Purpose:
_.flattenDeep(array)returns a new fully flattened array (no nested arrays remain). - Safety: the input array is not mutated.
- Next: Lodash _.flattenDepth(), _.flatten() (earlier in this track), or the array methods hub.
When you only need a fixed number of levels, _.flattenDepth(array, n) avoids unbounded recursion while still returning a new array.
About the author
6 people found this page helpful