jQuery Callbacks

What You’ll Learn

Need a lightweight pub/sub system or plugin hook list? jQuery Callbacks gives you a managed queue of functions — register with add(), trigger with fire(), and control lifecycle with flags and lock methods. This hub links to 12 Callbacks method tutorials.

Introduction

Multiple parts of your app may need to react to the same event — data loaded, plugin initialized, button clicked. Instead of one giant function, you maintain a list of handlers and run them together when something happens.

What Is the jQuery Callbacks Object?

$.Callbacks() is a factory that returns a callback list — an object with methods like add(), fire(), remove(), and lock(). It separates registration from invocation, keeping event wiring clean and testable.

Key Features

• List management — Add, remove, or clear handlers in a controlled queue.
• Flexible invocation — Pass arguments with fire() or bind this with fireWith().
• Behavior flags — Optional once, memory, unique, and stopOnFalse at creation time.
• Lifecycle control — Freeze with lock(), shut down with disable(), and query status with fired(), locked(), disabled().

📝 Syntax

Minimal Callbacks workflow:

const callbacks = $.Callbacks();

callbacks.add(function (message) {
  console.log("Handler:", message);
});

callbacks.fire("Hello, Callbacks!");

Method groups

🏷️ Callbacks Flags

Pass a space-separated string when creating the list:

const onReady = $.Callbacks("once memory");
onReady.fire("app-ready");
onReady.add(function (state) {
  console.log("Late subscriber:", state); // replays "app-ready"
});

When to Use Callbacks

• Custom event buses — Lightweight pub/sub without DOM events.
• Plugin hooks — Let users register callbacks for lifecycle events.
• Deferred internals — jQuery uses Callbacks lists inside Deferred/promise queues.
• Init guards — Combine once and fired() for one-time setup.
• Test doubles — Spy on whether handlers were added or lists fired.

Examples Gallery

Include jQuery 3.7+ and open DevTools Console (F12) to run each snippet.

const callbacks = $.Callbacks();

callbacks.add(function (msg) {
  console.log("First:", msg);
});
callbacks.add(function (msg) {
  console.log("Second:", msg.toUpperCase());
});

callbacks.fire("hello");

First: hello
Second: HELLO

const EventBus = (function () {
  const listeners = $.Callbacks();
  return {
    on: function (fn) { listeners.add(fn); },
    emit: function (payload) { listeners.fire(payload); }
  };
})();

EventBus.on(function (data) {
  console.log("Received:", data.id, data.value);
});
EventBus.emit({ id: 42, value: "temperature" });

Received: 42 temperature

const callbacks = $.Callbacks("once");

callbacks.add(function () { console.log("Runs once"); });
callbacks.fire();
callbacks.fire(); // ignored

Runs once

const hooks = $.Callbacks();
const plugin = { name: "Slider" };

hooks.add(function (value) {
  console.log(this.name + " changed to", value);
});

hooks.fireWith(plugin, [42]);

Slider changed to 42

const locked = $.Callbacks();
locked.add(function () { console.log("locked: fired"); });
locked.lock();
locked.fire(); // → locked: fired

const disabled = $.Callbacks();
disabled.add(function () { console.log("disabled: fired"); });
disabled.disable();
disabled.fire(); // nothing

locked: fired

🚀 Use Cases

• Plugin lifecycle hooks — onInit, onDestroy callbacks users can register.
• Internal event buses — Decouple modules without DOM event overhead.
• Animation sequences — Fire when steps complete; remove one-time listeners.
• Deferred queues — jQuery uses Callbacks for done/fail/always internally.

🌟 Advantages

• Clean separation — Register handlers separately from triggering them.
• Composable flags — Tune behavior with once, memory, unique, stopOnFalse.
• Lifecycle hooks — lock, disable, and status checks for robust APIs.
• Lightweight — No DOM required — pure JavaScript callback management.

💬 Usage Tips

• Store handler references — Required for remove() and has().
• Use empty() for bulk clear — Not remove() with no arguments.
• Pair action/status methods — lock/locked, disable/disabled, fire/fired.
• Lock after init — Prevent late subscribers from altering plugin hooks.
• Search this index — Jump to any of 12 method pages above.

⚠️ Common Pitfalls

• Anonymous handlers — Cannot remove what you did not store in a variable.
• Duplicate add() — Without unique, the same fn runs twice on fire.
• Confusing lock and disable — lock still fires; disable does not.
• Wrong has()/fired() docs online — Both take no flags; has needs a function reference.
• Removing after lock() — Silent no-op — check locked() first.

💡 Best Practices