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.
// Iterator helpers (Baseline Newly available)
Iterator.prototype.flatMap(callbackFn)
// callbackFn(value) : must return an iterable or iterator
// returns : a new lazy iterator helper
Parameters
Parameter
Description
callbackFn
Required. Called once per value as callbackFn(value). Must return an iterable or iterator whose values are yielded (flattened one level).
Return Value
Return Value
Description
Iterator helper
A 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().
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
Start with three numbers. The source yields 1, 2, and 3.
Return a small array each time. For 1 the callback returns [1, 10], and so on.
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.
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
Odd numbers vanish. For 1 and 3 the callback returns [], so nothing is yielded.
Even numbers stay. For 2 and 4 it returns [n], so those values appear.
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.
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
Yield two letters. The generator produces "a" and "b".
Expand each letter. The callback returns the letter and its uppercase form.
Print the flat stream.for...of shows four lines in order.
Compatibility
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.
2025Standard since
Google Chrome122+ · Desktop & Mobile
Full support
Microsoft Edge122+ · Chromium based
Full support
Mozilla Firefox131+ · Desktop & Mobile
Full support
Apple Safari18.4+ · macOS & iOS
Full support
Opera108+ · Chromium based
Full support
Samsung Internet26+ · Android
Supported
Android WebView122+ · Chromium based
Supported
Node.js22+ · Server runtime
Supported
DenoRecent versions · JavaScript runtime
Supported
BunRecent versions · JavaScript runtime
Supported
Internet ExplorerNo 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.