jQuery .toggle() Method Alternating click handlers

What You’ll Learn

The click-handler form of .toggle() bound alternating functions to the click event — first click runs handler one, second click runs handler two, then the cycle repeats. This tutorial covers .toggle(fn1, fn2) since 1.0, three-or-more handler cycling, manual replication with .on("click"), and why the API was removed in jQuery 1.9.

Introduction

Before jQuery 1.9, you could bind two click handlers in one call: $("#target").toggle(fn1, fn2). The first function ran on odd clicks, the second on even clicks — perfect for simple on/off toggles without writing state management by hand. jQuery also provided a separate .toggle() for showing and hiding elements — same method name, different job.

The click-handler form was deprecated in 1.8 and removed in 1.9 because it was fragile: applying it twice to one element failed, cleanup required .off("click"), and the implementation called preventDefault() so links would not navigate. Modern jQuery expects explicit .on("click") handlers or .toggleClass() for selection styling.

Understanding the .toggle() Click-Handler Method

The official jQuery API describes the click-handler .toggle() as a way to bind two or more handlers executed on alternate clicks. Internally it attaches to the click event — the same rules as .on("click") apply. Each matched element keeps its own click counter so handlers cycle independently.

With two handlers, clicks alternate: 1st → handler A, 2nd → handler B, 3rd → handler A again. With three handlers, the cycle is A → B → C → A. The method returns the jQuery object for chaining.

📝 Syntax

The click-handler .toggle() had one signature from the official jQuery API. It was deprecated in 1.8 and removed in 1.9:

1. Alternating handlers — .toggle( handler, handler [, handler ] ) (since 1.0, removed 1.9)

.toggle( handler, handler [, handler ] )

• handler — functions executed in rotation on each click.
• Two handlers: even clicks (1st, 3rd, 5th…) run the first; odd clicks (2nd, 4th…) run the second.
• Three+ handlers: cycles through all, then wraps to the first.
• Modern replacement: .on( "click", fn ) with a counter or state flag.

2. Official jQuery API example

$( "#target" ).toggle(
  function() {
    alert( "First handler for .toggle() called." );
  },
  function() {
    alert( "Second handler for .toggle() called." );
  }
);

3. Unbind — .off( "click" )

$( "#target" ).off( "click" );

• There is no "toggle" event — legacy .toggle(fn, fn) registered on click.
• .off("click") removes all click handlers, including those from .toggle().

4. Not the same as animation .toggle()

$( "#panel" ).toggle();        // show/hide — still in jQuery 3.x
$( "#panel" ).toggle( true );  // show
$( "#panel" ).toggle( false ); // hide

Return value

• Click-handler .toggle() returned the jQuery object for chaining (in jQuery 1.8 and earlier).

Examples Gallery

Examples 1–3 follow the official jQuery API documentation. Examples 4–5 cover manual replication and .toggleClass(). Try-it labs 1–3 use jQuery 1.12.4 because the click-handler .toggle() was removed in 1.9. Remember: do not use this API in jQuery 3.x.

$( "#target" ).toggle(
  function() {
    alert( "First handler for .toggle() called." );
  },
  function() {
    alert( "Second handler for .toggle() called." );
  }
);

1st click → "First handler for .toggle() called."
2nd click → "Second handler for .toggle() called."
3rd click → first handler again — cycle repeats

$( "#cycle" ).toggle(
  function() { $( "#log" ).text( "Handler 1 — click 1, 4, 7…" ); },
  function() { $( "#log" ).text( "Handler 2 — click 2, 5, 8…" ); },
  function() { $( "#log" ).text( "Handler 3 — click 3, 6, 9…" ); }
);

Click 1 → Handler 1
Click 2 → Handler 2
Click 3 → Handler 3
Click 4 → Handler 1 (wraps)

$( "td" ).toggle(
  function() {
    $( this ).addClass( "selected" );
  },
  function() {
    $( this ).removeClass( "selected" );
  }
);

1st click on td → .selected added
2nd click on same td → .selected removed

Official API recommends .toggleClass("selected") instead

var count = 0;

$( "#target" ).on( "click", function() {
  if ( count % 2 === 0 ) {
    $( "#log" ).text( "Handler A — 1st, 3rd, 5th click…" );
  } else {
    $( "#log" ).text( "Handler B — 2nd, 4th, 6th click…" );
  }
  count++;
} );

Click 1 → handler A message
Click 2 → handler B message
Click 3 → handler A again

Use count % N for N handlers

$( "td" ).on( "click", function() {
  $( this ).toggleClass( "selected" );
} );

Each click on td → .selected toggles on/off

Works in jQuery 3.x — no alternating handler pair needed

🚀 Common Use Cases

• On/off toggles — alternate two click actions without a state variable — legacy .toggle(fnOn, fnOff).
• Multi-state UI — cycle three or more views with .toggle(fn1, fn2, fn3).
• Table cell selection — add/remove selected class — better done with .toggleClass() today.
• Reading legacy code — recognize click-handler .toggle() in jQuery 1.8 and earlier codebases.
• Manual migration — replace with .on("click") + counter when upgrading past jQuery 1.8.
• Avoid confusion — distinguish from animation .toggle() for show/hide panels.

📝 Notes

• Removed in jQuery 1.9 — not available in jQuery 3.x. Use .on("click") with a counter or .toggleClass().
• Deprecated in jQuery 1.8; removed in 1.9.
• Binds to the click event internally — same rules as .on("click") apply.
• There is no "toggle" event — unbind with .off("click").
• Calling .toggle(fn, fn) twice on the same element was unreliable — avoid stacking.
• Do not confuse click-handler .toggle(fn, fn) with animation .toggle() for show/hide.
• For class toggling, prefer .toggleClass() over alternating add/remove handlers.

💡 Best Practices