jQuery’s .animate() method, and the shorthand methods that use it, are fantastic tools to create animations. Creating animations that link together to achieve a particular effect, and do something specific at the end of the animation, can be a painful, messy task. Luckily, we have .queue() for mashing animations together.

But what happens when you want to bridge the gap between ajax requests and animating? When you want to queue a bunch of animations, get data from the server, and handle it all at once, without a crap-load of nested callbacks? That’s when jQuery.Deferred() puts on its cape, tightens its utility belt, and saves the day.

Disclaimer

I should note, however, that this is more-or-less giving an example of a pending feature request to add deferreds support in $.fn.animate. If the feature request is accepted and landed, it won’t show up until version 1.6 of jQuery. The principles, however, speak to jQuery’s flexibility and how to forge its multitude of great features into an even stronger tool.

While this works, its behavior isn’t consistent with that of jQuery. Namely, the new custom animate method doesn’t return ‘this’, but a Deferred object. However, that’s kind of the point of $.sub(): allowing you to copy the jQuery object and have your way with it. So, do try this at home – just don’t threaten my life if your site explodes.

The Demo

The following demo is a basic, distilled use-case for this kind of situation. Clicking the button opens a div that contains a loading message. While it’s opening, it is also querying the server for information to populate the box. Once both have finished, the loading div is hidden and the box with the retrieved data remains.

Modifying .animate()

Here is the code driving the change to .animate()

While the comments explain just about everything, be sure to read up on $.sub() if you haven’t already. The new animate function on my$ simulates the method signature of the function, $.fn.animate, it’s attempting to replace. In short, speed, easing, and callback are forced into an options object — the same as if the second parameter was an object.

The deferred is created, a copy of the complete callback, and the count of how many items. Why? We want to fire the resolve() function on the deferred once all of the animations have finished. The complete() callback is replaced with a wrapper function that calls the original callback and decrements and checks the count. When the count reaches zero, all items have been animated and it’s safe to fire the resolve() function.

The untouched, standard version of $.fn.animate is called with the same ‘this’, properties, and the modified options object with the new complete wrapper function.

Returned is the promise, dfd.promise(), that lets $.when() do its awesomeness.

Putting it into action

If you haven’t familiarized yourself with deferreds, I highly recommend you read Eric Hynds’ fantastic article about it.

Because the new animate function was created on my$, the copy of jQuery made using $.sub(), .hide(), .slideUp(), and other helper functions that use the custom .animate() function.

When the animation and ajax request both succeed, thus resolving the promise as true, the first callback function of $.then() is called. However, if one of them fails, the second will be called. You can re-run the demo (by clicking on the run button) and opt to fail the ajax request to see the second function get run. The .then() function is a handy mix of .done() and .fail(), which are useful if you want to provide multiple callbacks.

Summary

While I highly doubt this will be the solution to using deferreds with .animate(), I’m confident it’ll get the ball rolling. Too, it covers some other topics, such as $.sub(), deferreds, and wrapping functions with alternate behavior, that hopefully you found interesting.

The HTML I tested against was a page of 100 div tags with a class and some content, I cached the selector $('div') to use with each method to exclude the time needed to find all the div elements on the page from the test. I used jQuery 1.4.2 for the testing, but keep in mind that the algorithms behind the method calls can change dramatically from version to version. What is true for 1.4.2 is not necessarily true for other versions of the library.

The methods I tested were .toggle(), .show() & .hide(), .css({'display':'none'}) & .css({'display':'block'}), and .addClass('hide') & .removeClass('hide'). I also tested modifying an attribute of a <style> element.

.show() & .hide()

These were, in fact, comparatively slow methods of hiding DOM elements across all browsers. One of the main reasons is that .hide() has to save the notion of what the display attribute was before, so that .show() can restore it. It does this using the .data() jQuery method, storing that information on the DOM element. In order to do so, .hide() loops through every element twice: once to save the current display value, and then once to update the display style to none. According to a comment in the source, this prevents the browser from reflowing with every loop. The .hide() method also checks to see if you pass in a parameter to animate the hiding with an effect. Even passing in a 0 dramatically slows down the performance. Performance was slowest on the first call to .hide(); subsequent calls were faster.

