What does jquery $ actually return?

Question

I have read the JQuery documentation, and while much attention is devoted to what you should pass the function, I don't see any information on what it actually returns.

In particular, does it always return an array, even if only one element is found? Does it return null when nothing is found? Where is this documented?

I understand that jquery methods can be applied to the return value, but what if I want to just use the return value directly?

Antonetta

Answer 1

From Rick Strahl's description:

The jQuery Object: The Wrapped Set: Selectors return a jQuery object known as the "wrapped set," which is an array-like structure that contains all the selected DOM elements. You can iterate over the wrapped set like an array or access individual elements via the indexer ($(sel)[0] for example). More importantly, you can also apply jQuery functions against all the selected elements.

About returning nothing:

Does it always return an array? Does it return null?

You always get the same thing back, whether or not it has any contents is the question. Typically you can check this by using .val() (e.g. $('.myElem').val())

Nottingham

Great, thanks... this is very helpful. I didn't know that a user-defined object could at the same time be so "array-like" -- I guess that's the genius of jquery. – Antonetta

You're welcome - I also just edited and added the full link to Rick Strahl's article - it's a good read. – Nottingham

For the question that led me here, namely, how do you check whether anything was found, I went with $(query).length, which seems to do the trick. – Antonetta

what is an array like set....is it an array or an object or ?...can we be precise? – Tisman

Rick Strahl's article link is broken... his page is still there though. Will someone please replace this link? I am not able to find the original source of it. – Verdure

Answer 2

It doesn't return an array, it returns a jQuery object. The jQuery object is what contains all the special jQuery methods.

It never returns null, or another type. If one element is found, the jQuery object will have only one child. If no elements are found, the jQuery object will be empty.

Jugulate

Answer 3

As another answerer mentioned, it always returns the jQuery object.

This object always contains an array of elements (even if it is an empty array, or an array with just one object).

If you'd like to use the returned object "directly", as in, as a plain element, you can do one of the following:

$('selector')[0] // element
$('selector').get(0) // element
$('selector').length // number of elements in the array

Farther

Answer 4

The jQuery function (i.e. "$") always returns a jQuery object in every instance.

Poverty

@harpo: not at all; It's just that the objects in question are poorly named. "The jQuery Object", aka $ vs "a jQuery Object", aka a "wrapped set". – Risorgimento

Answer 5

From the jQuery documentation:

The jQuery object itself behaves much like an array; it has a length property and the elements in the object can be accessed by their numeric indices [0] to [length-1]. Note that a jQuery object is not actually a Javascript Array object, so it does not have all the methods of a true Array object such as join().

Inspect

Answer 6

The fact that $() always returns the jQuery function lets you chain jQuery function calls judiciously.

Poise

ask! $() does not return the jQuery function, (which is $ itself,) but returns a wrapped set, with all those helpful methods on it. – Risorgimento

Answer 7

Jquery selector mechnism

$("..") , the jquery selector, is used to select matched elements.

Return value

It always return an array-like jquery object, which has a length property,

Call method on returned jquery object

Methods of jquery could be called on the object, and apply to those selected elements,

Access original element by index

The selected elements, are store as property of the object, their property name are index numbers start from 0,
thus could be accessed by index, start from 0,
after get the original element, you can treat it as if get by document.getElementXxx().

Wrap an original element to a jquery object

After get the original element, you can wrap it to be a jquery object, by calling $(originalEle),
then you can call jquery methods on the wrapped object.

Pellegrini

Answer 8

According to firebug, it returns an array of objects that match to your selector. But this array is a jQuery object, that more methods than a simple Array.

Achaean

Answer 9

Their documentation lists a few of the core calls you can use with "$" and what they return

Coreycorf