Commonly Confused Bits Of jQuery

$('span#mySpan').parent().css('background', '#f90');
$('p').parent('div.large').css('background', '#f90');

The first line gives the parent of #mySpan. The second does the same for parents of all <p> tags, provided that the parent is a div and has the class large.

Tip: the ability to limit the reach of methods like the one in the second line is a common feature of jQuery. The majority of DOM manipulation methods allow you to specify a selector in this way, so it’s not unique to parent().

parents(selector)

This acts in much the same way as parent(), except that it is not restricted to just one level above the matched element(s). That is, it can return multiple ancestors. So, for example:

$('li.nav').parents('li'); //for each LI that has the class nav, go find all its parents/ancestors that are also LIs

This says that for each <li> that has the class nav, return all its parents/ancestors that are also <li>s. This could be useful in a multi-level navigation tree, like the following:

<ul id='nav'>
    <li>Link 1
        <ul>
            <li>Sub link 1.1</li>
            <li>Sub link 1.2</li>
            <li>Sub link 1.3</li>
        </ul>
    <li>Link 2
        <ul>
            <li>Sub link 2.1

            <li>Sub link 2.2

        </ul>
    </li>
</ul>

Imagine we wanted to color every third-generation <li> in that tree orange. Simple:

$('#nav li').each(function() {
    if ($(this).parents('#nav li').length == 2)
        $(this).css('color', '#f90');
});

This translates like so: for every <li> found in #nav (hence our each() loop), whether it’s a direct child or not, see how many <li> parents/ancestors are above it within #nav. If the number is two, then this <li> must be on level three, in which case color.

closest(selector)

This is a bit of a well-kept secret, but very useful. It works like parents(), except that it returns only one parent/ancestor. In my experience, you’ll normally want to check for the existence of one particular element in an element’s ancestry, not a whole bunch of them, so I tend to use this more than parents(). Say we wanted to know whether an element was a descendant of another, however deep in the family tree:

if ($('#element1').closest('#element2').length == 1)
    alert("yes - #element1 is a descendent of #element2!");
else
    alert("No - #element1 is not a descendent of #element2");

Tip: you can simulate closest() by using parents() and limiting it to one returned element.

$($('#element1').parents('#element2').get(0)).css('background', '#f90');

One quirk about closest() is that traversal starts from the element(s) matched by the selector, not from its parent. This means that if the selector that passed inside closest() matches the element(s) it is running on, it will return itself. For example:

$('div#div2').closest('div').css('background', '#f90');

This will turn #div2 itself orange, because closest() is looking for a <div>, and the nearest <div> to #div2 is itself.

2. .position() vs. .offset()

These two are both concerned with reading the position of an element — namely the first element returned by the selector. They both return an object containing two properties, left and top, but they differ in what the returned position is relative to.

position() calculates positioning relative to the offset parent — or, in more understandable terms, the nearest parent or ancestor of this element that has position: relative. If no such parent or ancestor is found, the position is calculated relative to the document (i.e. the top-left corner of the viewport).

offset(), in contrast, always calculates positioning relative to the document, regardless of the position attribute of the element’s parents and ancestors.

Consider the following two <div>s:

Querying (no pun intended) the offset() and position() of #innerDiv will return different results.

var position = $('#innerDiv').position();
var offset = $('#innerDiv').offset();
alert("Position: left = "+position.left+", top = "+position.top+"n"+
      "Offset: left = "+offset.left+" and top = "+offset.top
)

Try it yourself to see the results: click here.

3. .css(‘width’) and .css(‘height’) vs. .width() and .height()

These three, you won’t be shocked to learn, are concerned with calculating the dimensions of an element in pixels. They both return the offset dimensions, which are the genuine dimensions of the element no matter how stretched it is by its inner content.

They differ in the data types they return: css(‘width’) and css(‘height’) return dimensions as strings, with px appended to the end, while width() and height() return dimensions as integers.