Browser      hide/show
FF3.6 -         29ms / 10ms 
Safari 4.05 -   6ms / 1ms
Opera 10.10 -   9ms / 1ms
Chrome 5.0.3 -  5ms / 1ms
IE 6.0  -       31ms / 16ms 
IE 7.0  -       15ms / 16ms 

.toggle()

This was, by far, the slowest method of hiding all of the div elements. It iterates through every element returned by the selector, checks to see if the element is currently visible, and then calls .hide() on visible elements one at a time and .show() on hidden ones one at a time. It also has to check to see if you are passing in a boolean to force everything to .show() or .hide() and check to see if you are passing in functions to toggle instead of toggling visibility. There seems to be some opportunity for optimization of this function, as one could select all of the hidden elements of the selector and call .show() on them all at once and then select the remaining elements in the selector and call .hide() on them at the same time. If you are so inclined, I encourage you to check out the source and see if you can eke out any performance gains.

Browser      hide/show
FF3.6 -         80ms / 59ms 
Safari 4.05 -   24ms / 30ms 
Opera 10.10 -   67ms / 201ms
Chrome 5.0.3 -  55ms / 20ms 
IE 6.0  -       296ms / 78ms 
IE 7.0  -       328ms / 47ms 

.addClass() & .removeClass()

These are pretty snappy methods of hiding/showing elements of the DOM, twice as fast as .show() & .hide() in Firefox and three times as fast in Safari. The differences in IE 6, IE7, Chrome, and Opera are negligible. It's also worth noting that with 100 DOM nodes, we're talking a total difference of 18ms in Firefox and 4ms in Safari. The speed difference will only be relevant for very large selections. Adding and removing a class requires a bit more management on your part, since you have to create the class that has a display of none and then have to keep track of CSS priority to make sure your elements get hidden. The way jQuery adds and removes a class is through string manipulation, so I imagine that as the number of classes on an element grows, this method will get slower, but that is untested speculation on my part.

Browser      hide/show
FF3.6   -       11ms / 11ms 
Safari 4.05 -   2ms / 2ms
Opera 10.10 -   6ms / 3ms
Chrome 5.0.3 -  3ms / 1ms
IE 6.0  -       47ms / 32ms
IE 7.0  -       15ms / 16ms

.css({'display':'none'}) & .css({'display':'block'});

These methods were very snappy. They showed an improvement over .addClass() and .removeClass() in Opera and IE 6/7 and about the same in other browsers. They work great if you know the current display style of all the elements you are changing, or at least have not changed the display style inline. If you have changed the display style inline, then you will need to make sure you set the correct value when you make the element visible again. If you are just using the elements' default display value or set the display value in the css, then you can just remove the style like so, .css({'display':''}), and it will revert to whatever value it has in the css or by default. As a library, jQuery can't assume that the display element wasn't set inline, so it has to manually keep track of it. That is the main slowness you can avoid since you know you won't be setting the display inline.

Browser      hide/show
FF3.6   -       14ms / 12ms
Safari 4.05 -   2ms / 1ms
Opera 10.10 -   2ms / 2ms
Chrome 5.0.3 -  2ms / 1ms
IE 6.0  -       16ms / 16ms
IE 7.0  -       0ms / 0ms  // The usual caveat about inaccuracy of IE clocks applies.

Disabling stylesheets

For fun, I thought, "What if instead of manipulating every DOM node and changing things, we just futz with the stylesheet?" Could there be speed improvements there? I mean, the methods benchmarked above are plenty fast for everyday use, but what if I had 10,000 nodes on a page I wanted to show and hide? It would be slow just selecting them all. But, if I could manipulate the stylesheet, I could avoid the entire overhead. Let me just tell you that way is fraught with peril.

