JavaScript Reference
Array.prototype.map()
Creates a new array by transforming every element with a callback function.
Last updated: October 2026
map() transforms every element in an array and returns a new array. Use it when you need to change each item without mutating the original.
Full definition: Array.prototype.map() creates a new array by calling a function on every element of the original array. It doesn't modify the original array.
🎬 Live Example
Five common map patterns. Click any button to see the output.
💡 Every example returns a new array. The input is never modified.
Basic Syntax
array.map(callback(element, index, array))
// Returns a new array of the same lengthThe callback receives three arguments, but you usually only need the first one.
🎯 Syntax & Parameters
| Parameter | Type | Description |
|---|---|---|
callback | Function | Runs for each element. Returns the new value. |
element | any | The current element being processed. |
index | number | The index of the current element. |
array | Array | The original array map was called on. |
Transform Numbers
const numbers = [1, 2, 3, 4, 5];
const doubled = numbers.map(n => n * 2);
// [2, 4, 6, 8, 10]
const squared = numbers.map(n => n ** 2);
// [1, 4, 9, 16, 25]
// Original is unchanged
console.log(numbers); // [1, 2, 3, 4, 5]Extract Properties from Objects
const users = [
{ name: 'Alice', age: 30 },
{ name: 'Bob', age: 25 },
{ name: 'Carol', age: 35 }
];
const names = users.map(u => u.name);
// ['Alice', 'Bob', 'Carol']
const ages = users.map(u => u.age);
// [30, 25, 35]Using the Index Argument
const letters = ['a', 'b', 'c'];
const withIndex = letters.map((letter, i) => `${i}: ${letter}`);
// ['0: a', '1: b', '2: c']
// Build list items
const htmlItems = letters.map((letter, i) =>
`<li data-index="${i}">${letter}</li>`
);Chaining map with Other Methods
const numbers = [1, 2, 3, 4, 5, 6, 7, 8];
const result = numbers
.map(n => n ** 2) // [1, 4, 9, 16, 25, 36, 49, 64]
.filter(n => n > 10); // [16, 25, 36, 49, 64]
// With reduce
const total = numbers
.map(n => n * 2)
.reduce((sum, n) => sum + n, 0);
// 72💡 Chain tip: map → filter runs the filter only after all elements are mapped. filter → map runs map only on the filtered elements. Choose the order that makes the most sense for your logic.
Common Real-World Example — Rendering Lists
// React rendering
function UserList({ users }) {
return (
<ul>
{users.map(user => (
<li key={user.id}>{user.name}</li>
))}
</ul>
);
}
// Vanilla JS
const items = products.map(p =>
`<div class="card">
<h3>${p.name}</h3>
<p>$${p.price}</p>
</div>`
).join('');
document.querySelector('#products').innerHTML = items;🎯 map vs forEach vs filter
| Method | Returns | Use when |
|---|---|---|
map | New array, same length | You want to transform each element |
filter | New array, subset | You want to keep only matching items |
forEach | undefined | You want a side effect (logging, updating) |
reduce | Single value | You want to combine into one value |
find | Element or undefined | You want the first matching item |
⚠️ Common Mistakes
- Forgetting to return.
arr.map(x => { x * 2 })returns[undefined, undefined]. Usearr.map(x => x * 2). - Using map for side effects. If you're not using the returned array, use
forEach. - Assuming map skips empty slots. It does — but forEach also does. Just don't rely on it.
- Modifying the original array inside map. Technically works but is bad practice.
- Confusing map with flatMap. map returns nested arrays; flatMap flattens them.
- Using async callbacks with map. map with async returns an array of Promises. Use
Promise.all()if you need the results. - Chaining map unnecessarily. Two maps in a row means two full passes. Combine them into one when possible.
❓ Frequently Asked Questions
What does Array.map() do in JavaScript?
Array.map() creates a new array by calling a function on each element of the original array. It returns a new array of the same length, without modifying the original array.
What is the difference between map and forEach?
map returns a new array with the results of the callback. forEach returns undefined and is used only for side effects like logging or updating external state. Use map when you need the transformed array.
Can I chain map with filter?
Yes. Both return new arrays, so you can chain them: arr.map(x => x * 2).filter(x => x > 10). The array passes through each method in order.
Does map mutate the original array?
No. map returns a new array. The original array remains unchanged. Any mutations to objects inside the array will still affect both, because the objects are shared by reference.
What are the parameters of the map callback?
The callback receives three arguments: the current element, the index of that element, and the original array. Most code only uses the first argument.