jQuery jQuery.map() Method

What You’ll Learn

The jQuery.map() utility transforms arrays, array-like objects, and plain objects into a new array of results. This tutorial covers syntax, five worked examples, how to filter with null, flatten nested arrays, and how $.map differs from $.each and DOM .map().

Introduction

Mapping is one of the most useful patterns in JavaScript: take a list of items, run a function on each one, and collect the outputs into a new list. jQuery provides jQuery.map() (also written $.map()) as a static utility that does exactly that for arrays, array-like objects, and plain objects.

Unlike jQuery.each(), which is built for side effects and returns the original collection, $.map() is built for transformation and always returns a fresh array. If you need to map over DOM elements inside a jQuery selection, use the separate instance method $(selector).map() instead.

Understanding the jQuery.map() Method

jQuery.map(collection, callback) invokes your callback once for every top-level item. For arrays and array-like objects, the callback receives (value, index). For plain objects, it receives (value, key). Each return value is collected; null and undefined are skipped; returned arrays are flattened one level into the result.

Choose $.map() when you want a transformed copy of your data — doubling numbers, formatting strings, extracting object values, or building a filtered list — without mutating the source collection.

📝 Syntax

General form of jQuery.map:

jQuery.map( arrayOrObject, callback(valueOrElement, indexOrKey) )
// or
$.map( arrayOrObject, callback(valueOrElement, indexOrKey) )

Parameters

• arrayOrObject — an array, array-like object (with length and indexed values), or plain JavaScript object to translate.
• callback — a function invoked for each item. For arrays: (element, index). For objects: (value, key). Inside the callback, this refers to the global object (window in browsers).

Return value

• A new array containing the mapped results.
• Items where the callback returns null or undefined are omitted.
• Arrays returned from the callback are concatenated (flattened one level) into the result.

Minimal workflow

var doubled = $.map([1, 2, 3], function (n) {
  return n * 2;
});

console.log(doubled); // [2, 4, 6]

Examples Gallery

Each example uses $.map(). Open DevTools or use the Try-it links to run them interactively.

var result = $.map([0, 1, 2], function (n) {
  return n + 4;
});

console.log(result); // [4, 5, 6]

[4, 5, 6]

var letters = ["a", "b", "c", "d", "e"];

var formatted = $.map(letters, function (n, i) {
  return n.toUpperCase() + i;
});

console.log(formatted.join(", "));
// "A0, B1, C2, D3, E4"

A0, B1, C2, D3, E4

var filtered = $.map([0, 1, 2], function (n) {
  return n > 0 ? n + 1 : null;
});

console.log(filtered); // [2, 3]

[2, 3]

var flat = $.map([0, 1, 2], function (n) {
  return [n, n + 1];
});

console.log(flat); // [0, 1, 1, 2, 2, 3]

[0, 1, 1, 2, 2, 3]

var dimensions = { width: 10, height: 15, length: 20 };

var doubled = $.map(dimensions, function (value, key) {
  return value * 2;
});

console.log(doubled); // [20, 30, 40]

[20, 30, 40]

🚀 Common Use Cases

• Data normalization — convert raw API rows into display strings or numeric scores.
• Inline filter-map — transform valid items and drop invalid ones with null in one loop.
• Object value extraction — pull and transform enumerable properties into an array for charts or templates.
• Building option lists — map id/name pairs from server data into label strings for a <select>.
• Legacy flattening — expand each item into multiple outputs by returning nested arrays.
• Array-like objects — map over NodeLists or custom collections that expose length and indexed slots.

📝 Notes

• Arrays and array-like objects supported since jQuery 1.0; plain objects since jQuery 1.6.
• Do not use $.map on a jQuery DOM object — call $(sel).map(fn) instead.
• Inside the callback, this is the global object, not the current array element.
• Mapping an object always yields an array of values; property keys are not included unless you return them yourself.
• Only one level of array flattening happens automatically — deeply nested arrays stay nested.
• For side effects without collecting values, prefer $.each; for immutable transforms, prefer $.map.

💡 Best Practices