JavaScript Reference
Array.prototype.flatMap()
Map each element, then flatten the result one level. Faster than map().flat().
Last updated: October 2026
Definition: Array.prototype.flatMap() first maps each element using a provided function, then flattens the result by one level into a new array. It is equivalent to map().flat(1) but more efficient [citation:5].
🎬 Live Example
Five flatMap patterns. Click any button to see the output.
💡 flatMap only flattens one level. Use map().flat(depth) for deeper flattening.
Basic Syntax
array.flatMap(callback(element, index, array))
// callback — function that returns a value or array
// Returns a new array
// Flattens the result by ONE level only🎯 Syntax & Parameters
| Parameter | Type | Description |
|---|---|---|
callback | Function | Runs on each element. Should return a value or array. |
element | any | Current element being processed. |
index | number | Index of current element. |
array | Array | The original array. |
Map and Flatten in One Step
const result = [1, 2, 3].flatMap(n => [n, n * 2]);
// [1, 2, 2, 4, 3, 6]
// Equivalent to:
[1, 2, 3].map(n => [n, n * 2]).flat();
// But flatMap is more efficientDuplicate or Expand Elements
['a', 'b'].flatMap(s => [s, s]);
// ['a', 'a', 'b', 'b']
// Word expansion
['hi'].flatMap(w => w.split(''));
// ['h', 'i']Filter and Map Together
// Return [] to skip, [value] to keep
const evens = [1, 2, 3, 4].flatMap(n =>
n % 2 === 0 ? [n] : []
);
// [2, 4]
// This is like filter() + map() combinedPro tip: Returning an empty array is the flatMap idiom for filtering during a map operation.
Only Flattens One Level
// This:
[[1, 2], [3, 4]].flatMap(a => a);
// [1, 2, 3, 4]
// But this:
[[1, [2]], [3, [4]]].flatMap(a => a);
// [1, [2], 3, [4]] ← inner stays nested
// For deeper, use map().flat(depth):
[[1, [2]], [3, [4]]].map(a => a).flat(2);
// [1, 2, 3, 4]Note: flatMap only flattens depth 1. It cannot accept a depth argument.
Real-World: Extract Tags from Posts
const posts = [
{ title: 'Post 1', tags: ['js', 'web'] },
{ title: 'Post 2', tags: ['css'] },
{ title: 'Post 3', tags: ['js', 'node'] }
];
// Get all tags as a flat array
const allTags = posts.flatMap(p => p.tags);
// ['js', 'web', 'css', 'js', 'node']
// Unique tags
const uniqueTags = [...new Set(allTags)];
// ['js', 'web', 'css', 'node']🎯 flatMap vs map vs flat vs map().flat()
| Method | Maps? | Flatten depth |
|---|---|---|
flatMap | Yes | 1 (fixed) |
map | Yes | None |
flat | No | Configurable |
map().flat() | Yes | Configurable |
⚠️ Common Mistakes
- Expecting deep flattening. flatMap only flattens depth 1.
- Returning non-arrays. flatMap works with any value — primitives are kept, arrays are flattened.
- Confusing flatMap with filter. To filter, return [] for excluded items.
- Using flatMap when map is enough. If you don't need flattening, map is simpler.
- Forgetting flatMap is not available in older browsers. ES2019 — check for polyfills if needed.
❓ Frequently Asked Questions
What does Array.flatMap() do in JavaScript?
Array.flatMap() first maps each element using a provided function, then flattens the result by one level into a new array. It is equivalent to map() followed by flat(1), but more efficient.
What is the difference between flatMap and map?
map returns an array where each element is the direct result of the callback. flatMap also maps, but then flattens the result by one level. Use flatMap when your callback returns arrays that should be merged.
What is the difference between flatMap and flat?
flat only flattens existing nested arrays. flatMap maps first (transforms each element) then flattens by depth 1. flatMap cannot flatten deeper than one level.
Can flatMap remove elements?
Yes. If the callback returns an empty array [], that element contributes nothing to the result. This is a common pattern for filtering while mapping.
Is flatMap faster than map().flat()?
Yes. flatMap is typically more efficient because it avoids creating an intermediate array. For large datasets, the performance difference is meaningful.