JavaScript Array flatMap() Method

What You’ll Learn

The flatMap() method maps each element with a callback, then flattens the result by one level. It is the modern replacement for map().flat(). This tutorial covers syntax, five examples, the filter-with-empty-array trick, and how flatMap() compares to map() and flat().

Introduction

Sometimes map() returns an array for each element—splitting words, duplicating values, or expanding records. You then need to flatten those nested arrays. flatMap() does both in one readable call.

Think of it as map(callback).flat(1). The callback can return a single value or an array; arrays are merged one level into the final result.

Understanding the flatMap() Method

For each element, flatMap runs your callback. If the callback returns [a, b], those items are appended to the output. If it returns a non-array value, that value is appended as one item.

Unlike flat(), you cannot choose depth—flattening is always exactly one level. Deeper nesting in the callback result stays nested unless you flatten again manually.

📝 Syntax

General form of Array.prototype.flatMap:

array.flatMap(callback(element, index, array), thisArg)

Parameters

• callback — called for each element; return a value or array to include in the result.
• thisArg — optional this value inside the callback.

Return value

• A new array with mapped values flattened one level.
• Original array unchanged.
• Sparse holes are skipped (unlike map().flat() in some cases).

Common patterns

• arr.flatMap((x) => [x * 2]) — map to single-item arrays.
• arr.flatMap((s) => s.split(" ")) — split and flatten words.
• arr.flatMap((n) => (n % 2 === 0 ? [n] : [])) — filter evens.
• arr.flatMap((x) => x.tags) — extract nested arrays from objects.

Examples Gallery

Open DevTools Console (F12) or use Try-it labs. Example N maps to ?tryit=N.

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

const doubled = numbers.flatMap((num) => [num * 2]);

console.log(doubled);
// [2, 4, 6, 8]

[2, 4, 6, 8]

const words = ["Hello", "World"];

const chars = words.flatMap((word) => word.split(""));

console.log(chars);
// ["H", "e", "l", "l", "o", "W", "o", "r", "l", "d"]

["H", "e", "l", "l", "o", "W", "o", "r", "l", "d"]

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

const evens = numbers.flatMap((num) =>
  num % 2 === 0 ? [num] : []
);

console.log(evens);
// [2, 4, 6]

[2, 4, 6]

const ids = [10, 20];

const withMap = ids.map((id) => [id, id + 1]);
const withFlatMap = ids.flatMap((id) => [id, id + 1]);

console.log("map:", withMap);
// [[10, 11], [20, 21]]

console.log("flatMap:", withFlatMap);
// [10, 11, 20, 21]

map: [[10, 11], [20, 21]]
flatMap: [10, 11, 20, 21]

const posts = [
  { title: "Intro", tags: ["js", "tutorial"] },
  { title: "Arrays", tags: ["flatMap", "map"] }
];

const allTags = posts.flatMap((post) => post.tags);

console.log(allTags);
// ["js", "tutorial", "flatMap", "map"]

["js", "tutorial", "flatMap", "map"]

🚀 Common Use Cases

• Tokenizing text — split sentences or words into flat character or word lists.
• Filter + map — one pass with [] / [value] returns.
• Collecting nested fields — gather tags, IDs, or child items from records.
• Expanding ranges — each input produces multiple output values.
• Removing optional items — return empty array when data is missing.
• Replacing map().flat() — cleaner pipelines in modern code.

📝 Notes

• Always flattens exactly one level—no depth parameter.
• Callback may return a non-array; it becomes one output element.
• Return [] to omit an element (filter pattern).
• Sparse arrays: holes are skipped, unlike some map().flat() cases.
• Not a replacement for flat(Infinity) on deeply nested existing arrays.
• ES2019—polyfill or use map().flat() for IE11.

💡 Best Practices