Underscore.js _.flatten() Method

Beginner
5 min read
Updated: Nov 2026
4 examples
Array

Definition

Flattens a nested array. Pass true or 1 for one level; a larger number for deeper; omit depth (or pass false / Infinity) to flatten all the way (official Underscore docs).

Pass the required arguments shown below. Underscore array helpers usually return a new value — check whether the source array is mutated.

Syntax

Call _.flatten. Start with this line.

Underscore
_.flatten(array, [depth])
CallWhat it does
_.flatten(array, [depth])Primary signature.
_.flatten(...)Call with the arguments your case needs.

Load Underscore with import _ from "underscore" (or the UMD CDN build) so these helpers are available as _.

Library declarations
Underscore
_.flatten(array, [depth])

Parameters

ParameterDescription
arrayRequired. Nested list to unwrap
depthOptional. true/1 = one level; number = levels; omit/false/Infinity = deep

Return Value

Return ValueDescription
*New array (never mutates source)

Underscore.js Examples

Example 1 — Official: Deep Flatten

Omit depth to pull values out of every nesting level.

Underscore
_.flatten([1, [2], [3, [[4]]]]);
// → [1, 2, 3, 4]
Try It Yourself

How It Works

  1. Nested source. Values sit inside arrays of arrays.
  2. No depth. Underscore keeps unwrapping until nothing nested remains.
  3. Result. A single flat list: [1, 2, 3, 4].
  4. Copy. The original nesting is still intact on the input.

Example 2 — Official: Shallow with true

Pass true (or 1) to flatten only one level.

Underscore
_.flatten([1, [2], [3, [[4]]]], true);
// → [1, 2, 3, [[4]]]
Try It Yourself

How It Works

  1. One unwrap. Top-level arrays are opened once.
  2. [2] and [3, [[4]]]. Become 2 and 3 plus [[4]].
  3. Stop. [[4]] is still nested — depth ran out.
  4. Same as 1. _.flatten(arr, 1) matches this result.

Example 3 — Official: Depth 2

A numeric depth descends a fixed number of levels.

Underscore
_.flatten([1, [2], [3, [[4]]]], 2);
// → [1, 2, 3, [4]]
Try It Yourself

How It Works

  1. Level 1. Open outer nests → reach [[4]].
  2. Level 2. Open [[4]] → leave [4].
  3. Stop. No third unwrap, so 4 stays inside one array.
  4. Control. Use numbers when you want “almost flat,” not fully flat.

Example 4 — Merge Several Arrays

Wrap lists in one outer array, then flatten to concatenate them.

Underscore
var a = [1, 2];
var b = [3, 4];
var c = [5, 6];

_.flatten([a, b, c]);
// → [1, 2, 3, 4, 5, 6]
Try It Yourself

How It Works

  1. Outer list. [a, b, c] is one level of nesting.
  2. Deep flatten. Each inner array is unwrapped into the result.
  3. Order. Items stay in left-to-right order.
  4. Uniqueness? Duplicates are kept — use _.union if you need unique values.

Browser & Runtime Support

_.flatten ships with Underscore.js (1.x), including numeric depth. It runs anywhere Underscore runs — modern browsers (CDN or bundle) and Node.js / Bun / Deno with npm install underscore. Native Array.prototype.flat is separate (ES2019).

✓ Stable · Underscore 1.x

_.flatten()

Available in [email protected] (UMD / ESM). Works in evergreen browsers and current Node LTS when Underscore is loaded.

100% With Underscore 1.x
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Bun Supported · JavaScript runtime
Supported
Deno Supported · JavaScript runtime
Supported
Node.js Supported · Server runtime
Supported
Android WebView Supported · Modern WebView
Full support
_.flatten Underscore 1.x+

Bottom line: Safe for production once Underscore is on the page or in your bundle. Not a native browser API — load Underscore first. Prefer a pinned CDN version (e.g. [email protected]).

Frequently Asked Questions

_.flatten(array, [depth]) flattens a nested array into a new array. By default it goes all the way to the deepest nesting level.
Pass true or 1 as the depth: _.flatten(arr, true) or _.flatten(arr, 1). Deeper nests stay as arrays.
Yes. Pass a number (for example 2) to descend that many levels. Omit depth, or pass false or Infinity, for a full deep flatten.
No. It returns a new array. The source nesting is left unchanged. Object elements are still shared by reference.
_.flatten only unwraps nested arrays. _.union merges arrays and also keeps unique values in first-seen order.
Array.prototype.flat is ES2019 and uses a similar depth idea (default 1). Underscore defaults to deep flatten, and true means one level — opposite default depth from native flat().

Next: _.without()

Return a copy of the array with specific values removed.

_.without() tutorial →

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.

11 people found this page helpful