JavaScript Array flatMap Method: Complete Guide

flatMap() does two things at once: it runs a mapping function on every element, then flattens the result by one level. It was added in ES2019 and is the cleaner, more efficient way to combine map() and flat().

javascript

const phrases = ["hello world", "goodbye moon"];
 
const words = phrases.flatMap(phrase => phrase.split(" "));
 
console.log(words); // ["hello", "world", "goodbye", "moon"]

Without flatMap(), you would need to chain map() and flat() separately to get the same flattened result, running two full passes over the array instead of one:

javascript

const wordsOld = phrases.map(phrase => phrase.split(" ")).flat();
// Same result: ["hello", "world", "goodbye", "moon"]

flatMap() does the same thing but reads more naturally and runs slightly faster because it is a single pass.

Syntax and Parameters

flatMap() takes a single callback function and calls it once for every element in the array:

javascript

array.flatMap(callback)

The callback receives the same arguments as map(), giving you access to the element, its position, and the full array if needed:

The callback must return an array. If it returns anything else, flatMap() throws a TypeError.

Removing Elements by Returning an Empty Array

A unique power of flatMap() is filtering elements by returning [] for the ones you want to remove:

javascript

const numbers = [1, 2, 3, 4, 5, 6];
 
// Double evens, remove odds -- all in one pass
const doubledEvens = numbers.flatMap(n =>
  n % 2 === 0 ? [n * 2] : []
);
 
console.log(doubledEvens); // [4, 8, 12]

This is cleaner than the two-pass alternative of mapping first and filtering afterward, which needs a second full iteration over the array:

javascript

// Two passes with map + filter
const doubledEvensOld = numbers
  .filter(n => n % 2 === 0)
  .map(n => n * 2);

With flatMap(), you decide per element whether to include it and what value to produce, all in one callback.

Adding Multiple Elements Per Input

flatMap() shines when one input element should produce multiple output elements:

javascript

const users = [
  { name: "Alice", hobbies: ["reading", "hiking"] },
  { name: "Bob", hobbies: ["gaming", "cooking", "cycling"] }
];
 
const allHobbies = users.flatMap(user => user.hobbies);
 
console.log(allHobbies);
// ["reading", "hiking", "gaming", "cooking", "cycling"]

Replace each user object with their array of hobbies, then flatten. The result is a single list of every hobby across all users.

Duplicating Elements

You can use flatMap() to repeat elements a certain number of times:

javascript

const items = ["a", "b"];
 
const duplicated = items.flatMap(item => [item, item, item]);
 
console.log(duplicated); // ["a", "a", "a", "b", "b", "b"]

flatMap() also works well for generating ranges, where the mapping function returns a differently sized array depending on the input value:

javascript

const nums = [1, 2, 3];
 
// Each number repeats itself that many times: [1], [2, 2], [3, 3, 3]
const expanded = nums.flatMap(n => Array(n).fill(n));
 
console.log(expanded); // [1, 2, 2, 3, 3, 3]

Splitting and Normalizing Text

A common data processing task is splitting comma-separated strings and trimming whitespace. flatMap() handles this in a single clean step:

javascript

const entries = ["apple, banana", "cherry , date", "elderberry, fig"];
 
const allFruits = entries.flatMap(entry =>
  entry.split(",").map(s => s.trim())
);
 
console.log(allFruits);
// ["apple", "banana", "cherry", "date", "elderberry", "fig"]

Each string is split into an array, each piece is trimmed, and flatMap() flattens the intermediate arrays into one clean list of fruit names. Without flatMap(), you would need map() followed by flat() -- two passes instead of one.

flatMap() vs map() + flat()

Use flatMap() when you need exactly one level of flattening. Use map() + flat(n) when you need deeper flattening.

Common Mistakes

Returning a non-array value. Since flatMap() expects to flatten the callback's return value, giving it a plain number or string instead of an array throws an error:

javascript

const nums = [1, 2, 3];
 
const result = nums.flatMap(n => n * 2);
// TypeError: flatMap callback must return an array

The callback must always return an array, even for a single value. Wrapping the value in brackets fixes it and lets flatMap() flatten it back down normally:

javascript

// Right: wrap the value in an array
const result = nums.flatMap(n => [n * 2]);
console.log(result); // [2, 4, 6]

Expecting deep flattening. Since flatMap() only removes one level of nesting, arrays nested more than one level deep still need an extra step:

javascript

const nested = [[[1, 2]], [[3, 4]]];
 
// flatMap only flattens one level
const result = nested.flatMap(arr => arr);
console.log(result); // [[1, 2], [3, 4]] (still nested arrays!)
 
// For deeper flattening, use flat() with a depth argument
const deep = nested.flatMap(arr => arr).flat();
console.log(deep); // [1, 2, 3, 4]

flatMap() is flat(1), not flat(Infinity). If you need more depth, chain .flat(n) after flatMap().

Now that you understand flatMap(), learn how to select specific elements with filter or combine and transform values with reduce.