Lodash _.flattenDepth() method

Beginner
⏱️ 7 min read
📚 Updated: May 2026
🎯 3 Code examples
🚀 3 Try-it labs
Lodash

What you’ll learn

  • How _.flattenDepth(array, depth) unwraps exactly depth levels of array nesting.
  • Why that sits between _.flatten() (one level) and _.flattenDeep() (all levels).
  • How it lines up with Array.prototype.flat(depth) on real arrays.
  • Try each example in the editor (?tryit=1, 2, 3) with Lodash from a CDN.

Prerequisites

Read _.flatten() and _.flattenDeep() on this site so the three APIs form one mental model.

  • You can read depth as “how many times to peel array wrappers from the current structure.”
  • You can run snippets in Node or open the Try-it labs in a browser.

Overview

_.flattenDepth is the controlled middle ground: you pass an integer depth so Lodash stops before the structure is fully linear. That is ideal when you know your payloads are “at most two levels of arrays” or when you want to preserve one intentional inner list.

Bounded work

Unlike full recursion, worst-case work scales with depth you choose, not unknown tree height.

Default depth 1

Omitting depth behaves like a single _.flatten pass for ordinary nested arrays.

New array

The source array is not mutated; you always receive a new result reference.

Syntax

javascript
_.flattenDepth(array, [depth=1])
  • array: collection that may contain nested arrays (array-like values are coerced).
  • depth: how many levels of nested arrays to flatten (non-negative integer; defaults to 1).
  • Returns: a new array with nesting reduced by up to depth levels.
1

Two levels of unwrapping

With depth: 2, two layers of brackets disappear; a third layer can remain.

javascript
import flattenDepth from "lodash/flattenDepth";

flattenDepth([1, [2, [3, [4]]]], 2);
// [1, 2, 3, [4]]
Try it Yourself
2

Default depth equals one

Omitting the second argument matches a single shallow flatten pass.

javascript
import flattenDepth from "lodash/flattenDepth";

flattenDepth([[1, 2], [3, [4, 5]]]);
// [1, 2, 3, [4, 5]]
Try it Yourself
3

Same idea as native flat

For a plain array instance, flat(2) and flattenDepth(arr, 2) express the same depth budget.

javascript
import flattenDepth from "lodash/flattenDepth";

const nested = [0, [1, [2, [3]]]];

flattenDepth(nested, 2);
// [0, 1, 2, [3]]

nested.flat(2);
// [0, 1, 2, [3]]
Try it Yourself

📋 _.flattenDepth vs _.flatten vs _.flattenDeep

APILevels removedWhen to pick it
_.flatten(array)Always 1Known single wrapper around batches
_.flattenDepth(array, n)Up to nBounded depth or preserving one inner list on purpose
_.flattenDeep(array)AllUnknown or variable nesting; must end with no arrays

Pitfalls to avoid

Depth

Off-by-one nesting

If your API adds one more wrapper in a new version, a fixed depth may stop early. Add tests around real payloads.

Type

Only real arrays unwrap

Array-like objects and plain objects are not recursively opened the way you might expect from custom trees.

Copy

Still not a deep clone

Leaf objects and arrays that survive flattening share references with the source.

❓ FAQ

No. Lodash returns a new array with the requested amount of flattening applied.
When depth is omitted, Lodash defaults to 1, which unwraps a single level of nested arrays (same idea as _.flatten).
flattenDeep keeps unwrapping until no arrays remain. flattenDepth stops after exactly depth levels, which may still leave nested arrays in the result.
A depth of 0 returns a shallow copy of the array without removing any nesting (useful when you want the same API but no flattening).
Use import flattenDepth from "lodash/flattenDepth" or require("lodash/flattenDepth") for tree-shaking friendly bundles.

Summary

Did you know?

With depth set to 1, _.flattenDepth matches _.flatten for typical arrays: both unwrap a single bracket layer.

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

6 people found this page helpful

Lodash _.flattenDeep() Lodash _.fromPairs()