There’s actually another little-known difference that concerns IE (quelle surprise!), and it’s why you should avoid the css(‘width’) and css(‘height’) route. It has to do with the fact that IE, when asked to read “computed” (i.e. not implicitly set) dimensions, unhelpfully returns auto. In jQuery core, width() and height() are based on the .offsetWidth and .offsetHeight properties resident in every element, which IE does read correctly.

But if you’re working on elements with dimensions implicitly set, you don’t need to worry about that. So, if you wanted to read the width of one element and set it on another element, you’d opt for css(‘width’), because the value returned comes ready appended with ‘px’.

But if you wanted to read an element’s width() with a view to performing a calculation on it, you’d be interested only in the figure; hence width() is better.

Note that each of these can simulate the other with the help of an extra line of JavaScript, like so:

var width = $('#someElement').width(); //returns integer
width = width+'px'; //now it's a string like css('width') returns
var width = $('#someElement').css('width'); //returns string
width = parseInt(width); //now it's an integer like width() returns

Lastly, width() and height() actually have another trick up their sleeves: they can return the dimensions of the window and document. If you try this using the css() method, you’ll get an error.

4. .click() (etc) vs. .bind() vs. .live() vs. .delegate

These are all concerned with binding events to elements. The differences lie in what elements they bind to and how much we can influence the event handler (or “callback”). If this sounds confusing, don’t worry. I’ll explain.

click() (etc)

It’s important to understand that bind() is the daddy of jQuery’s event-handling API. Most tutorials deal with events with simple-looking methods, such as click() and mouseover(), but behind the scenes these are just the lieutenants who report back to bind().

These lieutenants, or aliases, give you quick access to bind certain event types to the elements returned by the selector. They all take one argument: a callback function to be executed when the event fires. For example:

$('#table td ').click(function() {
    alert("The TD you clicked contains '"+$(this).text()+"'");
});

This simply says that whenever a <div> inside #table is clicked, alert its text content.

bind()

We can do the same thing with bind, like so:

$('#table td ').bind('click', function() {
    alert("The TD you clicked contains '"+$(this).text()+"'");
});

Note that this time, the event type is passed as the first argument to bind(), with the callback as the second argument. Why would you use bind() over the simpler alias functions?

Very often you wouldn’t. But bind() gives you more control over what happens in the event handler. It also allows you to bind more than one event at a time, by space-separating them as the first argument, like so:

$('#table td').bind('click contextmenu', function() {
    alert("The TD you clicked contains '"+$(this).text()+"'");
});

Now our event fires whether we’ve clicked the <td> with the left or right button. I also mentioned that bind() gives you more control over the event handler. How does that work? It does it by passing three arguments rather than two, with argument two being a data object containing properties readable to the callback, like so:

$('#table td').bind('click contextmenu', {message: 'hello!'}, function(e) {
    alert(e.data.message);
});

As you can see, we’re passing into our callback a set of variables for it to have access to, in our case the variable message.

You might wonder why we would do this. Why not just specify any variables we want outside the callback and have our callback read those? The answer has to do with scope and closures. When asked to read a variable, JavaScript starts in the immediate scope and works outwards (this is a fundamentally different behavior to languages such as PHP). Consider the following:

var message = 'you left clicked a TD';
$('#table td').bind('click', function(e) {
    alert(message);
});
var message = 'you right clicked a TD';
$('#table td').bind('contextmenu', function(e) {
    alert(message);
});

No matter whether we click the <td> with the left or right mouse button, we will be told it was the right one. This is because the variable message is read by the alert() at the time of the event firing, not at the time the event was bound.

If we give each event its own “version” of message at the time of binding the events, we solve this problem.

$('#table td').bind('click', {message: 'You left clicked a TD'}, function(e) {
    alert(e.data.message);
});
$('#table td').bind('contextmenu', {message: 'You right clicked a TD'}, function(e) {
    alert(e.data.message);
});

Events bound with bind() and with the alias methods (.mouseover(), etc) are unbound with the unbind() method.

live()

This works almost exactly the same as bind() but with one crucial difference: events are bound both to current and future elements — that is, any elements that do not currently exist but which may be DOM-scripted after the document is loaded.

