Question

Are the docs for jQuery’s on() function incorrect (or unclear)? Consider this code:

<div>
    <span>
        <div>
            <input type="button" value="click me!" />
        </div>
    </span>
</div>

$(document).on("click", function() {
    console.log(this.toString());
});

The docs state

selector A selector string to filter the descendants of the selected
elements that trigger the event. If the selector is null or omitted,
the event is always triggered when it reaches the selected element.

Clicking the button only causes one console.log for the document itself, while $(document).on("click", "*", function()... causes many.

I know the Stack Overflow community isn’t responsible for the jQuery docs, but shouldn’t they say that when the selector is omitted, the event is only triggered when it reaches the selected element? Or is there something about event delegation I’m not understanding correctly?

Complete fiddle

Answer 1

There is no event delegation when you leave the selector out. From the docs:

If selector is omitted or is null, the event handler is referred to as
direct or directly-bound. The handler is called every time an event
occurs on the selected elements, whether it occurs directly on the
element or bubbles from a descendant (inner) element.

When a selector is provided, the event handler is referred to as
delegated. The handler is not called when the event occurs directly on
the bound element, but only for descendants (inner elements) that
match the selector. jQuery bubbles the event from the event target up
to the element where the handler is attached (i.e., innermost to
outermost element) and runs the handler for any elements along that
path matching the selector.

Basically .on is doing the jQuery thing — it is overloaded to do completely different things depending on arguments. Personally I prefer .delegate for delegation, and .bind for normal events, as they are much clearer and I hope they don’t get removed in later versions.