JavaScript Iterator flatMap() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Instance method

Definition

iterator.flatMap(callbackFn) calls callbackFn on each source value. The callback must return an iterable or iterator of values. Those inner values are yielded one by one, so one input can become zero, one, or many outputs.

The result is a lazy iterator helper. Chain more helpers if you like, then collect with toArray() or walk with for...of when you need the flat list.

Remember
iterator.flatMap(callbackFn)

callback returns → an iterable / iterator
inner values    → yielded one by one (flattened)
returns         → a new lazy iterator

One input can become many outputs
Collect with toArray() or for...of

Syntax

Call flatMap() on an iterator. The callback must return an iterable (or iterator) of values to flatten.

JavaScript
const it = [1, 2, 3].values();

const pairs = it.flatMap((n) => [n, n * 10]);

console.log(pairs.toArray());   // [1, 10, 2, 20, 3, 30]
CallWhat it does
iterator.flatMap(callbackFn)Map each value to an iterable/iterator and flatten one level.
iterator.flatMap(fn).toArray()Flat-map values, then collect them into an array.
[1, 2].values().flatMap(fn)Start from an array iterator with .values().
iterator.flatMap(() => [])Return an empty iterable to drop that source value.

An Iterator helper (Baseline Newly available) on Iterator.prototype. No import required. Feature-detect before use in older engines. Siblings: Iterator.concat(), Iterator.from(), Iterator.zip(), Iterator.zipKeyed(), chunks(), drop(), every(), filter(), find(), forEach(), includes(), join(), map(), reduce(), some(), take(), toArray(), windows(), [Symbol.dispose](), [Symbol.iterator]().

Library declarations
JavaScript
// Iterator helpers (Baseline Newly available)
Iterator.prototype.flatMap(callbackFn)

// callbackFn(value) : must return an iterable or iterator
// returns          : a new lazy iterator helper

Parameters

ParameterDescription
callbackFnRequired. Called once per value as callbackFn(value). Must return an iterable or iterator whose values are yielded (flattened one level).

Return Value

Return ValueDescription
Iterator helperA new lazy iterator that yields every inner value from each callback result, in order. Use toArray() or for...of to consume it.

JavaScript Examples

Example 1 — Flat-Map Each Number into a Pair

For each number, return an array of the number and ten times that number, then collect with toArray().

JavaScript
const nums = [1, 2, 3].values();
const pairs = nums.flatMap((n) => [n, n * 10]);

console.log(pairs.toArray());
Try It Yourself

The Try It page first checks that iterator.flatMap() exists, because Iterator helpers are still new. In an older browser it prints a short explanation and the output above. In a current browser it runs the code for real.

How It Works

  1. Start with three numbers. The source yields 1, 2, and 3.
  2. Return a small array each time. For 1 the callback returns [1, 10], and so on.
  3. Flatten one level. toArray() shows all six values in order.

Example 2 — Drop Values by Returning an Empty Iterable

Keep only even numbers by returning a one-item array or an empty array from the callback.

JavaScript
const result = [1, 2, 3, 4].values()
  .flatMap((n) => (n % 2 === 0 ? [n] : []))
  .toArray();

console.log(result);
Try It Yourself

The Try It page first checks that iterator.flatMap() exists, because Iterator helpers are still new. In an older browser it prints a short explanation and the output above. In a current browser it runs the code for real.

How It Works

  1. Odd numbers vanish. For 1 and 3 the callback returns [], so nothing is yielded.
  2. Even numbers stay. For 2 and 4 it returns [n], so those values appear.
  3. Collect the kept ones. toArray() prints [2, 4].

Example 3 — Flat-Map from a Generator

Yield letters from a generator, expand each into two strings, and print with for...of.

JavaScript
function* letters() {
  yield "a";
  yield "b";
}

const expanded = letters().flatMap((ch) => [ch, ch.toUpperCase()]);

for (const item of expanded) {
  console.log(item);
}
Try It Yourself

The Try It page first checks that iterator.flatMap() exists, because Iterator helpers are still new. In an older browser it prints a short explanation and the output above. In a current browser it runs the code for real.

How It Works

  1. Yield two letters. The generator produces "a" and "b".
  2. Expand each letter. The callback returns the letter and its uppercase form.
  3. Print the flat stream. for...of shows four lines in order.

Browser & Runtime Support

Iterator.prototype.flatMap() is an Iterator helper (Baseline Newly available since March 2025). It works in current browsers and in Node.js 22 or newer.

✓ Baseline 2025 · Newly available

iterator.flatMap()

Supported in Chrome 122+, Edge 122+, Firefox 131+, Safari 18.4+, Opera 108+ and Node.js 22+. Internet Explorer never got it.

2025 Standard since
Google Chrome 122+ · Desktop & Mobile
Full support
Microsoft Edge 122+ · Chromium based
Full support
Mozilla Firefox 131+ · Desktop & Mobile
Full support
Apple Safari 18.4+ · macOS & iOS
Full support
Opera 108+ · Chromium based
Full support
Samsung Internet 26+ · Android
Supported
Android WebView 122+ · Chromium based
Supported
Node.js 22+ · Server runtime
Supported
Deno Recent versions · JavaScript runtime
Supported
Bun Recent versions · JavaScript runtime
Supported
Internet Explorer No native support
Not supported
iterator.flatMap() Current browsers

Bottom line: Check support with a typeof test before you use it in older browsers. Prefer chaining helpers and calling toArray() last.

Frequently Asked Questions

It maps each value to an iterable or iterator, then yields the inner values one by one (one level of flattening). The result is a lazy iterator helper.
An iterable or iterator of values to yield. Common choices are a small array like [n, n * 10], an empty array [], or another iterator.
map() yields whatever the callback returns as a single value. flatMap() expects an iterable/iterator and flattens those inner values into the output stream.
Yes. Return an empty iterable such as [] and that source value contributes nothing to the output.
No. It flattens only one level: the iterable returned by the callback. Deeper nesting stays as nested structures unless you flatten further yourself.

Next: forEach()

Learn how to run a function for every value from an iterator with forEach().

forEach() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

14 people found this page helpful