Side note: DOM-scripting entails creating and manipulating elements in JavaScript. Ever notice in your Facebook profile that when you “add another employer” a field magically appears? That’s DOM-scripting, and while I won’t get into it here, it looks broadly like this:

var newDiv = document.createElement('div');
newDiv.appendChild(document.createTextNode('hello, world!'));
$(newDiv).css({width: 100, height: 100, background: '#f90'});
document.body.appendChild(newDiv);

delegate()

A shortfall of live() is that, unlike the vast majority of jQuery methods, it cannot be used in chaining. That is, it must be used directly on a selector, like so:

$('#myDiv a').live('mouseover', function() {
    alert('hello');
});

But not…

$('#myDiv').children('a').live('mouseover', function() {
    alert('hello');
});

… which will fail, as it will if you pass direct DOM elements, such as $(document.body).

delegate(), which was developed as part of jQuery 1.4.2, goes some way to solving this problem by accepting as its first argument a context within the selector. For example:

$('#myDiv').delegate('a', 'mouseover', function() {
    alert('hello');
});

Like live(), delegate() binds events both to current and future elements. Handlers are unbound via the undelegate() method.

Real-Life Example

For a real-life example, I want to stick with DOM-scripting, because this is an important part of any RIA (rich Internet application) built in JavaScript.

Let’s imagine a flight-booking application. The user is asked to supply the names of all passengers travelling. Entered passengers appear as new rows in a table, #passengersTable, with two columns: “Name” (containing a text field for the passenger) and “Delete” (containing a button to remove the passenger’s row).

To add a new passenger (i.e. row), the user clicks a button, #addPassenger:

$('#addPassenger').click(function() {
    var tr = document.createElement('tr');
    var td1 = document.createElement('td');
    var input = document.createElement('input');
    input.type = 'text';
    $(td1).append(input);
    var td2 = document.createElement('td');
    var button = document.createElement('button');
    button.type = 'button';
    $(button).text('delete');
    $(td2).append(button);
    $(tr).append(td1);
    $(tr).append(td2);
    $('#passengersTable tbody').append(tr);
});

Notice that the event is applied to #addPassenger with click(), not live(‘click’), because we know this button will exist from the beginning.

What about the event code for the “Delete” buttons to delete a passenger?

$('#passengersTable td button').live('click', function() {
    if (confirm("Are you sure you want to delete this passenger?"))
    $(this).closest('tr').remove();
});

Here, we apply the event with live() because the element to which it is being bound (i.e. the button) did not exist at runtime; it was DOM-scripted later in the code to add a passenger.

Handlers bound with live() are unbound with the die() method.

The convenience of live() comes at a price: one of its drawbacks is that you cannot pass an object of multiple event handlers to it. Only one handler.

5. .children() vs. .find()

Remember how the differences between parent(), parents() and closest() really boiled down to a question of reach? So it is here.

children()

This returns the immediate children of an element or elements returned by a selector. As with most jQuery DOM-traversal methods, it is optionally filtered with a selector. So, if we wanted to turn all <td>s orange in a table that contained the word “dog”, we could use this:

$('#table tr').children('td:contains(dog)').css('background', '#f90');

find()

This works very similar to children(), only it looks at both children and more distant descendants. It is also often a safer bet than children().

Say it’s your last day on a project. You need to write some code to hide all <tr>s that have the class hideMe. But some developers omit <tbody> from their table mark-up, so we need to cover all bases for the future. It would be risky to target the <tr>s like this…

$('#table tbody tr.hideMe').hide();

… because that would fail if there’s no <tbody>. Instead, we use find():

$('#table').find('tr.hideMe').hide();

This says that wherever you find a <tr> in #table with .hideMe, of whatever descendancy, hide it.

6. .not() vs. !.is() vs. :not()

As you’d expect from functions named “not” and “is,” these are opposites. But there’s more to it than that, and these two are not really equivalents.

.not()

not() returns elements that do not match its selector. For example:

$('p').not('.someclass').css('color', '#f90');

That turns all paragraphs that do not have the class someclass orange.

.is()

