{"name":"jQuery","type":"method","title":"jQuery()","deprecated":null,"removed":null,"desc":"Return a collection of matched elements either found in the DOM based on passed argument(s) or created by passing an HTML string.","categories":["core","version/1.0","version/1.4"],"entries":[{"return":"jQuery","signatures":[{"added":"1.0","argument":[{"desc":"A string containing a selector expression","name":"selector","type":"Selector"},{"type":[{"name":"Element"},{"name":"jQuery"}],"desc":"A DOM Element, Document, or jQuery to use as context","name":"context","optional":"true"}]},{"added":"1.0","argument":{"desc":"A DOM element to wrap in a jQuery object.","name":"element","type":"Element"}},{"added":"1.0","argument":{"desc":"An array containing a set of DOM elements to wrap in a jQuery object.","name":"elementArray","type":"Array"}},{"added":"1.0","argument":{"desc":"A plain object to wrap in a jQuery object.","name":"object","type":"PlainObject"}},{"added":"1.0","argument":{"desc":"An existing jQuery object to clone.","name":"jQuery object","type":"PlainObject"}},{"added":"1.4"}],"examples":[{"desc":"Find all p elements that are children of a div element and apply a border to them.","code":"\n$( \"div > p\" ).css( \"border\", \"1px solid gray\" );\n","html":"\n

one

\n

two

\n

three

\n"},{"desc":"Find all inputs of type radio within the first form in the document.","code":"\n$( \"input:radio\", document.forms[ 0 ] );\n"},{"desc":"Find all div elements within an XML document from an Ajax response.","code":"\n$( \"div\", xml.responseXML );\n"},{"desc":"Set the background color of the page to black.","code":"\n$( document.body ).css( \"background\", \"black\" );\n"},{"desc":"Hide all the input elements within a form.","code":"\n$( myForm.elements ).hide();\n"}],"desc":"Accepts a string containing a CSS selector which is then used to match a set of elements.","longdesc":"\n

In the first formulation listed above, jQuery() — which can also be written as $() — searches through the DOM for any elements that match the provided selector and creates a new jQuery object that references these elements:

\n 
$( \"div.foo\" );
\n

If no elements match the provided selector, the new jQuery object is \"empty\"; that is, it contains no elements and has .length property of 0.

\n

Selector Context

\n

By default, selectors perform their searches within the DOM starting at the document root. However, an alternate context can be given for the search by using the optional second parameter to the $() function. For example, to do a search within an event handler, the search can be restricted like so:

\n 
\n$( \"div.foo\" ).click(function() {\n  $( \"span\", this ).addClass( \"bar\" );\n});\n
\n

When the search for the span selector is restricted to the context of this, only spans within the clicked element will get the additional class.

\n

Internally, selector context is implemented with the .find() method, so $( \"span\", this ) is equivalent to $( this ).find( \"span\" ).

\n\n

Using DOM elements

\n

The second and third formulations of this function create a jQuery object using one or more DOM elements that were already selected in some other way.

\n

Note: These formulations are meant to consume only DOM elements; feeding mixed data to the elementArray form is particularly discouraged.

\n

A common use of this facility is to call jQuery methods on an element that has been passed to a callback function through the keyword this:

\n 
\n$( \"div.foo\" ).click(function() {\n  $( this ).slideUp();\n});\n
\n

This example causes elements to be hidden with a sliding animation when clicked. Because the handler receives the clicked item in the this keyword as a bare DOM element, the element must be passed to the $() function before applying jQuery methods to it.

\n

XML data returned from an Ajax call can be passed to the $() function so individual elements of the XML structure can be retrieved using .find() and other DOM traversal methods.

\n 
\n$.post( \"url.xml\", function( data ) {\n  var $child = $( data ).find( \"child\" );\n});\n
\n\n

Cloning jQuery Objects

\n

When a jQuery object is passed to the $() function, a clone of the object is created. This new jQuery object references the same DOM elements as the initial one.

\n\n

Returning an Empty Set

\n

As of jQuery 1.4, calling the jQuery() method with no arguments returns an empty jQuery set (with a .length property of 0). In previous versions of jQuery, this would return a set containing the document node.

\n

Working With Plain Objects

\n

At present, the only operations supported on plain JavaScript objects wrapped in jQuery are: .data(),.prop(),.on(), .off(), .trigger() and .triggerHandler(). The use of .data() (or any method requiring .data()) on a plain object will result in a new property on the object called jQuery{randomNumber} (eg. jQuery123456789).

\n 
\n// Define a plain object\nvar foo = { foo: \"bar\", hello: \"world\" };\n\n// Pass it to the jQuery function\nvar $foo = $( foo );\n\n// Test accessing property values\nvar test1 = $foo.prop( \"foo\" ); // bar\n\n// Test setting property values\n$foo.prop( \"foo\", \"foobar\" );\nvar test2 = $foo.prop( \"foo\" ); // foobar\n\n// Test using .data() as summarized above\n$foo.data( \"keyName\", \"someValue\" );\nconsole.log( $foo ); // will now contain a jQuery{randomNumber} property\n\n// Test binding an event name and triggering\n$foo.on( \"eventName\", function () {\n  console.log( \"eventName was called\" );\n});\n\n$foo.trigger( \"eventName\" ); // Logs \"eventName was called\"\n
\n

Should .trigger( \"eventName\" ) be used, it will search for an \"eventName\" property on the object and attempt to execute it after any attached jQuery handlers are executed. It does not check whether the property is a function or not. To avoid this behavior, .triggerHandler( \"eventName\" ) should be used instead.

\n 
\n$foo.triggerHandler( \"eventName\" ); // Also logs \"eventName was called\"\n
\n "},{"return":"jQuery","signatures":[{"added":"1.0","argument":[{"desc":"A string of HTML to create on the fly. Note that this parses HTML, not XML.","name":"html","type":"htmlString"},{"desc":"A document in which the new elements will be created.","name":"ownerDocument","optional":"true","type":"document"}]},{"added":"1.4","argument":[{"desc":"A string defining a single, standalone, HTML element (e.g.
or
).","name":"html","type":"htmlString"},{"desc":"An object of attributes, events, and methods to call on the newly-created element.","name":"attributes","type":"PlainObject"}]}],"examples":[{"desc":"Create a div element (and all of its contents) dynamically and append it to the body element. Internally, an element is created and its innerHTML property set to the given markup.","code":"\n$( \"

Hello

\" ).appendTo( \"body\" )\n"},{"desc":"Create some DOM elements.","code":"\n$( \"
\", {\n \"class\": \"test\",\n text: \"Click me!\",\n click: function() {\n $( this ).toggleClass( \"test\" );\n }\n})\n .appendTo( \"body\" );\n"}],"desc":"Creates DOM elements on the fly from the provided string of raw HTML.","longdesc":"\n

In the first formulation listed above, jQuery() — which can also be written as $() — searches through the DOM for any elements that match the provided selector and creates a new jQuery object that references these elements:

\n 
$( \"div.foo\" );
\n

If no elements match the provided selector, the new jQuery object is \"empty\"; that is, it contains no elements and has .length property of 0.

\n

Selector Context

\n

By default, selectors perform their searches within the DOM starting at the document root. However, an alternate context can be given for the search by using the optional second parameter to the $() function. For example, to do a search within an event handler, the search can be restricted like so:

\n 
\n$( \"div.foo\" ).click(function() {\n  $( \"span\", this ).addClass( \"bar\" );\n});\n
\n

When the search for the span selector is restricted to the context of this, only spans within the clicked element will get the additional class.

\n

Internally, selector context is implemented with the .find() method, so $( \"span\", this ) is equivalent to $( this ).find( \"span\" ).

\n\n

Using DOM elements

\n

The second and third formulations of this function create a jQuery object using one or more DOM elements that were already selected in some other way.

\n

Note: These formulations are meant to consume only DOM elements; feeding mixed data to the elementArray form is particularly discouraged.

\n

A common use of this facility is to call jQuery methods on an element that has been passed to a callback function through the keyword this:

\n 
\n$( \"div.foo\" ).click(function() {\n  $( this ).slideUp();\n});\n
\n

This example causes elements to be hidden with a sliding animation when clicked. Because the handler receives the clicked item in the this keyword as a bare DOM element, the element must be passed to the $() function before applying jQuery methods to it.

\n

XML data returned from an Ajax call can be passed to the $() function so individual elements of the XML structure can be retrieved using .find() and other DOM traversal methods.

\n 
\n$.post( \"url.xml\", function( data ) {\n  var $child = $( data ).find( \"child\" );\n});\n
\n\n

Cloning jQuery Objects

\n

When a jQuery object is passed to the $() function, a clone of the object is created. This new jQuery object references the same DOM elements as the initial one.

\n\n

Returning an Empty Set

\n

As of jQuery 1.4, calling the jQuery() method with no arguments returns an empty jQuery set (with a .length property of 0). In previous versions of jQuery, this would return a set containing the document node.

\n

Working With Plain Objects

\n

At present, the only operations supported on plain JavaScript objects wrapped in jQuery are: .data(),.prop(),.on(), .off(), .trigger() and .triggerHandler(). The use of .data() (or any method requiring .data()) on a plain object will result in a new property on the object called jQuery{randomNumber} (eg. jQuery123456789).

\n 
\n// Define a plain object\nvar foo = { foo: \"bar\", hello: \"world\" };\n\n// Pass it to the jQuery function\nvar $foo = $( foo );\n\n// Test accessing property values\nvar test1 = $foo.prop( \"foo\" ); // bar\n\n// Test setting property values\n$foo.prop( \"foo\", \"foobar\" );\nvar test2 = $foo.prop( \"foo\" ); // foobar\n\n// Test using .data() as summarized above\n$foo.data( \"keyName\", \"someValue\" );\nconsole.log( $foo ); // will now contain a jQuery{randomNumber} property\n\n// Test binding an event name and triggering\n$foo.on( \"eventName\", function () {\n  console.log( \"eventName was called\" );\n});\n\n$foo.trigger( \"eventName\" ); // Logs \"eventName was called\"\n
\n

Should .trigger( \"eventName\" ) be used, it will search for an \"eventName\" property on the object and attempt to execute it after any attached jQuery handlers are executed. It does not check whether the property is a function or not. To avoid this behavior, .triggerHandler( \"eventName\" ) should be used instead.

\n 
\n$foo.triggerHandler( \"eventName\" ); // Also logs \"eventName was called\"\n
\n "},{"return":"jQuery","signatures":{"added":"1.0","argument":{"desc":"The function to execute when the DOM is ready.","name":"callback","type":"Function"}},"examples":[{"desc":"Execute the function when the DOM is ready to be used.","code":"\n$(function() {\n // Document is ready\n});\n"},{"desc":"Use both the shortcut for $(document).ready() and the argument to write failsafe jQuery code using the $ alias, without relying on the global alias.","code":"\njQuery(function( $ ) {\n // Your code using failsafe $ alias here...\n});\n"}],"desc":"Binds a function to be executed when the DOM has finished loading.","longdesc":"\n

In the first formulation listed above, jQuery() — which can also be written as $() — searches through the DOM for any elements that match the provided selector and creates a new jQuery object that references these elements:

\n 
$( \"div.foo\" );
\n

If no elements match the provided selector, the new jQuery object is \"empty\"; that is, it contains no elements and has .length property of 0.

\n

Selector Context

\n

By default, selectors perform their searches within the DOM starting at the document root. However, an alternate context can be given for the search by using the optional second parameter to the $() function. For example, to do a search within an event handler, the search can be restricted like so:

\n 
\n$( \"div.foo\" ).click(function() {\n  $( \"span\", this ).addClass( \"bar\" );\n});\n
\n

When the search for the span selector is restricted to the context of this, only spans within the clicked element will get the additional class.

\n

Internally, selector context is implemented with the .find() method, so $( \"span\", this ) is equivalent to $( this ).find( \"span\" ).

\n\n

Using DOM elements

\n

The second and third formulations of this function create a jQuery object using one or more DOM elements that were already selected in some other way.

\n

Note: These formulations are meant to consume only DOM elements; feeding mixed data to the elementArray form is particularly discouraged.

\n

A common use of this facility is to call jQuery methods on an element that has been passed to a callback function through the keyword this:

\n 
\n$( \"div.foo\" ).click(function() {\n  $( this ).slideUp();\n});\n
\n

This example causes elements to be hidden with a sliding animation when clicked. Because the handler receives the clicked item in the this keyword as a bare DOM element, the element must be passed to the $() function before applying jQuery methods to it.

\n

XML data returned from an Ajax call can be passed to the $() function so individual elements of the XML structure can be retrieved using .find() and other DOM traversal methods.

\n 
\n$.post( \"url.xml\", function( data ) {\n  var $child = $( data ).find( \"child\" );\n});\n
\n\n

Cloning jQuery Objects

\n

When a jQuery object is passed to the $() function, a clone of the object is created. This new jQuery object references the same DOM elements as the initial one.

\n\n

Returning an Empty Set

\n

As of jQuery 1.4, calling the jQuery() method with no arguments returns an empty jQuery set (with a .length property of 0). In previous versions of jQuery, this would return a set containing the document node.

\n

Working With Plain Objects

\n

At present, the only operations supported on plain JavaScript objects wrapped in jQuery are: .data(),.prop(),.on(), .off(), .trigger() and .triggerHandler(). The use of .data() (or any method requiring .data()) on a plain object will result in a new property on the object called jQuery{randomNumber} (eg. jQuery123456789).

\n 
\n// Define a plain object\nvar foo = { foo: \"bar\", hello: \"world\" };\n\n// Pass it to the jQuery function\nvar $foo = $( foo );\n\n// Test accessing property values\nvar test1 = $foo.prop( \"foo\" ); // bar\n\n// Test setting property values\n$foo.prop( \"foo\", \"foobar\" );\nvar test2 = $foo.prop( \"foo\" ); // foobar\n\n// Test using .data() as summarized above\n$foo.data( \"keyName\", \"someValue\" );\nconsole.log( $foo ); // will now contain a jQuery{randomNumber} property\n\n// Test binding an event name and triggering\n$foo.on( \"eventName\", function () {\n  console.log( \"eventName was called\" );\n});\n\n$foo.trigger( \"eventName\" ); // Logs \"eventName was called\"\n
\n

Should .trigger( \"eventName\" ) be used, it will search for an \"eventName\" property on the object and attempt to execute it after any attached jQuery handlers are executed. It does not check whether the property is a function or not. To avoid this behavior, .triggerHandler( \"eventName\" ) should be used instead.

\n 
\n$foo.triggerHandler( \"eventName\" ); // Also logs \"eventName was called\"\n
\n "}]}