jQuery .map() Method

What You’ll Learn

The .map() traversing method transforms each element in the current set through a callback and builds a new jQuery object from the return values. This tutorial covers the official checkbox ID and form value demos, return-value rules (including null and arrays), the .get().join() pattern, and compares .map() with .each().

Introduction

Sometimes you need to extract data from a jQuery collection — checkbox IDs, input values, element heights — rather than modify the elements in place. The .map() method runs a callback on each matched element and collects whatever the callback returns into a new jQuery object.

Available since jQuery 1.2, .map(callback) is the collection counterpart to side-effect iteration with .each(). It is particularly useful for building lists, comma-separated strings, or transformed DOM fragments from an existing set. Chain .get() when you need a plain JavaScript array.

Understanding the .map() Method

Given a jQuery object with matched DOM elements, .map(function(index, element) { return value; }) invokes the function once per element. Each return value is added to the result — a single item, an array of items (flattened in), or nothing if the callback returns null or undefined.

Inside the callback, this refers to the current DOM element. The return type can be a string, number, DOM node, jQuery object, or array of any of these. The final result is always wrapped in a new jQuery object.

📝 Syntax

General form of .map:

.map( callback )

Parameters

• callback (required) — a function invoked for each element; receives index and DOM element; this is the current element. Return a value to include in the result, null/undefined to skip, or an array to insert multiple items.

Return value

• A new jQuery object containing the collected return values from the callback.

Official jQuery API checkbox example

$( ":checkbox" )
  .map( function () {
    return this.id;
  } )
  .get()
  .join();
// "two,four,six,eight"

Examples Gallery

Examples 1–4 follow the official jQuery API documentation. Use DevTools or the Try-it links to run each snippet in the browser.

$( ":checkbox" )
  .map( function () {
    return this.id;
  } )
  .get()
  .join();

"two,four,six,eight"
Checked boxes with ids two, four, six, eight

$( "p" ).append(
  $( "input" ).map( function () {
    return $( this ).val();
  } )
  .get()
  .join( ", " )
);

Values: 2, 4, 6, 8
Appended to paragraph from input.val() map

var mappedItems = $( "li" ).map( function ( index ) {
  var replacement = $( " " ).text( $( this ).text() ).get( 0 );
  if ( index === 0 ) {
    $( replacement ).text( $( replacement ).text().toUpperCase() );
  } else if ( index === 1 || index === 3 ) {
    replacement = null;  // skip 2nd and 4th
  } else if ( index === 2 ) {
    replacement = [ replacement, $( " " ).text( "Extra" ).get( 0 ) ];
  }
  return replacement;
});
$( "#results" ).append( mappedItems );

FIRST (uppercase), Third, Extra, Fifth
Second and Fourth skipped via null

$.fn.equalizeHeights = function () {
  var maxHeight = this.map( function ( i, e ) {
    return $( e ).height();
  } ).get();
  return this.height( Math.max.apply( null, maxHeight ) );
};
$( "div" ).equalizeHeights();

All divs set to tallest height
.map() collects heights → Math.max → .height()

var texts = $( "#map-demo li" ).map( function () {
  return $( this ).text();
} ).get().join( " | " );

$( "#map-demo li" ).each( function ( i ) {
  $( this ).css( "color", i % 2 ? "blue" : "green" );
});

// .map() → string of text | .each() → colors each li

.map().get().join() → "A | B | C"
.each() → alternating green/blue text colors

🚀 Common Use Cases

• Form serialization helpers — collect input values or names with .map().
• Checked item IDs — $(":checked").map(function(){ return this.value; }).get().
• Build option lists — map elements to new DOM nodes for re-insertion.
• Height/width arrays — plugin math like equalize-heights pattern.
• Extract text or attributes — .map(function(){ return this.dataset.id; }).
• Filter via null — skip elements by returning null instead of using .filter().

📝 Notes

• Available since jQuery 1.2 — callback required.
• Returns a new jQuery object — not the original matched set.
• Return null or undefined to skip an element in the result.
• Return an array to insert multiple values for one iteration.
• Chain .get() for a plain JavaScript array before .join() or Math.max.
• For plain arrays/objects (not DOM collections), use static jQuery.map() instead.

💡 Best Practices