If, on the other hand, you want to target paragraphs that do have the class someclass, you could be forgiven for thinking that this would do it:

$('p').is('.someclass').css('color', '#f90');

In fact, this would cause an error, because is() does not return elements: it returns a boolean. It’s a testing function to see whether any of the chain elements match the selector.

So when is is useful? Well, it’s useful for querying elements about their properties. See the real-life example below.

:not()

:not() is the pseudo-selector equivalent of the method .not() It performs the same job; the only difference, as with all pseudo-selectors, is that you can use it in the middle of a selector string, and jQuery’s string parser will pick it up and act on it. The following example is equivalent to our .not() example above:

$('p:not(.someclass)').css('color', '#f90');

Real-Life Example

As we’ve seen, .is() is used to test, not filter, elements. Imagine we had the following sign-up form. Required fields have the class required.

<form id='myform' method='post' action='somewhere.htm'>
    <label>Forename *
    <input type='text' class='required' />
    <br />
    <label>Surname *
    <input type='text' class='required' />
    <br />
    <label>Phone number
    <input type='text' />
    <br />
    <label>Desired username *
    <input type='text' class='required' />
    <br />
    <input type='submit' value='GO' />
</form>

When submitted, our script should check that no required fields were left blank. If they were, the user should be notified and the submission halted.

$('#myform').submit(function() {
    if ($(this).find('input').is('.required[value=]')) {
        alert('Required fields were left blank! Please correct.');
        return false; //cancel submit event
    }
});

Here we’re not interested in returning elements to manipulate them, but rather just in querying their existence. Our is() part of the chain merely checks for the existence of fields within #myform that match its selector. It returns true if it finds any, which means required fields were left blank.

7. .filter() vs. .each()

These two are concerned with iteratively visiting each element returned by a selector and doing something to it.

.each()

each() loops over the elements, but it can be used in two ways. The first and most common involves passing a callback function as its only argument, which is also used to act on each element in succession. For example:

$('p').each(function() {
    alert($(this).text());
});

This visits every <p> in our document and alerts out its contents.

What about the event code for the “Delete” buttons to delete a passenger?

$('#passengersTable td button').live('click', function() {
    if (confirm("Are you sure you want to delete this passenger?"))
    $(this).closest('tr').remove();
});

Here, we apply the event with live() because the element to which it is being bound (i.e. the button) did not exist at runtime; it was DOM-scripted later in the code to add a passenger.

Handlers bound with live() are unbound with the die() method.

The convenience of live() comes at a price: one of its drawbacks is that you cannot pass an object of multiple event handlers to it. Only one handler.

5. .children() vs. .find()

Remember how the differences between parent(), parents() and closest() really boiled down to a question of reach? So it is here.

children()

This returns the immediate children of an element or elements returned by a selector. As with most jQuery DOM-traversal methods, it is optionally filtered with a selector. So, if we wanted to turn all <td>s orange in a table that contained the word “dog”, we could use this:

$('#table tr').children('td:contains(dog)').css('background', '#f90');

find()

This works very similar to children(), only it looks at both children and more distant descendants. It is also often a safer bet than children().

Say it’s your last day on a project. You need to write some code to hide all <tr>s that have the class hideMe. But some developers omit <tbody> from their table mark-up, so we need to cover all bases for the future. It would be risky to target the <tr>s like this…

$('#table tbody tr.hideMe').hide();

… because that would fail if there’s no <tbody>. Instead, we use find():

$('#table').find('tr.hideMe').hide();

This says that wherever you find a <tr> in #table with .hideMe, of whatever descendancy, hide it.

6. .not() vs. !.is() vs. :not()

As you’d expect from functions named “not” and “is,” these are opposites. But there’s more to it than that, and these two are not really equivalents.

.not()

not() returns elements that do not match its selector. For example:

$('p').not('.someclass').css('color', '#f90');

That turns all paragraphs that do not have the class someclass orange.

.is()

If, on the other hand, you want to target paragraphs that do have the class someclass, you could be forgiven for thinking that this would do it:

$('p').is('.someclass').css('color', '#f90');

