jQuery .undelegate() Method deprecated 3.0

What You’ll Learn

The .undelegate() method removes delegated event handlers attached with .delegate(). Deprecated since jQuery 3.0 and superseded by .off() since 1.7, it still appears in legacy plugins and themes. This tutorial covers all official signatures, five worked examples, namespace cleanup, migration with swapped argument order, and why new code should use .off().

Introduction

Event delegation lets you attach one handler on a stable parent and filter events from matching descendants. jQuery introduced .delegate() in version 1.4.2 for this pattern, with .undelegate() as its removal counterpart. Together they predated the unified .on() / .off() API from jQuery 1.7.

As of jQuery 3.0, .undelegate() is deprecated. It still runs in jQuery 3.x for backward compatibility, but every new project should use .off(eventType, selector, handler) on the same root element — note the reversed argument order compared to .undelegate(selector, eventType, handler).

Understanding .undelegate()

.undelegate() operates on the root element where delegation was attached — not on the descendant that triggers the event. If you called $("body").delegate("#theone", "click", fn), you must call $("body").undelegate("#theone", "click", fn) on body, not on #theone.

The descendant selector must exactly match what was passed to .delegate(). Handler removal by function reference requires the same function object used during binding — anonymous inline functions cannot be removed unless you keep a reference.

📝 Syntax

Five signatures from the official jQuery API (all deprecated since 3.0):

1. Remove all delegated — .undelegate()

.undelegate()

2. By selector and type — .undelegate( selector, eventType [, handler ] )

$( "body" ).undelegate( "p", "click", foo );

3. Event type only — .undelegate( eventType )

$( "p" ).undelegate( "click" );

4. Events map — .undelegate( selector, events ) since 1.4.3

$( "#list" ).undelegate( "li", {
  click: handlerA,
  mouseenter: handlerB
});

5. Namespace — .undelegate( namespace ) since 1.6

$( "form" ).undelegate( ".whatever" );

Migration to .off()

// Legacy — selector FIRST
$( "#list" ).delegate( "li", "click", fn );
$( "#list" ).undelegate( "li", "click", fn );

// Modern — event type FIRST
$( "#list" ).on( "click", "li", fn );
$( "#list" ).off( "click", "li", fn );

// Namespace — same on both APIs
$( "form" ).undelegate( ".whatever" );
$( "form" ).off( ".whatever" );

Return value

• Returns the original jQuery object for chaining.
• Only removes handlers attached via .delegate() on the matched root elements.

Examples Gallery

All five examples follow the official jQuery API documentation for .undelegate(). Try-it labs use .delegate() / .undelegate() on the legacy API to match the docs.

function aClick() {
  $( "div" ).show().fadeOut( "slow" );
}

$( "#bind" ).on( "click", function() {
  $( "body" )
    .delegate( "#theone", "click", aClick )
    .find( "#theone" ).text( "Can Click!" );
});

$( "#unbind" ).on( "click", function() {
  $( "body" )
    .undelegate( "#theone", "click", aClick )
    .find( "#theone" ).text( "Does nothing..." );
});

Bind Click → body.delegate on #theone

Click #theone → div flashes

Unbind Click → .undelegate removes handler

Modern: body.off("click", "#theone", aClick)

$( "p" ).undelegate();

p is delegation root with handlers on descendants

$("p").undelegate() → all delegated entries removed

Direct .bind() handlers on p itself are NOT removed

$( "p" ).undelegate( "click" );

#list has delegated click on li + mouseenter on li

$("#list").undelegate("click") → click delegation gone

Delegated mouseenter still works

Modern: $("#list").off("click")

var foo = function() {
  // Code to handle some kind of event
};

$( "body" ).delegate( "p", "click", foo );
$( "body" ).undelegate( "p", "click", foo );

Two handlers delegated on body for click p

.undelegate("p", "click", handlerA) removes only handlerA

handlerB still runs on p clicks

Modern: body.off("click", "p", handlerA)

var foo = function() {
  // Code to handle some kind of event
};

$( "form" ).delegate( ":button", "click.whatever", foo );
$( "form" ).delegate( "input[type='text']", "keypress.whatever", foo );

$( "form" ).undelegate( ".whatever" );

click.whatever on :button + keypress.whatever on input

.undelegate(".whatever") removes BOTH

Other delegated handlers without .whatever untouched

Modern: form.off(".whatever")

🚀 Why You Still See .undelegate()

• Legacy jQuery plugins — delegated bind/unbind before .on() existed.
• Maintenance & migration — read old code before swapping to .off().
• Toggle delegation — official bind/unbind button demo from Example 1.
• Widget teardown — .undelegate(".myPlugin") in destroy methods.
• Understanding .off() — see why argument order flipped from legacy delegation.
• Pair with .delegate() — the complete legacy delegation story.

📝 Notes

• .undelegate() was added in jQuery 1.4.2; namespace-only form since 1.6; deprecated in 3.0.
• Only removes handlers from .delegate() — not .live() (use .die()) or .bind() (use .unbind()).
• Argument order is selector first, event type second — opposite of .off().
• Call .undelegate() on the delegation root, not on the descendant that receives clicks.
• Proxied handlers: unbinding one proxied function may affect others; prefer namespaces.
• Modern replacement: .off(eventType, selector, handler) on the same root element.

💡 Best Practices