Lodash _.flatten() method
What you’ll learn
- How
_.flatten(array)produces a new one-level-flatter array. - Why double-nested arrays still contain an inner array after a single flatten pass.
- How this compares to
Array.prototype.flat(1)and when to reach for_.flattenDeep. - Try each example in the editor (
?tryit=1,2,3) with Lodash from a CDN.
Prerequisites
Optional context: _.chunk() builds nested arrays; _.findLastIndex() sits earlier on the same tutorial track.
- You know that nested arrays are still normal values at the outer index until you unwrap them.
- You can run snippets in Node or open the Try-it labs in a browser.
Overview
_.flatten is the shallow un-nester: every element that is itself an array becomes its children in order, one time only. It is the right default when you control the shape (for example API batches that are at most one array deep) and want predictable performance.
One level
Perfect when you only need to peel a single wrapper, not arbitrary tree depth.
New array
The input array is unchanged; the result is a fresh linear sequence of references.
Pairs with chunk
A common pattern is chunk then later flatten when you are done grouping.
Syntax
_.flatten(array)- array: collection whose top-level elements may be arrays (array-like values are coerced).
- Returns: a new array where each top-level array element is replaced by its contents, in order. Non-array elements are copied through unchanged.
Typical nested batch
Two inner arrays become one sequence preserving left-to-right order.
import flatten from "lodash/flatten";
flatten([[1, 2], [3, 4]]);
// [1, 2, 3, 4]Still nested after one pass
The innermost [3] started two levels deep; after flatten once you still have an array at index 2.
import flatten from "lodash/flatten";
flatten([1, [2, [3]]]);
// [1, 2, [3]]Mix of values and arrays
Scalars pass through; only array elements expand into the result.
import flatten from "lodash/flatten";
flatten(["a", ["b", "c"], "d"]);
// ["a", "b", "c", "d"]📋 _.flatten vs native flat(1) vs deeper helpers
| API | Depth | Note |
|---|---|---|
_.flatten(array) | One level | Lodash module import; consistent on array-like inputs |
array.flat(1) | One level | Native ES2019; same idea for real arrays |
_.flattenDeep / _.flattenDepth | All / configurable | Use when nesting depth is unknown or greater than one |
Pitfalls to avoid
Assuming full recursion
User-generated trees often need flattenDeep or an explicit loop; a single flatten leaves surprises one level down.
Not a deep clone
Flatten copies references. Nested objects inside arrays are not duplicated; mutating them still affects every alias.
Holes and undefined slots
Behavior follows Lodash collection rules; when in doubt, log the output for sparse arrays before shipping.
❓ FAQ
Summary
- Purpose:
_.flatten(array)returns a new array with one level of nested arrays removed. - Safety: the input array is not mutated.
- Next: Lodash _.flattenDeep(), _.findLastIndex() (earlier in this track), or the array methods hub.
_.flatten is intentionally shallow: nested arrays deeper than one level remain nested unless you switch to _.flattenDeep or _.flattenDepth.
About the author
6 people found this page helpful