There are, of course, cross browser issues when manipulating stylesheets, since jQuery doesn't abstract them away for you. First, I tried to see if I could append a style tag with the css class as a string using jQuery, but got inconsistent results across browsers. Then I tried creating the stylesheet node and class using JavaScript, but there were different APIs and it ended up being too slow to justify. So finally, forgoing an attempt to do this in a programmatic way, I ended up just writing a style tag with a class in the head of the document. It's far too slow to create the stylesheet programmatically, but if it's already there then it is trivial to give it an ID and use its disabled attribute.

Then in javascript…

and BAM, you just displayed all of your elements with a class of “special_hide”. To hide them all again, just do…

and they are now all hidden. The total javascript processing time was 0-1ms across all browsers. The only javascript you are doing is changing an attribute. Of course, there is still the time the browser takes to reflow and repaint the page, but you've virtually eliminated all the javascript processing time. If you call any of the other methods, .toggle(), .hide(), or .css(), this method will stop working on those elements because they set the css style inline, which has higher precedence than other css. To make this method work again, simply do a .css(‘display’, ‘’) to remove the inline style. This method also requires the most work on your part, because you have to define the class and give the class to all of the elements on the page you want to show/hide at the same time, but if you are dealing with extremely large sets, this might just be worth it.

To recap, here is a list of methods to change the display of elements in order from fastest to slowest:

1. Enabling/Disabling a stylesheet
2. .css('display', ''), .css('display', 'none')
3. .addClass(), .removeClass()
4. .show(), .hide()
5. .toggle()

Also note that for the majority of use cases, all of these methods are plenty fast to use. When you start having to manipulate large jQuery collections, .show() and .hide() might become too slow in IE, and you might need to bump up to .addClass() or .removeClass(). Enabling/disabling of stylesheets would only be necessary in the most extreme cases, but if things are hiding to slowly for you, you might want to give it a try.

Quick Review

In my last three tutorials, I discussed how to put together a very simple tooltip, and I introduced a different feature or concept in each one. In an effort to continue in the spirit of simplicity, I will refrain from repeating the explanations of previous posts and instead simply direct your attention to them before we begin:

• Simple Tooltip for Huge Number of Elements
• Binding Multiple Events to Reduce Redundancy with Event Delegation Tooltips
• Using setTimeout to Delay Showing Event Delegation Tooltips

Setup

Now I'd like to round off this series with a little exploration of one way to keep the tooltip within view when it might otherwise get clipped to the right or the bottom of the viewable area.

As with the previous tooltip tutorials, I start by setting a few variables:

The first line creates the tooltip container, hides it, appends it to the body, and stores a reference to it for later use. The next line is more for convenience than anything else (though it might provide nominal performance benefit), since I'll be calling jQuery methods on the window object a few times. The third line will be used as a reference to a setTimeout function for delaying the tooltip's visibility.

Position the Tip

Okay. So far, so boring. But here is where things start getting fun. I have a few more pieces I want to store and retrieve, but since they're all related, I figured it would be nice to have them be properties of a single tip object:

Since the position needs to be calculated each time the tooltip is displayed, I've made position a function—in other words, a method of the tip object. This is the part that does the hard work of figuring out where exactly to put the tooltip and whether or not to "flip" it above or to the left of the mouse position. Because this method is going to be called repeatedly as the mouse moves over a link, I wanted to make it as bare-bones as possible. I defined two objects. The first one contains the x and y mouse coordinates. The other contains two sets of numbers: (x) the inner width of the browser window and outer width of the tooltip, and (y) the distance from the top of the document to the bottom edge of the viewable area and the outer height of the tooltip.

Notice that the properties of the dimensions object have the same names as the properties of the positions object. I did that so I could easily loop through the properties of one and use the same loop variable for both, as shown in lines 18-26 above. Within that little loop, I'm testing to see if the tooltip, plus the mouse position, plus our user-defined "offset," is greater than the window dimension—on the x axis and then on the y. If it is, I subtract the tooltip's dimension and its offset from the mouse position; if not, I just add the offset to the mouse position.

Finally, I set the top and left style properties of the tooltip with the appropriate coordinates. I suppose it would have been cool to name the properties of my two objects "left" and "top". That way, I could have written $liveTip.css(positions). But, x and y make more sense to me as I read them, so I figured it would be worth a few extra bytes to help me remember what I was doing here when I look back at the script later on.

