jQuery .mousemove() Method

What You’ll Learn

The .mousemove() method is jQuery’s legacy shorthand for binding and triggering the mousemove event. This tutorial covers .mousemove(handler) since 1.0, .mousemove(eventData, handler) since 1.4.3, no-argument .mousemove() as a trigger, migration to .on("mousemove") and .trigger("mousemove"), and why the binding form is deprecated since jQuery 3.3. For the modern mousemove event API, see the jQuery mousemove event tutorial.

Introduction

Before jQuery 1.7 unified events with .on() and .off(), every common event had a matching shorthand — .click(), .mousemove(), .keydown(), and dozens more. The .mousemove() method let you track pointer movement in one short call: $("#canvas").mousemove(function(e){ ... }). It remains in jQuery 3.x for backward compatibility but is marked deprecated.

Understanding .mousemove() matters when reading older drag-and-drop plugins, drawing tools, and legacy tutorials. The method does two distinct jobs: with a function argument it binds; with no arguments it triggers. Modern jQuery splits those roles explicitly — .on("mousemove", handler) for binding and .trigger("mousemove") for firing. This page documents the shorthand API and shows how to migrate.

Understanding the .mousemove() Method

The official jQuery API describes .mousemove() as a way to bind an event handler to the mousemove event, or trigger that event on an element. When you pass a handler, jQuery registers it on each matched element and calls it whenever the pointer moves inside that element — often many times per second. Handlers typically read event.pageX and event.pageY for coordinates.

When you call .mousemove() with no arguments, jQuery synthetically fires the mousemove event on each matched element. Bound handlers run immediately. This trigger behavior is equivalent to .trigger("mousemove").

📝 Syntax

The .mousemove() method has three signatures from the official jQuery API. The binding forms are deprecated; the trigger form remains valid but .trigger("mousemove") is preferred:

1. Bind a handler — .mousemove( handler ) (since 1.0, deprecated 3.3)

.mousemove( handler )

• handler — function executed each time mousemove fires: function( event ) { ... }.
• Returns the jQuery object for chaining.
• Modern replacement: .on( "mousemove", handler ).

2. Bind with eventData — .mousemove( [eventData], handler ) (since 1.4.3, deprecated 3.3)

.mousemove( [eventData], handler )

• eventData — optional object available in the handler as event.data.
• Modern replacement: .on( "mousemove", eventData, handler ).

3. Trigger the event — .mousemove() (since 1.0)

.mousemove()

• No arguments — triggers mousemove on every matched element.
• Runs bound mousemove handlers.
• Preferred replacement: .trigger( "mousemove" ).

Official jQuery API migration note

// Deprecated binding
$( "#target" ).mousemove( function( event ) {
  $( "#log" ).text( "pageX: " + event.pageX + ", pageY: " + event.pageY );
} );

// Modern binding
$( "#target" ).on( "mousemove", function( event ) {
  $( "#log" ).text( "pageX: " + event.pageX + ", pageY: " + event.pageY );
} );

// Deprecated trigger
$( "#target" ).mousemove();

// Modern trigger
$( "#target" ).trigger( "mousemove" );

Return value

• All .mousemove() signatures return the original jQuery object for chaining.
• Handler return values are ignored unless you use return false (equivalent to preventDefault() + stopPropagation()).

Examples Gallery

Five examples cover binding, eventData, triggering, migration from .mousemove() to .on("mousemove"), and legacy drag tracking with .mousedown() + .mousemove(). Use the Try-it links to run each snippet in the browser. Remember: binding with .mousemove(handler) is deprecated — these demos show legacy syntax you will encounter in older code.

$( "#target" ).mousemove( function( event ) {
  $( "#log" ).text(
    "pageX: " + event.pageX + ", pageY: " + event.pageY
  );
} );

Move over #target → log updates with pageX and pageY

Values change continuously as the pointer moves

Deprecated — prefer .on("mousemove", fn) for new code

$( "#target" ).mousemove( { mode: "track" }, function( event ) {
  $( "#log" ).text(
    "mode: " + event.data.mode +
    " | pageX: " + event.pageX +
    ", pageY: " + event.pageY
  );
} );

Move over #target → "mode: track | pageX: 120, pageY: 85"

event.data.mode comes from { mode: "track" }

Modern equivalent: .on("mousemove", { mode: "track" }, fn)

var count = 0;

$( "#target" ).mousemove( function() {
  count++;
  $( "#log" ).text( "Handler fired (count: " + count + ")" );
} );

$( "#fire" ).click( function() {
  $( "#target" ).mousemove();
} );

Move over #target → count increments naturally

Click #fire → $("#target").mousemove() → same handler runs

No-arg .mousemove() is trigger shorthand — prefer .trigger("mousemove")

$( "#legacy" ).mousemove( function( event ) {
  $( "#log" ).text(
    "Legacy: .mousemove(function(){ ... }) — pageX: " + event.pageX +
    " — deprecated since jQuery 3.3."
  );
} );

$( "#modern" ).on( "mousemove", function( event ) {
  $( "#log" ).text(
    "Modern: .on('mousemove', function(){ ... }) — pageX: " + event.pageX +
    " — use this for new code."
  );
} );

Move over #legacy → legacy deprecation message with pageX

Move over #modern → modern .on("mousemove") message with pageX

Behavior is identical — only the API name differs

function onMove( event ) {
  $( "#box" ).css( { left: event.pageX - 25, top: event.pageY - 25 } );
}

$( "#box" ).mousedown( function( event ) {
  if ( event.which !== 1 ) return;
  $( document ).mousemove( onMove );
  $( document ).one( "mouseup", function() {
    $( document ).off( "mousemove", onMove );
    $( "#log" ).text( "Released — .off('mousemove') called." );
  } );
} );

Press left button on #box → $(document).mousemove(onMove)

Drag anywhere → box follows cursor via pageX/pageY

Release anywhere → $(document).off("mousemove", onMove)

Migrate to .on("mousedown") / .on("mousemove") / .off("mousemove") in new code

🚀 Common Use Cases

• Reading legacy code — recognize $("#canvas").mousemove(fn) as equivalent to .on("mousemove", fn) in older drag libraries.
• Coordinate tracking — legacy code uses .mousemove(fn) to read event.pageX and event.pageY — migrate to .on("mousemove", fn).
• Proxy triggers — $("#btn").click(function(){ $("#target").mousemove(); }) — replace inner no-arg .mousemove() with .trigger("mousemove").
• Shared eventData — $("#panel").mousemove({ mode: "track" }, fn) passes metadata without closures.
• Drag pairs — chain .mousedown(fn).mousemove(drag) on document — unbind with .off("mousemove") on mouseup.
• Automated testing — test suites may call .mousemove() to simulate movement — consider .trigger("mousemove") for explicit intent.

📝 Notes

• Deprecated since jQuery 3.3 — do not use .mousemove(handler) or .mousemove(eventData, handler) in new code. Use .on("mousemove") instead.
• Bind with .mousemove(handler) since jQuery 1.0; eventData form since 1.4.3.
• No-argument .mousemove() triggers the event since jQuery 1.0 — prefer .trigger("mousemove").
• .mousemove() does not support event delegation — use .on("mousemove", selector, fn) for dynamic elements.
• mousemove is high-frequency — keep handlers lightweight and unbind with .off("mousemove") when tracking ends.
• Remove handlers with .off("mousemove") — not by calling .mousemove(undefined).
• Legacy code using .mousemove() still runs in jQuery 3.x — migrate when you refactor those files.
• For the full modern mousemove guide — drag patterns, coordinates, and performance — see the jQuery mousemove event tutorial.

💡 Best Practices