From jQuery JavaScript Library

This section details the event-related functions in the jQuery API. For more information about how jQuery handles and normalizes event properties and functions in a cross-browser manner, see Events (Guide)

bind( type, data, fn )

Binds a handler to a particular event (like click) for each matched element. The event handler is passed an event object that you can use to prevent default behaviour. To stop both default action and event bubbling, your handler has to return false.

In most cases, you can define your event handlers as anonymous functions (see first example). In cases where that is not possible, you can pass additional data as the second parameter (and the handler function as the third), see second example.

Return value: jQuery
Parameters:

• type (String): An event type
• data (Object): (optional) Additional data passed to the event handler as event.data
• fn (Function): A function to bind to the event on each of the set of matched elements

Example:

 $("p").bind("click", function(){
   alert( $(this).text() );
 });

 <p>Hello</p>

 alert("Hello")

Example:

 function handler(event) {
   alert(event.data.foo);
 }
 $("p").bind("click", {foo: "bar"}, handler)

 alert("bar")

Example:

 $("form").bind("submit", function() { return false; })

Example:

 $("form").bind("submit", function(event){
   event.preventDefault();
 });

Example:

 $("form").bind("submit", function(event){
   event.stopPropagation();
 });

blur()

Trigger the blur event of each matched element. This causes all of the functions that have been bound to that blur event to be executed, and calls the browser's default blur action on the matching element(s). This default action can be prevented by returning false from one of the functions bound to the blur event.

Note: This does not execute the blur method of the underlying elements! If you need to blur an element via code, you have to use the DOM method, eg. $("#myinput")[0].blur();

Return value: jQuery
Example:

 $("p").blur();

 <p onblur="alert('Hello');">Hello</p>

 alert('Hello');

blur( fn )

Bind a function to the blur event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the blur event on each of the matched elements.