Wire it up

Now that the tooltip positioning is taken care of, it's time to hook it up to some events. If you read Binding Multiple Events to Reduce Redundancy with Event Delegation Tooltips, you may remember that I used the .bind() method and passed in three events: mouseover, mouseout, and mousemove. That seemed to work fine, but now that jQuery 1.4.2 has provided us with the more convenient .delegate() method, we can use that one instead. Jordan Boesch recently wrote a nice introductory article on Using Delegate and Undelegate in jQuery, so check that out if you're uncertain about what the method does. One thing I'd like to note about it, though, is that it's currently the only jQuery method (of its kind) that doesn't map the this keyword in the callback function to the current element within the matched set. In the code below, for example, the callback function for other methods would map this to the "#mytable" element; for .delegate(), the function maps to its first argument, "a" — when it is within "#mytable" and when it or one of its ancestors is the event.target element. I hope this little .delegate() excursion didn't confuse matters. Suffice it to say that the method allows us to use this for the link we want to act on, instead of going through the rigamarole of checking for the event target ourselves as I did in my previous tooltip articles.

Since a lot of what's going on in this code snippet has already been discussed in my previous posts, I'll just mention a couple things.

The tip positioning occurs in line 13, triggered by the mouseover event, and in line 34, triggered by mousemove. It only gets triggered in the mousemove, however, if the mouse has been over the link for the time specified in tip.delay for the setTimeout. That's where the link's "tipActive" data attribute is set.

This time around, I also added a little fade effect to show the tooltip. As a safeguard, I hide the tooltip and reset its opacity to 0 (using .fadeout() with a 0ms duration) before fading it in, because jQuery will only fade in elements if they are hidden to begin with. This extra step is only necessary if the fade-in duration is greater than tip.delay.

Conclusion

So that wraps up this tooltip series. As always, if you see something that I could do better, please leave a comment. I always appreciate learning better ways of plying the craft. And if you have any questions about what's going on in the code, please point out what you'd like me to clarify.

To see this one in action, visit the Flip Tip demo page. You can also look at the complete JavaScript file or download a zip of both the HTML and JavaScript.

The Styles

For the navigation items, I used a simple unordered list wrapped in a <div class="nav">. While the HTML structure is straightforward, the CSS is a little tricky, so I'll detail it here:

Most of the relevant CSS here has to do with positioning the nav items. I set the top <ul>'s left margin to 75 pixels less than the wrapper's width so that the top-level links appear on the right side. The 1600px width for the <ul> gives the floated list items ample room to line up horizontally next to each other.

The wrapper's overflow declaration is significant, as it hides the list items when they're sticking out to the right, but the rest is "window dressing."

Sliding the Nav

With the nav looking the way I want it at its initial state, it's time to make it do something. I'll start with a simple setup, having each "tab" (top-level item) slide to the left on the first click to reveal its sub-nav items, and slide back to its initial position when it's clicked a second time.

For this basic behavior, everything can be done inside a click handler for the top-level links. Note: Since I'm using multiple navs for this tutorial, each with its own set of behavior, I'll be referring to them by ID, unlike in the CSS snippet above, where everything is styled by class. There is nothing special about the selectors or their naming here. Name your own elements and select them however you want.

The first thing to do is set a few variables. The $parentItem variable is the <li> parent of the clicked link. The slideAmt is the width of the nested <ul>, which is the next sibling of the link. And direction will eventually determine whether the parent <li> should be slid to the left or to the right.

Notice the use of $(this). Inside the click handler, this refers to the clicked DOM element. By wrapping this in $(), we can call jQuery methods on it.

To get the sliding motion to occur, we can animate either the left property or the marginLeft property. Here, I'll animate marginLeft. So, the next thing to do is determine the direction of the animation based on the current value of marginLeft: If it's less than 0, direction is set to "+=", which increases it (back to 0); otherwise, direction is set to "-=". At the same time, an "expanded" class will be toggled so that the arrow background image can change directions.