In fact, this would cause an error, because is() does not return elements: it returns a boolean. It’s a testing function to see whether any of the chain elements match the selector.

So when is is useful? Well, it’s useful for querying elements about their properties. See the real-life example below.

:not()

:not() is the pseudo-selector equivalent of the method .not() It performs the same job; the only difference, as with all pseudo-selectors, is that you can use it in the middle of a selector string, and jQuery’s string parser will pick it up and act on it. The following example is equivalent to our .not() example above:

$('p:not(.someclass)').css('color', '#f90');

Real-Life Example

As we’ve seen, .is() is used to test, not filter, elements. Imagine we had the following sign-up form. Required fields have the class required.

<form id='myform' method='post' action='somewhere.htm'>
    <label>Forename *
    <input type='text' class='required' />
    <br />
    <label>Surname *
    <input type='text' class='required' />
    <br />
    <label>Phone number
    <input type='text' />
    <br />
    <label>Desired username *
    <input type='text' class='required' />
    <br />
    <input type='submit' value='GO' />
</form>

When submitted, our script should check that no required fields were left blank. If they were, the user should be notified and the submission halted.

$('#myform').submit(function() {
    if ($(this).find('input').is('.required[value=]')) {
        alert('Required fields were left blank! Please correct.');
        return false; //cancel submit event
    }
});

Here we’re not interested in returning elements to manipulate them, but rather just in querying their existence. Our is() part of the chain merely checks for the existence of fields within #myform that match its selector. It returns true if it finds any, which means required fields were left blank.

7. .filter() vs. .each()

These two are concerned with iteratively visiting each element returned by a selector and doing something to it.

.each()

each() loops over the elements, but it can be used in two ways. The first and most common involves passing a callback function as its only argument, which is also used to act on each element in succession. For example:

$('p').each(function() {
    alert($(this).text());
});

This visits every <p> in our document and alerts out its contents.

But each() is more than just a method for running on selectors: it can also be used to handle arrays and array-like objects. If you know PHP, think foreach(). It can do this either as a method or as a core function of jQuery. For example…

var myarray = ['one', 'two'];
$.each(myarray, function(key, val) {
    alert('The value at key '+key+' is '+val);
});

… is the same as:

var myarray = ['one', 'two'];
$(myarray).each(function(key, val) {
    alert('The value at key '+key+' is '+val);
});

That is, for each element in myarray, in our callback function its key and value will be available to read via the key and val variables, respectively. The first of the two examples is the better choice, since it makes little sense to pass an array as a jQuery selector, even if it works.

One of the great things about this is that you can also iterate over objects — but only in the first way (i.e. $.each).

jQuery is known as a DOM-manipulation and effects framework, quite different in focus from other frameworks such as MooTools, but each() is an example of its occasional foray into extending JavaScript’s native API.

.filter()

filter(), like each(), visits each element in the chain, but this time to remove it from the chain if it doesn’t pass a certain test.

The most common application of filter() is to pass it a selector string, just like you would specify at the start of a chain. So, the following are equivalents:

$('p.someClass').css('color', '#f90');
$('p').filter('.someclass').css('color', '#f90');

In which case, why would you use the second example? The answer is, sometimes you want to affect element sets that you cannot (or don’t want to) change. For example:

var elements = $('#someElement div ul li a');
//hundreds of lines later...
elements.filter('.someclass').css('color', '#f90');

elements was set long ago, so we cannot — indeed may not wish to — change the elements that return, but we might later want to filter them.

filter() really comes into its own, though, when you pass it a filter function to which each element in the chain in turn is passed. Whether the function returns true or false determines whether the element stays in the chain. For example:

$('p').filter(function() {
    return $(this).text().indexOf('hello') != -1;
}).css('color', '#f90')

Here, for each <p> found in the document, if it contains the string hello, turn it orange. Otherwise, don’t affect it.

We saw above how is(), despite its name, was not the equivalent of not(), as you might expect. Rather, use filter() or has() as the positive equivalent of not().

Note also that unlike each(), filter() cannot be used on arrays and objects.

Real-Life Example

