Array.flat()
Flattens nested arrays by a given depth and returns a new array.
array.flat(depth?)This static page keeps the syntax and examples indexed for search, while the coding app handles interactive exploration and saved references.
What it does
Overview
Flattens nested arrays by a given depth and returns a new array.
The Array.prototype.flat() method creates a new array with all sub-array elements concatenated into it recursively up to a specified depth. It defaults to a depth of 1 if no argument is provided. This method is non-mutating, ensuring the original array remains unchanged. Performance-wise, flat() has a time complexity of O(n), where n is the total number of elements across all nesting levels. A significant edge case is its behavior with sparse arrays: flat() automatically removes empty slots (holes), which can be used to compress arrays. While using Infinity as a depth argument allows for complete flattening of any nested structure, developers should be cautious with massive datasets as the creation of a large new array can lead to significant memory consumption. This feature was introduced in ES2019; as such, Internet Explorer is not supported.
Quick reference
Syntax
array.flat(depth?)Inputs
Parameters
See it in practice
Examples
Basic Single-Level Flattening
const nested = [1, 2, [3, 4], 5];
const flattened = nested.flat();[1, 2, 3, 4, 5]
By default, flat() moves elements from one level of nesting into the top-level array.
Deep Flattening with Infinity
const deeplyNested = [1, [2, [3, [4, 5]]]];
const fullyFlattened = deeplyNested.flat(Infinity);[1, 2, 3, 4, 5]
Using the Infinity keyword ensures that all nesting levels are processed, regardless of depth.
Removing Sparse Array Holes
const sparseArray = [1, 2, , 4, 5];
const cleaned = sparseArray.flat();[1, 2, 4, 5]
The flat() method automatically removes empty slots (holes) in the array during the process.
Debug faster
Common Errors
LogicError
Cause: Assuming flat() removes all levels of nesting by default.
Fix: Specify the depth as an integer or use Infinity for unknown nesting levels.
const arr = [1, [2, [3]]];
arr.flat(); // Returns [1, 2, [3]], not [1, 2, 3]LogicError
Cause: Expecting the flat() method to modify the original array in place.
Fix: Assign the result to a new variable or reassign the existing one, as flat() returns a new reference.
const arr = [1, [2]];
arr.flat();
console.log(arr); // Still [1, [2]]Runtime support
Compatibility
Source: MDN Web Docs
Common questions
Frequently Asked Questions
Flattens nested arrays by a given depth and returns a new array.
depth: How deep to flatten. Default is 1.
LogicError: Specify the depth as an integer or use Infinity for unknown nesting levels. LogicError: Assign the result to a new variable or reassign the existing one, as flat() returns a new reference.