Finally, we do the animation, plugging in the direction and slideAmt variables. The return false; line stops the default click action from occurring. Here is the finished code for the basic implementation:

Give it a try:

One at a Time

That's all well and good, but I don't really care for having more than one row of items expanded at a time. A couple simple modifications will fix that for us:

The links are stored in a variable first thing here. Whenever a link is clicked, all links have the "expanded" class removed. Of course, only one, at most, will have that class, but I'm lazy and it's easier to tell all of the links to remove the class than it is to hunt links that have the class first.

The same check is performed to set the direction of the animation. If the clicked link's parent <li> is going to be slid to the left, the link will also get the "expanded" class.

Finally, the clicked link's parent is animated in the direction and number of pixels specified by the variables. But here's the twist: all of that parent's siblings have their marginLeft property animated to 0. Again, I'm taking the lazy route, animating all of the siblings, even though one or none of them will need it.

Here's a demo of the "one at a time" version:

Auto-Collapse

Now that the expanding and collapsing are happening the way I like it, I'll add one more little touch. If the user's mouse leaves the containing <div class="tab-nav">, and stays out for a full second, any expanded list will collapse.

Line 2 declares a variable that will be used for the setTimeout(), which you can see tucked inside the .mouseleave() method near the bottom of the code. The setTimeout() function has two arguments: the first is an anonymous function that contains code for triggering the collapse of the list items, and the second is the number of milliseconds to wait (1,000 milliseconds) before the first argument (the anonymous function) is executed. The clearTimeout() inside the .mouseenter() method does what its name suggests: it clears the timeout. If the user mouses out of the nav area but then mouses back in before the 1000 milliseconds are up, the timer is stopped and the function will not be executed.

Note: The mouseenter(fn) and mouseleave(fn) shorthand methods are available as of jQuery 1.3. If you're still using jQuery 1.2.6, you can use .bind('mouseenter', fn) and .bind('mouseleave', fn) instead. Or, with just about any version of jQuery, you can use .hover(fn, fn).

Here is the final demo:

There are many ways to do this sort of thing. Just tweak the CSS or change the animation for a completely different experience.

Reverse the Slide Direction

With the built-in slide methods, elements are shown by sliding them down and into view. But what if we want to slide something from the bottom up and into view? The trick here is to use some judicious CSS. Let's start with a simple HTML structure:

To get the inner div to slide up, we'll anchor its bottom edge to the bottom of the bottom of the nearest positioned ancestor (in this case, the #slidebottom div):

Other properties such as width, padding, margin, and background-color have been set for these elements, but only the essential properties for modifying the slide behavior are shown above.

Note: I'll be using the term positioned to refer to elements that have the CSS position property set to something other than "static." Both divs in this example are positioned — one absolutely and the other relatively.

Now, we can write the jQuery the same way we would with a traditional slide effect:

Try it out:

Horizontal Slides

Animate Width

We can also slide elements to the left and right. The simplest way is to animate the element's width property.

In this case it's not necessary for the sliding element to be positioned.

While animating the width is fine for what it is, I'm not crazy about how the text wraps as the width decreases. One way to avoid the wrapping is to add a CSS declaration such as white-space: nowrap;, but that would mess up the appearance of an element with a lot of text—one in which we would expect to see text wrapping when it is at full length.

Animate Left

Another way to avoid the text-wrap issue is to animate the element's left property. Here, it's important once again to make sure that the element is positioned. After all, we can't move an element if it's static.

With this animation, we need to calculate how far to move the element. The following code rests on two assumptions: (1) the sliding element has an outerWidth() that is equal to or greater than its parent element's width, and (2) the sliding element is initially set to left: 0;. You may have to adjust your code if either one of these assumptions doesn't hold in your situation.

Lines 5 through 7 use a "ternary" operator that basically says, "If the left css property equals 0, move the element to the left as many pixels as it is wide (including padding and border); if not, move it back to 0."

Also, if we want the element to be hidden when it slides to the left, we need to add overflow: hidden; to its parent element.

Animate Left Margin

