How to Use flat and flatMap in JavaScript: Syntax and Examples

In JavaScript, flat() is used to flatten nested arrays into a single-level array, while flatMap() combines mapping and flattening by applying a function to each element and then flattening the result by one level. Use flat() when you want to reduce nesting, and flatMap() when you want to transform and flatten in one step.

Syntax

flat() syntax: array.flat(depth)
flatMap() syntax: array.flatMap(callback)

• depth (optional) is how deep to flatten nested arrays; default is 1.
• callback is a function applied to each element before flattening.

javascript

const arr = [1, [2, [3, 4]]];

// flat with depth 1
const flatOnce = arr.flat();

// flat with depth 2
const flatTwice = arr.flat(2);

// flatMap example
const flatMapped = [1, 2, 3].flatMap(x => [x, x * 2]);

Output

[1, 2, [3, 4]]
[1, 2, 3, 4]
[1, 2, 2, 4, 3, 6]

Example

This example shows how flat() flattens nested arrays and how flatMap() maps each element to an array and flattens the result by one level.

javascript

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

// Flatten one level
const flatOnce = nested.flat();
console.log(flatOnce);

// Flatten two levels
const flatTwice = nested.flat(2);
console.log(flatTwice);

// flatMap doubles each number and flattens
const flatMapped = [1, 2, 3].flatMap(x => [x, x * 2]);
console.log(flatMapped);

Output

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

Common Pitfalls

One common mistake is expecting flat() to flatten all nested levels by default; it only flattens one level unless you specify a deeper depth. Another is confusing flatMap() with map() followed by flat() with a depth greater than 1, which flatMap() does not do—it only flattens one level.

Also, flatMap() only accepts a function that returns an array or a value; returning nested arrays will not flatten beyond one level.

javascript

const arr = [1, [2, [3]]];

// Wrong: flat() default depth is 1, so nested deeper arrays stay nested
console.log(arr.flat()); // Output: [1, 2, [3]]

// Right: specify depth to flatten deeper
console.log(arr.flat(2)); // Output: [1, 2, 3]

// Wrong: flatMap does not flatten deeply nested arrays
const result = [1, 2].flatMap(x => [[x, x * 2]]);
console.log(result); // Output: [[1, 2], [2, 4]] (not fully flattened)

Output

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

Quick Reference

Method	Purpose	Default Flatten Depth	Input	Output
flat()	Flattens nested arrays	1	Array with nested arrays	New array flattened by depth
flatMap()	Maps and flattens by one level	1 (fixed)	Array and mapping function	Mapped and flattened array

Key Takeaways

flat() flattens nested arrays by a specified depth, defaulting to one level.

flatMap() applies a function to each element and flattens the result by one level.

Use flat() to reduce nesting; use flatMap() to transform and flatten in one step.

flatMap() only flattens one level, so deeply nested arrays need extra handling.

Specify the depth in flat() to control how deeply arrays are flattened.