JavaScript Array flat() Method

What You’ll Learn

The flat() method flattens nested arrays into a new, simpler array. Default depth is 1; pass a number or Infinity for deeper flattening. This tutorial covers syntax, five examples, depth behavior, and how flat() differs from flatMap() and spread.

Introduction

Nested arrays appear everywhere—API payloads, grid coordinates, results from map() that return arrays. The flat() method collapses those layers into a single list without manual loops.

It returns a new array and leaves the original untouched. Control how aggressive the flattening is with the optional depth argument.

Understanding the flat() Method

array.flat(depth) walks the structure and merges nested array elements into the output. Non-array values (numbers, strings, objects) are copied through unchanged.

Think of depth as how many nesting levels to unpack. flat(1) is the default; flat(2) unwraps two levels; flat(Infinity) keeps going until nothing is nested.

📝 Syntax

General form of Array.prototype.flat:

array.flat(depth)

Parameters

• depth — optional; how many levels to flatten (default 1). Use Infinity for all levels.

Return value

• A new flattened array.
• Original array unchanged.
• Empty slots in sparse arrays become undefined in the result.

Common patterns

• nested.flat() — one level (default).
• nested.flat(2) — two levels.
• nested.flat(Infinity) — fully flat.
• arr.map(fn).flat() — classic pre–flatMap pattern.

Examples Gallery

Open DevTools Console (F12) or use Try-it labs. Example N maps to ?tryit=N.

const nested = [1, [2, [3, 4, [5]]]];

const flattened = nested.flat();

console.log(flattened);
// [1, 2, [3, 4, [5]]]

[1, 2, [3, 4, [5]]]

const nested = [1, [2, [3, 4, [5]]]];

const flattened = nested.flat(2);

console.log(flattened);
// [1, 2, 3, 4, [5]]

[1, 2, 3, 4, [5]]

const irregular = [1, [2, [3, [4, [5]]]]];

const simplified = irregular.flat(Infinity);

console.log(simplified);
// [1, 2, 3, 4, 5]

[1, 2, 3, 4, 5]

const sentences = ["hello world", "flat arrays"];

const words = sentences
  .map((s) => s.split(" "))
  .flat();

console.log(words);
// ["hello", "world", "flat", "arrays"]

["hello", "world", "flat", "arrays"]

const mixed = [1, { tags: ["a", "b"] }, [2, 3]];

const result = mixed.flat(Infinity);

console.log(result);
// [1, { tags: ["a", "b"] }, 2, 3]

[1, { tags: ["a", "b"] }, 2, 3]

🚀 Common Use Cases

• API normalization — collapse nested list responses.
• Grid / matrix data — turn 2D arrays into 1D for processing.
• Tokenizing text — after map(split), flatten words.
• Tree leaves — collect leaf nodes stored as nested arrays.
• Test fixtures — simplify deeply nested sample data.
• Pipeline cleanup — one-level flatten after operations that return arrays.

📝 Notes

• Default depth is 1, not full flatten.
• flat(Infinity) is the idiomatic full-flatten shortcut.
• Non-integer depth is truncated toward zero (invalid values behave like 0).
• Only arrays flatten—not array-like objects unless they are true arrays.
• Sparse arrays: holes may become undefined entries in the result.
• ES2019—use polyfill or recursive helper for IE11.

💡 Best Practices