Finally, we can achieve the same effect as the left animation by animating the marginLeft property. In this case, we still need overflow: hidden; on the parent element, but the sliding element does not need to be positioned.

For the sake of variety, we're sliding this one to the right.

With a couple little tweaks, these horizontal slides can be used for a horizontal accordion.

Further Resources

• To learn about adding easing effects to your slides, check out Brandon Aaron's Quick Tip: Add Easing to Your Animations.
• To convert any of these slides into a plugin for convenient reuse, see Simple Effects Plugins.
• For a whole bunch of ready-made slides and other effects, take a look at jQuery UI.

The jQuery easing plugin offers 30 different easing methods, courtesy of Robert Penner's easing equations. Let's check some of them out.

Easing can only be applied when using the .animate() method. The effects helper methods like .show('fast'), .toggle('fast'), fadeIn('fast'), and so on all just use the default easing, "swing."

There are two ways to use easing with the .animate() method. For example, let's say we want to animate the opacity of a particular div. The first way to call .animate() is like this:

The second way is very similar and might even look the same at first glance.

The difference is that the second method signature takes only two arguments: the properties we are animating and an object literal of settings/options. The first method signature separates out the settings/options into individual arguments.

jQuery Easing Plugin

Finally, let's look at a few of the 30 easing methods provided by the easing plugin.

Ease Out Bounce

Ease Out Elastic

Ease Out Back

jQuery UI Easing

jQuery UI includes the easing plugin as part of its Effects Core. It also extends the effects helper methods to support the use of easing and even other types of effects. You can find the documentation for jQuery UI Effects here.

The natural queuing of animations/effects by jQuery makes the typical animation super easy to code and move on to more important tasks. However, sometimes the animation queue just gets in the way.

Here is an example of a navigation that has some effects applied to it via jQuery. Mouse back and forth over the links to see how the animations build up.

• Menu Item One
• Menu Item Two
• Menu Item Three
• Menu Item Four
• Menu Item Five

Here is the JavaScript that does the effect for the menu:

Now let's look at how we can prevent this undesirable behavior. Ready? Simply call the .stop() method before animating again. Here is the updated JavaScript that fixes the animation queue buildup by using the .stop() method.

Here is the navigation again, using the above JavaScript.

• Menu Item One
• Menu Item Two
• Menu Item Three
• Menu Item Four
• Menu Item Five

As you can see, the animation is no longer queued up by moving your mouse back and forth over the menu items.

You can even get bonus points for implementing something like the hoverIntent plugin that can add a slight delay before running the animation. Doing so makes sure the animation plays only if the user actually places the mouse on the element.

For more information about the .stop() method, visit the jQuery documentation page. To see a real-world example of the .stop() method in action, using its two arguments — clearQueue and goToEnd — check out the script Karl Swedberg put together at Little Orange Star.

Update: This article has been translated into Belorussian.

All of these methods have optional speed, easing, and callback arguments — although a couple are special cases. The .show() and .hide() methods, when used without a speed, will immediately show and hide the matched set of elements with no animation. When the speed argument is included, the matched elements are shown and hidden gradually by animating their height, width, and opacity simultaneously. The .toggle() method shares its name with a method that takes two arguments that alternate being triggered. All of the other effect methods have a default speed of 400ms.

The Flexible .animate()

jQuery internally uses another method, .animate(), to define these shorthand effect methods, and it makes .animate() available to us to do the same. So, let's create our own method that we can use the same way we would use, for example, .slideToggle().

Custom Animation Methods

Someone on the jQuery discussion list recently asked if there was a .fadeToggle() effect in jQuery. In my reply, I admitted that there wasn't one, but suggested that it wouldn't be too hard to create using .animate(). We just attach .fadeToggle to jQuery.fn and pass in the speed, easing, and callback arguments. Then, we return this.animate() with the effect we want, along with those same arguments:

Try it out:

To create a method that toggles a fade and a slide at the same time, all we need to do is repeat the process, adding a "height" parameter:

Give this one a try:

Blind Toggle

