Array.prototype.flat()

flat(depth)

The flat() method creates a new array with all sub-array elements concatenated into it recursively up to the specified depth. It’s the cleanest way to flatten nested arrays without writing recursive logic yourself.

Syntax

array.flat(depth)

• depth: The depth level specifying how deep a nested array should be flattened. Defaults to 1. Use Infinity to flatten all nested arrays.
• Returns: A new flattened array.

TypeScript Signature

interface Array<T> {
  flat<U>(this: U[Global_Objects::eval][Global_Objects::eval], depth: 1): U[Global_Objects::eval];
  flat<U>(this: U[Global_Objects::eval][Global_Objects::eval], depth: 0): U[Global_Objects::eval][Global_Objects::eval];
  flat<U>(this: any[Global_Objects::eval], depth: number): U[Global_Objects::eval];
}

Parameters

Parameter	Type	Default	Description
depth	number	1	The nesting depth level to flatten. Infinity flattens all levels.

Examples

Basic Flattening

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

// Default depth of 1
console.log(nested.flat());
// [1, 2, 3, 4, [5, 6]]

// Flatten one level deep
console.log(nested.flat(1));
// [1, 2, 3, 4, [5, 6]]

Flattening to Different Depths

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

// Depth 0 - no flattening
console.log(deep.flat(0));
// [1, [2, [3, [4, [5]]]]]

// Depth 1
console.log(deep.flat(1));
// [1, 2, [3, [4, [5]]]]

// Depth 2
console.log(deep.flat(2));
// [1, 2, 3, [4, [5]]]

// Infinity - fully flatten
console.log(deep.flat(Infinity));
// [1, 2, 3, 4, 5]

Removing Empty Slots

const sparse = [1, 2, , 4, 5];

// flat() automatically removes empty slots
console.log(sparse.flat());
// [1, 2, 4, 5]

Combining with Other Array Methods

const data = [[1, 2], [3, 4], [5, 6]];

// Flatten after mapping
const result = data.map(pair => pair.map(x => x * 2)).flat();
console.log(result);
// [2, 4, 6, 8, 10, 12]

// This is equivalent to flatMap()
console.log(data.flatMap(pair => pair.map(x => x * 2)));
// [2, 4, 6, 8, 10, 12]

Practical Example: Processing API Responses

const apiResponse = {
  users: [
    { name: "Alice", scores: [95, 87] },
    { name: "Bob", scores: [92, 88, 91] },
    { name: "Carol", scores: [78] }
  ]
};

// Get all scores in a flat array
const allScores = apiResponse.users.map(u => u.scores).flat();
console.log(allScores);
// [95, 87, 92, 88, 91, 78]

// Calculate average
const avg = allScores.reduce((a, b) => a + b, 0) / allScores.length;
console.log(avg.toFixed(2));
// "88.50"

Common Patterns

Flatten Object Values

const groups = {
  a: [1, 2],
  b: [3, 4],
  c: [5, 6]
};

const values = Object.values(groups).flat();
console.log(values);
// [1, 2, 3, 4, 5, 6]

Flatten While Filtering

const matrix = [[1, 2, 0], [3, 0, 4], [5, 6, 0]];

// Flatten and filter in one chain
const nonZero = matrix.flat().filter(x => x !== 0);
console.log(nonZero);
// [1, 2, 3, 4, 5, 6]

Edge Cases

// Empty arrays are preserved
console.log([1, [Global_Objects::eval], 2].flat());
// [1, 2]

// Holes are removed
console.log([1, 2, , 3, , 4].flat());
// [1, 2, 3, 4]

// Non-array elements are passed through
console.log([1, "two", 3].flat());
// [1, "two", 3]

Performance Note

For very deep arrays, flat(Infinity) can be slow. Consider using a custom recursive function if you need more control or better performance with massive arrays.

See Also

• array::flatMap — map and flatten in one step
• array::concat — concatenate arrays