Array.flatMap()
Maps and flattens one level in a single pass (returns new array).
array.flatMap(callbackFn, thisArg?)This static page keeps the syntax and examples indexed for search, while the coding app handles interactive exploration and saved references.
What it does
Overview
Maps and flattens one level in a single pass (returns new array).
Array.prototype.flatMap() creates a new array by applying a provided callback function to each element and then flattening the resulting array by exactly one level. It is functionally equivalent to calling map() followed by flat(1), but it is more efficient as it performs both operations in a single pass, avoiding the creation of an intermediate array. This method is particularly powerful for handling one-to-many relationships or acting as a combined filter-and-map operation; by returning an empty array [] for specific elements, they are effectively removed from the final result. Note that flatMap() only flattens to a depth of 1; deeper nested arrays returned by the callback will remain nested. Performance-wise, it is optimized in modern engines but is not supported in Internet Explorer (IE).
Quick reference
Syntax
array.flatMap(callbackFn, thisArg?)Inputs
Parameters
See it in practice
Examples
Splitting Strings into Individual Words
const sentences = ['JavaScript is versatile', 'flatMap is efficient'];
const words = sentences.flatMap(s => s.split(' '));['JavaScript', 'is', 'versatile', 'flatMap', 'is', 'efficient']
Splits each sentence into an array of words and flattens them into a single-level array.
Combined Filtering and Mapping
const numbers = [10, -5, 20, -15, 30];
const doubledPositives = numbers.flatMap(n => n > 0 ? [n * 2] : []);[20, 40, 60]
Uses an empty array return to filter out negatives while doubling positive values in one pass.
Expanding Data Sets (One-to-Many)
const categories = ['tech', 'art'];
const tags = categories.flatMap(cat => [cat, cat + '-new', cat + '-legacy']);['tech', 'tech-new', 'tech-legacy', 'art', 'art-new', 'art-legacy']
Generates multiple related items for every single input element and flattens the result.
Debug faster
Common Errors
LogicError
Cause: Expecting flatMap to flatten nested arrays deeper than one level.
Fix: Use map() combined with flat(depth) if you need to flatten multiple levels of nesting.
const arr = [1, 2];
arr.flatMap(x => [[x]]); // Returns [[1], [2]] instead of [1, 2]LogicError
Cause: Returning 'null' or 'undefined' to remove an item instead of an empty array.
Fix: Return an empty array [] to ensure the item is removed during the flattening step.
[1, 2].flatMap(x => x === 1 ? null : [x]); // Returns [null, 2] instead of [2]TypeError
Cause: Attempting to use flatMap in an environment where it is not supported, such as Internet Explorer.
Fix: Use a polyfill or transpile code with Babel. IE is not supported.
[1, 2].flatMap(x => [x]); // Throws 'is not a function' in IERuntime support
Compatibility
Source: MDN Web Docs
Common questions
Frequently Asked Questions
Maps and flattens one level in a single pass (returns new array).
callback: Returns a value or an array of values. thisArg: Value used as 'this' inside callback.
LogicError: Use map() combined with flat(depth) if you need to flatten multiple levels of nesting. LogicError: Return an empty array [] to ensure the item is removed during the flattening step. TypeError: Use a polyfill or transpile code with Babel. IE is not supported.