You’re reading the English version of this content since no translation exists yet for this locale. Help us translate this article!

The flatMap() method first maps each element using a mapping function, then flattens the result into a new array. It is identical to a map() followed by a flat() of depth 1, but flatMap() is often quite useful, as merging both into one method is slightly more efficient.


var new_array = arr.flatMap(function callback(currentValue[, index[, array]]) {
    // return element for new_array
}[, thisArg])


Function that produces an element of the new Array, taking three arguments:
The current element being processed in the array.
The index of the current element being processed in the array.
The array map was called upon.
Value to use as this when executing callback.

Return value

A new array with each element being the result of the callback function and flattened to a depth of 1.


See for a detailed description of the callback function. The flatMap method is identical to a map followed by a call to flat of depth 1.


map() and flatMap()

let arr1 = [1, 2, 3, 4]; => [x * 2]); 
// [[2], [4], [6], [8]]

arr1.flatMap(x => [x * 2]);
// [2, 4, 6, 8]

// only one level is flattened
arr1.flatMap(x => [[x * 2]]);
// [[2], [4], [6], [8]]

While the above could have been achieved by using map itself, here is an example that better showcases the use of flatMap.

Let's generate a list of words from a list of sentences.

let arr1 = ["it's Sunny in", "", "California"]; => x.split(" "));
// [["it's","Sunny","in"],[""],["California"]]

arr1.flatMap(x => x.split(" "));
// ["it's","Sunny","in", "", "California"]

Notice, the output list length can be different from the input list length.

For adding and removing items during a map()

flatMap can be used as a way to add and remove items (modify the number of items) during a map. In other words, it allows you to map many items to many items (by handling each input item separately), rather than always one-to-one. In this sense, it works like the opposite of filter. Simply return a 1-element array to keep the item, a multiple-element array to add items, or a 0-element array to remove the item.

// Let's say we want to remove all the negative numbers and split the odd numbers into an even number and a 1
let a = [5, 4, -3, 20, 17, -33, -4, 18]
//       |\  \  x   |  | \   x   x   |
//      [4,1, 4,   20, 16, 1,       18]

a.flatMap( (n) =>
  (n < 0) ?      [] :
  (n % 2 == 0) ? [n] :
                 [n-1, 1]

// expected output: [4, 1, 4, 20, 16, 1, 18]


reduce() and concat()

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

arr.flatMap(x => [x, x * 2]);
// is equivalent to
arr.reduce((acc, x) => acc.concat([x, x * 2]), []);
// [1, 2, 2, 4, 3, 6, 4, 8]

Note, however, that this is inefficient and should be avoided for large arrays: in each iteration, it creates a new temporary array that must be garbage-collected, and it copies elements from the current accumulator array into a new array instead of just adding the new elements to the existing array.


Specification Status Comment
ECMAScript 2019 Finished Initial definition

Browser compatibility

Update compatibility data on GitHub
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
flatMapChrome Full support 69Edge No support NoFirefox Full support 62IE No support NoOpera Full support 56Safari Full support 12WebView Android Full support 69Chrome Android Full support 69Firefox Android Full support 62Opera Android Full support 48Safari iOS Full support 12Samsung Internet Android No support Nonodejs Full support 11.0.0


Full support  
Full support
No support  
No support

See also