jQuery Pocket Reference

Triggering Events

The event handlers you register are automatically invoked when the user uses the mouse or keyboard, or when other kinds of events occur. Sometimes, however, it is useful to be able to trigger events manually. The simple way to do this is to invoke one of the event registration methods (like click() or mouseover()) with no argument. Just as many jQuery methods serve as both getters and setters, these event methods register an event handler when invoked with an argument, and trigger event handlers when invoked with no arguments. For example:

// Act as if the user clicked the Submit button
$("#my_form").submit();    

The submit() method in the line above synthesizes an Event object and triggers any event handlers that have been registered for the “submit” event. If none of those event handlers returns false or calls the preventDefault() method of the Event object, the form will actually be submitted. Note that events that bubble will do so even when triggered manually. This means that triggering an event on a selected set of elements may also trigger handlers on the ancestors of those elements.

It is important to note that jQuery’s event triggering methods will trigger any handlers registered with jQuery’s event registration methods, and they will also trigger handlers defined on HTML attributes or Element properties such as onsubmit. But you cannot manually trigger event handlers registered with addEventListener() or attachEvent() (those handlers will still be invoked when a real event occurs, however).

It is also important to note that jQuery’s event triggering mechanism is synchronous—there is no event queue involved. When you trigger an event, event handlers are invoked immediately, before the triggering method you called returns. If you trigger a “click” event, and one of the triggered handlers triggers a “submit” event, all of the matching submit handlers are invoked before the next “click” handler is invoked.

Methods like submit() are convenient for binding and triggering events, but just as jQuery defines a more general bind() method, it also defines a more general trigger() method. Normally, you invoke trigger() with an event type string as the first argument, and it triggers the handlers registered for events of that type on all elements in the jQuery object. So, the submit() call above is equivalent to:

$("#my_form").trigger("submit");

Unlike the bind() and unbind() methods, you cannot specify more than one event type in this string. Like bind() and unbind(), however, you can specify event namespaces to trigger only the handlers defined in that namespace. If you want to trigger only event handlers that have no namespace, append an exclamation mark to the event type. Handlers registered through properties like onclick are considered to have no namespace:

// Trigger button click handlers in namespace ns1
$("button").trigger("click.ns1");  
// Trigger button click handlers in no namespace
$("button").trigger("click!");     

Instead of passing an event type string as the first argument to trigger(), you can also pass an Event object (or any object that has a type property). The type property will be used to determine what kind of handlers to trigger. If you specified a jQuery Event object, it will be the one passed to the triggered handlers. If you specified a plain object, a new jQuery Event object will be created, and the properties of the object you passed will be added to it. This is an easy way to pass additional data to event handlers:

// The onclick handler of button1 triggers
// the same event on button2
$('#button1').click(function(e) {
    $('#button2').trigger(e);
});

// Add extra property to the event object when triggering
$('#button1').trigger({type:'click', synthetic:true});

// Test extra property to distinguish real from synthetic
$('#button1').click(function(e) {
    if (e.synthetic) {...};
});

There is another way to pass additional data to event handlers when you trigger them manually. The value you pass as the second argument to trigger() will become the second argument to each of the event handlers that is triggered. If you pass an array as the second argument, each of its elements will be passed as arguments to the triggered handlers:

// Pass a single extra argument
$('#button1').trigger("click", true);    
// Pass three extra arguments
$('#button1').trigger("click", [x,y,z]); 

Sometimes you may want to trigger all handlers for a given event type, regardless of which document element those handlers are bound to. You could select all elements with $('*') and then call trigger() on the result, but that would be very inefficient. Instead, call the jQuery.event.trigger() utility function, which takes the same arguments as the trigger() method but efficiently triggers event handlers for the specified event type throughout the document. Note that “global events” triggered in this way do not bubble, and only handlers registered using jQuery methods (not event handlers registered with DOM properties like onclick) are triggered with this technique.

After invoking event handlers, trigger() (and the convenience methods that call it) perform whatever default action is associated with the triggered event (assuming that the event handlers didn’t return false or call preventDefault() on the event object). For example, if you trigger a “submit” event on a <form> element, trigger() will call the submit() method of that form, and if you trigger a “focus” event on an element, trigger() will call the focus() method of that element.

If you want to invoke event handlers without performing the default action, use triggerHandler(), which works just like trigger() except that it first calls the preventDefault() and cancelBubble() methods of the Event object. This means that the synthetic event does not bubble or perform the default action associated with it.