Let's try one more — a "blind" effect. Instead of changing the height of the element, as we do with a "slide" animation, we're going to move the entire element up and down.

The plugin itself will still be fairly rudimentary, but we'll need to set up some CSS to get it to work correctly. Here is the CSS:

Notice that we have two "boxes" styled here. The first one will be in the markup itself, but the second one, since it's only being used to help with the effect, will be created by our script. The important properties here are #box-outer's overflow: hidden and height: 120px. The hidden overflow will allow #box to seemingly disappear as it moves up, while the height (which is #box's height plus its top and bottom padding) will keep the rest of the page from shifting along with the box.

While relatively simple, there are a couple things here that might be confusing to jQuery/JavaScript beginners. The first line inside the function declares a variable for the height of this, plus the top and bottom padding ("this" here refers to whatever is matched by the selector in the script that uses the plugin). The parseInt() JavaScript function function looks at a string from left to right until it encounters a non-numeric character. The string of digits up to that character is converted into an integer, stripping off the trailing non-numeric character. So, "10px" becomes 10.

The line that follows animates the marginTop property. It uses a ternary (conditional) operator to test if marginTop is less than zero. If it is, the element's marginTop property animates to 0; if not, it animates to negative the value stored in the h variable.

Finally, we're ready to put this plugin to use:

Line 2 "caches" our selector, since we're using it more than once. Then we wrap a div around the "#box" div and bind a click handler to a button. Let's see how this one looks:

So, now we have three simple effects methods that we apply to our sites for a little extra flair.

jQuery UI

For really cool effects, check out the demos of jQuery UI effects.

Answer: The animated scrolling script hijacks links that look like this: <a href="#">. A couple people confirmed in the comments that the script needed a bit more work, so I figured we could take one more pass at it.

By the way, even though we attached the click event handler to all links that have the "#" symbol anywhere in the href, the very next line ensures that the link is pointing to the same page — by checking for a match between location.pathname and this.pathname — and the line after that ensures that it's pointing to the same domain, by checking for a match between location.hostname and this.hostname. With this approach, we can accommodate same-page links whether they include a fully-qualified URL, a relative URL, or just the fragment identifier.

Check for the Hash