Example:

 $("p").blur( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onblur="alert('Hello');">Hello</p>

change( fn )

Bind a function to the change event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the change event on each of the matched elements.

Example:

 $("p").change( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onchange="alert('Hello');">Hello</p>

click()

Trigger the click event of each matched element. This causes all of the functions that have been bound to that click event to be executed.

Return value: jQuery
Example:

 $("p").click();

 <p onclick="alert('Hello');">Hello</p>

 alert('Hello');

click( fn )

Bind a function to the click event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the click event on each of the matched elements.

Example:

 $("p").click( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onclick="alert('Hello');">Hello</p>

dblclick( fn )

Bind a function to the dblclick event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the dblclick event on each of the matched elements.

Example:

 $("p").dblclick( function() { alert("Hello"); } );

 <p>Hello</p>

 <p ondblclick="alert('Hello');">Hello</p>

error( fn )

Bind a function to the error event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the error event on each of the matched elements.

Example:

 $("p").error( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onerror="alert('Hello');">Hello</p>

focus()

Trigger the focus event of each matched element. This causes all of the functions that have been bound to the focus event to be executed.

Note: This does not execute the focus method of the underlying elements! If you need to focus an element via code, you have to use the DOM method, eg. $("#myinput")[0].focus();

Return value: jQuery
Example:

 $("p").focus();

 <p onfocus="alert('Hello');">Hello</p>

 alert('Hello');

focus( fn )

Bind a function to the focus event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the focus event on each of the matched elements.

Example:

 $("p").focus( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onfocus="alert('Hello');">Hello</p>

hover( over, out )

A method for simulating hovering (moving the mouse on, and off, an object). This is a custom method which provides an 'in' to a frequent task.

Whenever the mouse cursor is moved over a matched element, the first specified function is fired. Whenever the mouse moves off of the element, the second specified function fires. Additionally, checks are in place to see if the mouse is still within the specified element itself (for example, an image inside of a div), and if it is, it will continue to 'hover', and not move out (a common error in using a mouseout event handler).

Return value: jQuery
Parameters:

• over (Function): The function to fire whenever the mouse is moved over a matched element.
• out (Function): The function to fire whenever the mouse is moved off of a matched element.

Example:

 $("p").hover(function(){
   $(this).addClass("hover");
 },function(){
   $(this).removeClass("hover");
 });

keydown( fn )

Bind a function to the keydown event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the keydown event on each of the matched elements.

Example:

 $("p").keydown( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onkeydown="alert('Hello');">Hello</p>

keypress( fn )

Bind a function to the keypress event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the keypress event on each of the matched elements.

Example:

 $("p").keypress( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onkeypress="alert('Hello');">Hello</p>

keyup( fn )

Bind a function to the keyup event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the keyup event on each of the matched elements.

Example:

 $("p").keyup( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onkeyup="alert('Hello');">Hello</p>

load( fn )

Bind a function to the load event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the load event on each of the matched elements.

Example:

 $("p").load( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onload="alert('Hello');">Hello</p>

mousedown( fn )

Bind a function to the mousedown event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the mousedown event on each of the matched elements.

Example:

 $("p").mousedown( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onmousedown="alert('Hello');">Hello</p>

mousemove( fn )

Bind a function to the mousemove event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the mousemove event on each of the matched elements.

Example:

 $("p").mousemove( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onmousemove="alert('Hello');">Hello</p>

mouseout( fn )

Bind a function to the mouseout event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the mouseout event on each of the matched elements.

Example:

 $("p").mouseout( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onmouseout="alert('Hello');">Hello</p>

mouseover( fn )

Bind a function to the mouseover event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the mouseover event on each of the matched elements.

Example:

 $("p").mouseover( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onmouseover="alert('Hello');">Hello</p>

mouseup( fn )

Bind a function to the mouseup event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the mouseup event on each of the matched elements.

Example:

 $("p").mouseup( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onmouseup="alert('Hello');">Hello</p>

one( type, data, fn )

Binds a handler to a particular event (like click) for each matched element. The handler is executed only once for each element. Otherwise, the same rules as described in bind() apply. The event handler is passed an event object that you can use to prevent default behaviour. To stop both default action and event bubbling, your handler has to return false.

In most cases, you can define your event handlers as anonymous functions (see first example). In cases where that is not possible, you can pass additional data as the second paramter (and the handler function as the third), see second example.

Return value: jQuery
Parameters:

• type (String): An event type
• data (Object): (optional) Additional data passed to the event handler as event.data
• fn (Function): A function to bind to the event on each of the set of matched elements

Example:

 $("p").one("click", function(){
   alert( $(this).text() );
 });

 <p>Hello</p>

 alert("Hello")

ready( fn )

Bind a function to be executed whenever the DOM is ready to be traversed and manipulated. This is probably the most important function included in the event module, as it can greatly improve the response times of your web applications.

In a nutshell, this is a solid replacement for using window.onload, and attaching a function to that. By using this method, your bound function will be called the instant the DOM is ready to be read and manipulated, which is when what 99.99% of all JavaScript code needs to run.

There is one argument passed to the ready event handler: A reference to the jQuery function. You can name that argument whatever you like, and can therefore stick with the $ alias without risk of naming collisions.

Please ensure you have no code in your <body> onload event handler, otherwise $(document).ready() may not fire.

You can have as many $(document).ready events on your page as you like. The functions are then executed in the order they were added.

Return value: jQuery
Parameters:

• fn (Function): The function to be executed when the DOM is ready.

Example:

 $(document).ready(function(){ Your code here... });

Example:

 jQuery(function($) {
   // Your code using failsafe $ alias here...
 });

resize( fn )

Bind a function to the resize event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the resize event on each of the matched elements.

Example:

 $("p").resize( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onresize="alert('Hello');">Hello</p>

scroll( fn )

Bind a function to the scroll event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the scroll event on each of the matched elements.

Example:

 $("p").scroll( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onscroll="alert('Hello');">Hello</p>

select()

Trigger the select event of each matched element. This causes all of the functions that have been bound to that select event to be executed, and calls the browser's default select action on the matching element(s). This default action can be prevented by returning false from one of the functions bound to the select event.

Return value: jQuery
Example:

 $("p").select();

 <p onselect="alert('Hello');">Hello</p>

 alert('Hello');

select( fn )

Bind a function to the select event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the select event on each of the matched elements.

Example:

 $("p").select( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onselect="alert('Hello');">Hello</p>

submit()

Trigger the submit event of each matched element. This causes all of the functions that have been bound to that submit event to be executed, and calls the browser's default submit action on the matching element(s). This default action can be prevented by returning false from one of the functions bound to the submit event.

Note: This does not execute the submit method of the form element! If you need to submit the form via code, you have to use the DOM method, eg. $("form")[0].submit();

Return value: jQuery
Example:

 $("form").submit();

submit( fn )

Bind a function to the submit event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the submit event on each of the matched elements.

Example:

 $("#myform").submit( function() {
   return $("input", this).val().length > 0;
 } );

 <form id="myform"><input /></form>

toggle( even, odd )

Toggle between two function calls every other click. Whenever a matched element is clicked, the first specified function is fired, when clicked again, the second is fired. All subsequent clicks continue to rotate through the two functions.

Use unbind("click") to remove.

Return value: jQuery
Parameters:

• even (Function): The function to execute on every even click.
• odd (Function): The function to execute on every odd click.

Example:

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

trigger( type, data )

Trigger a type of event on every matched element. This will also cause the default action of the browser with the same name (if one exists) to be executed. For example, passing 'submit' to the trigger() function will also cause the browser to submit the form. This default action can be prevented by returning false from one of the functions bound to the event.

You can also trigger custom events registered with bind.

Return value: jQuery
Parameters:

• type (String): An event type to trigger.
• data (Array): (optional) Additional data to pass as arguments (after the event object) to the event handler

Example:

 $("p").trigger("click")

 <p click="alert('hello')">Hello</p>

 alert('hello')

Example:

 $("p").click(function(event, a, b) {
   // when a normal click fires, a and b are undefined
   // for a trigger like below a refers too "foo" and b refers to "bar"
 }).trigger("click", ["foo", "bar"]);

Example:

 $("p").bind("myEvent",function(event,message1,message2) {
 	alert(message1 + ' ' + message2);
 });
 $("p").trigger("myEvent",["Hello","World"]);

 alert('Hello World') // One for each paragraph

unbind( type, fn )

The opposite of bind, removes a bound event from each of the matched elements.

Without any arguments, all bound events are removed.

If the type is provided, all bound events of that type are removed.

If the function that was passed to bind is provided as the second argument, only that specific event handler is removed.

Return value: jQuery
Parameters:

• type (String): (optional) An event type
• fn (Function): (optional) A function to unbind from the event on each of the set of matched elements

Example:

 $("p").unbind()

 <p onclick="alert('Hello');">Hello</p>

 [ <p>Hello</p> ]

Example:

 $("p").unbind( "click" )

 <p onclick="alert('Hello');">Hello</p>

 [ <p>Hello</p> ]

Example:

 $("p").unbind( "click", function() { alert("Hello"); } )

 <p onclick="alert('Hello');">Hello</p>

 [ <p>Hello</p> ]

unload( fn )

Bind a function to the unload event of each matched element.

Return value: jQuery
Parameters:

• fn (Function): A function to bind to the unload event on each of the matched elements.

Example:

 $("p").unload( function() { alert("Hello"); } );

 <p>Hello</p>

 <p onunload="alert('Hello');">Hello</p>