Suggest an edit

Improve this article

Refine the answer for “flatMap() vs map()”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

The `map()` and `flatMap()` methods really are similar, but they have one **key difference**: `flatMap()` not only **transforms elements**, but also **"flattens" nested arrays by one level**. Let's break it down step by step:

---

## 1. Main difference

| Method | What it does |
|---|---|
| `map()` | Transforms each array element and returns a **new array** of the same size |
| `flatMap()` | Transforms each element, **then merges nested arrays** into one flat array (equivalent to `map().flat(1)`) |

---

## Example 1. Regular map()

```javascript
const words = ["hello", "world"];

const mapped = words.map(word => word.split(""));

console.log(mapped);
// [['h','e','l','l','o'], ['w','o','r','l','d']]
```

> `map()` creates an **array of arrays**, a nested structure. It merges nothing, it just returns what you returned from the callback.

---

## Example 2. flatMap() does the same, but flattens the result

```javascript
const words = ["hello", "world"];

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

console.log(flattened);
// ['h','e','l','l','o','w','o','r','l','d']
```

> `flatMap()` applied `split()` and **merged the result** into one flat array. Same as:
>
> ```javascript
> words.map(word => word.split("")).flat();
> ```

---

## Example 3. Real scenario - filtering and transforming together

```javascript
const sentences = [
  "hello world",
  "js is awesome"
];

// we want an array of all words
const words = sentences.flatMap(sentence => sentence.split(" "));

console.log(words);
// ['hello', 'world', 'js', 'is', 'awesome']
```

> Very convenient when you need to **"split and merge"** elements into one collection.

---

## Example 4. Difference in result size

```javascript
const arr = [1, 2, 3];

const mapped = arr.map(x => [x, x * 2]);
console.log(mapped);
// [[1,2], [2,4], [3,6]] - length 3

const flatMapped = arr.flatMap(x => [x, x * 2]);
console.log(flatMapped);
// [1,2,2,4,3,6] - length 6
```

> `flatMap()` does not create nesting, it merges all sub-arrays into one level.

---

## Important:

- `flatMap()` **always flattens only 1 level deep** (`flat(1)`).

```javascript
  [[1], [2, [3]]].flatMap(x => x);
  // [1, 2, [3]]
  ```
- If you need to "flatten deeper" (`flat(2)` or more), use `flat()` separately.
- `flatMap()` **does not change the original array**, it returns a new one.

---

## Frequent mistakes

1. **Expecting deep flattening:**

```javascript
  [ [1, [2]], [3, [4]] ].flatMap(x => x);
  // [1, [2], 3, [4]] - not deep!
  ```
Use `flat(2)`:

```javascript
  [ [1, [2]], [3, [4]] ].flat(2);
  // [1, 2, 3, 4]
  ```
2. **Forgotten** `return` **with curly braces**

```javascript
  arr.flatMap(x => { [x, x*2] }); // returns []
  ```
Correct:

```javascript
  arr.flatMap(x => [x, x*2]);
  // or
  arr.flatMap(x => { return [x, x*2]; });
  ```

---

## When to use flatMap()

| Goal | Does `flatMap()` fit |
|---|---|
| Transform array elements | Yes |
| Get a flat list from nested results | Yes |
| Flatten an array without transformation | No, use `flat()` |
| Keep the nesting | No, use `map()` |

---

## In short:

> `flatMap()` **=** `map()` **+** `flat(1)`

A formula to remember:
`arr.flatMap(fn)` -> applies `fn` to each element and merges the result into one level.

---

## Comparison: map() vs flatMap()

| Criterion | `map()` | `flatMap()` |
|---|---|---|
| Transforms elements | Yes | Yes |
| Returns nested arrays | Yes | No |
| Flattens the result | No | Yes (1 level) |
| Changes the original array | No | No |
| Analog | `arr.map()` | `arr.map().flat(1)` |

---

## Real example: processing API data

```javascript
const users = [
  { name: 'Tim', hobbies: ['ski', 'guitar'] },
  { name: 'Alex', hobbies: ['books'] },
  { name: 'John', hobbies: ['surf', 'code'] },
];

// get all hobbies into one list
const hobbies = users.flatMap(user => user.hobbies);

console.log(hobbies);
// ['ski', 'guitar', 'books', 'surf', 'code']
```

> The ideal case for `flatMap()` is when the callback returns **arrays**, and you want to get **one merged list**.

Markdown · drag & drop images · ⌘B / ⌘I shortcuts634 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.