Let's fix the problem with the <a href="#"> links. The first thing we have to do is see if there is actually something following the "#" symbol in the href. Apparently, if there is a lone "#" symbol, without any following characters, Firefox and Internet Explorer don't consider it a hash. Safari does, however. So, to avoid a false positive on <a href="#">, we need to first strip the "#" and then check if there is anything left. We can do so by adding this condition to the first if statement: && this.hash.replace(/#/,'')

Check for the Named Anchor

Since we're already changing the script, maybe it's a good time to make some of it more readable, too. This part with the "short-circuit" logic, using && and ||, makes me a little dizzy:

There is absolutely nothing wrong with this syntax. In fact, more advanced JavaScripters use it all the time. But I feel more comfortable using a simpler, more straightforward style. So, let's set two variables — one for a target ID and one for a target named anchor. We'll then use conditional (aka ternary) operators to set a third, $target, variable as the target ID if it's there, and if not, the target named anchor if it's there, and if not, false. Then we can just check if $target has some value (other than false):

Now it appears that the animated scrolling behavior will be attached to all same-page links and not break other stuff on the page.

Loop First, Bind Last

But there is another problem. Since we're still binding the .click() method to every link with "#" in it, even if it's appropriately avoiding applying the animation for some of those links, jQuery is still hijacking links that have an inline onclick handler (but, oddly, only the first time those links are clicked). To fix this problem, we can replace the .click() with .each(). Then we'll iterate through all links that have "#" somewhere in them, but place the conditions inside the loop so that we bind the click handler only after we've filtered out all the links that don't apply. Here is what the script looks like with the change:

Notice especially lines 2 and line 10. This change not only takes care of our problem, but it feels cleaner somehow, too. Is it more efficient? I don't know. Maybe someone else can tell us in the comments.

Normalize Directory Indexes

To be complete, we should probably take care of one more thing: the possibility that, on an "index" page, a link could point to "/path/index.htm" when the current location says "/path/" or vice versa. One way to "normalize" these index pages and links is to add a couple more .replace() methods to both sides of the equation in line 3.

Update

Aman suggested in a comment below that I make this process DRYer, and kangax provided a great example. So we can write a filter function and apply it to both sides rather than repeating the three replaces on each side:

The first additional .replace() will find a string represented by "index" or "default," followed by a dot, followed by any three or four letters at the end the pathname, and replace it with an empty string (i.e. remove it). The second one will replace a trailing slash with an empty string. As with chained jQuery methods, these regular-expression methods can be placed on separate lines to improve readability. Finally, we have a bullet-proof (I hope) animated scrolling script for same-page links:

If you try it out, let me know how it goes.

Update 2

Ariel Flesler has written an excellent ScrollTo plugin, which he says was inspired by this blog entry. Be sure to check out the demo.

Update 3

Someone called my attention to a problem that this script was having in IE and Opera. Not sure how I could have missed that, because I'm sure I tested it in both of those browsers. But never mind, I've come up with a little patch:

Apparently, IE doesn't see a hostname or pathname if a link's href attribute is set with JavaScript and contains only a hash (such as "#example"). So, I'm checking now for either a match or an absence of hostname and pathname.

I hope this change fixes the problem that Mike was having. Seems to work in my tests now. Oh, and I took the opportunity to improve the code a bit. Now, it has mild back-button support: while clicking on the back button doesn't produce the animated scrolling, it at least gets you back to the previous location.

Update 4

Ariel Flesler suggested that the problem a few people have mentioned regarding this script with Opera has to do with this line: $('html, body').animate({scrollTop: targetOffset}, 400); Here is a fix:

I put together a little smooth-scroll jQuery plugin with a couple options, in case anyone is interested. For a more robust feature set, check out Ariel Flesler's scrollTo plugin.

Here is what the code looks like with the minor change:

Not a bad little adjustment when you consider that we're able to get rid of a plugin dependency.

One subtle change here is that we've removed the "@" symbol for the attribute selector, because jQuery 1.2 uses the CSS notation rather than the XPath. The more significant change is the way we're locating the target's position and animating the scroll to reach it:

First, we declare a targetOffset variable for the target's top offset position. This is now possible because the .offset() method from the Dimensions plugin has been moved into the core library.

Next, we animate the scrollTop property of the body and html elements to that targetOffset value, courtesy of the expanded jQuery fx module.

But why do we need to select both body and html? Well, Firefox and IE use body in quirks mode but html in standards mode. Our $('html, body') selector takes both situations into account. Of course, if you know your pages are running in standards mode (which they should), then you can drop the body (and the comma) from the selector.

Ease on down the page

Let's not stop there, though. While we're playing around with this, we can add an easing effect. All we need to do is reference the easing plugin and add our easing option to the .animate() method, like so:

.animate({scrollTop: targetOffset}, 1000, 'easeOutBack');

And if, as Dorian asked about in a comment on the previous tutorial, you want to scroll to a position 30 pixels above the target id, you can do so simply by subtracting 30 from $target.offset().top:

var targetOffset = $target.offset().top - 30;

Animate scrolling within an element

Here's something really fun: with the new .animate() functionality, we can animate the scrolling of an element that has its CSS overflow property set to "auto" or "scroll."

Let's say, for example, that we have a div with an id of "scrollable" and inside it we have a bunch of paragraphs. Something like this:

Now we want to animate the scroll to the third paragraph. Before we get too far in the explanation, let's try it: Scroll to paragraph 3

For this one, we find the difference between the div's top offset and that of the third paragraph. Then we just scroll the div to that number. Just for kicks, we'll include the "easeOutBounce" easing method as well.

Update

Based on feedback from Joel Birch and Oli in the comments below, I've changed the code below to take advantage of "relative animations," using the syntax available in jQuery 1.2.1. My initial tests showed that it's now working regardless of scroll-bar or font-size adjustments. Here is what it looks like now (not sure if storing the difference in a third variable was necessary, but it felt right to me):

That's all there is to it. Have fun.