You might be looking at the example above, where we turned <p>s starting with hello orange, and thinking, “But we could do that more simply.” You’d be right:

$('p:contains(hello)').css('color', '#f90')

For such a simple condition (i.e. contains hello), that’s fine. But filter() is all about letting us perform more complex or long-winded evaluations before deciding whether an element can stay in our chain.

Imagine we had a table of CD products with four columns: artist, title, genre and price. Using some controls at the top of the page, the user stipulates that they do not want to see products for which the genre is “Country” or the price is above $10. These are two filter conditions, so we need a filter function:

$('#productsTable tbody tr').filter(function() {
    var genre = $(this).children('td:nth-child(3)').text();
    var price = $(this).children('td:last').text().replace(/[^d.]+/g, '');
    return genre.toLowerCase() == 'country' || parseInt(price) >= 10;
}).hide();

So, for each <tr> inside the table, we evaluate columns 3 and 4 (genre and price), respectively. We know the table has four columns, so we can target column 4 with the :last pseudo-selector. For each product looked at, we assign the genre and price to their own variables, just to keep things tidy.

For the price, we replace any characters that might prevent us from using the value for mathematical calculation. If the column contained the value $14.99 and we tried to compute that by seeing whether it matched our condition of being below $10, we would be told that it’s not a number, because it contains the $ sign. Hence we strip away everything that is not number or dot.

Lastly, we return true (meaning the row will be hidden) if either of our conditions are met (i.e. the genre is country or the price is $10 or more).

filter()

8. .merge() vs. .extend()

Let’s finish with a foray into more advanced JavaScript and jQuery. We’ve looked at positioning, DOM manipulation and other common issues, but jQuery also provides some utilities for dealing with the native parts of JavaScript. This is not its main focus, mind you; libraries such as MooTools exist for this purpose.

.merge()

merge() allows you to merge the contents of two arrays into the first array. This entails permanent change for the first array. It does not make a new array; values from the second array are appended to the first:

var arr1 = ['one', 'two'];
var arr2 = ['three', 'four'];
$.merge(arr1, arr2);

After this code runs, the arr1 will contain four elements, namely one, two, three, four. arr2 is unchanged. (If you’re familiar with PHP, this function is equivalent to array_merge().)

.extend()

extend() does a similar thing, but for objects:

var obj1 = {one: 'un', two: 'deux'}
var obj2 = {three: 'trois', four: 'quatre'}
$.extend(obj1, obj2);

extend() has a little more power to it. For one thing, you can merge more than two objects — you can pass as many as you like. For another, it can merge recursively. That is, if properties of objects are themselves objects, you can ensure that they are merged, too. To do this, pass true as the first argument:

var obj1 = {one: 'un', two: 'deux'}
var obj2 = {three: 'trois', four: 'quatre', some_others: {five: 'cinq', six: 'six', seven: 'sept'}}
$.extend(true, obj1, obj2);

Covering everything about the behaviour of JavaScript objects (and how merge interacts with them) is beyond the scope of this article, but you can read more here.

The difference between merge() and extend() in jQuery is not the same as it is in MooTools. One is used to amend an existing object, the other creates a new copy.

There You Have It

We’ve seen some similarities, but more often than not intricate (and occasionally major) differences. jQuery is not a language, but it deserves to be learned as one, and by learning it you will make better decisions about what methods to use in what situation.

It should also be said that this article does not aim to be an exhaustive guide to all jQuery functions available for every situation. For DOM traversal, for example, there’s also nextUntil() and parentsUntil().

While there are strict rules these days for writing semantic and SEO-compliant mark-up, JavaScript is still very much the playground of the developer. No one will demand that you use click() instead of bind(), but that’s not to say one isn’t a better choice than the other. It’s all about the situation.

Related Posts

You may be interested in the following related posts:

• Seven JavaScript Things I Wish I Knew Much Earlier In My Career
• The Seven Deadly Sins Of JavaScript Implementation
• Developing Sites With AJAX: Design Challenges and Common Issues

We appreciate the feedback of our Twitter followers who reviewed the article before it was published.