jQuery.LocalScroll

Notice

I've pretty much stopped updating this blog, but the plugin development is still on-going. You can find the link to the Github project page at the bottom of the article.

What does this plugin do ?

This plugin will animate a regular anchor navigation [1] [2].
It will allow your visitors to navigate your site with a smooth scrolling effect.

Each time a link is clicked, the element you decide(can be the whole screen), will gradually scroll to the targeted element, instead of "jumping" as it'd normally do.
jQuery.ScrollTo is used for the animation.

How to implement it ?

That's easy! you need to set links and anchors, that means, set an id to all those elements you want to scroll to.
These are the anchors.
Then add links with the respective id in the href, like this:

<a href="#the_id">your_text</a>

Let's call these "local links".
Lastly, you must call jQuery.LocalScroll on elements that contain our local links, you must wait for the document to be ready.

So if (for example) you have a div with id "navigation" and the local links are inside. You add this inside a document.ready:

$('#navigation').localScroll();

If your links are all spread, you can use:

$.localScroll();

That gets all the local links in the page. Both calls to the plugin accept one optional argument, that is, a hash specifying the settings described below. None is required.

Settings

• target

  What to scroll (selector, DOMElement, or jQuery Object). If none is specified, the whole window will be scrolled.

• filter

  String or function filter to ignore some of the links.

• event

  On which event of the link to react (click by default)

• lazy

  If true, more links can be added to the matched elements ( by AJAX, jQuery, etc ) and the plugin will also react to them.

• stop

  If true (default), the plugin will stop any previous animations of the target, to avoid queuing.

• lock

  If true, the plugin will ignore events if already animating (alternative to 'stop').

• hash

  If true, the hash of the clicked link, will appear on the address bar once the animation ends.
  Note:This option isn't too cool when scrolling overflown elements, it's mostly recommended when scrolling the window.

• onBefore

  A function to be called before each scrolling. It receives the following arguments: event object, targeted element and target to be scrolled. The 'this' will point to the set of settings.

• reset

  Only for $.localScroll.hash(), if true (default) elements' scroll is reset before actual scrolling.

In addition to that, you can use jQuery.ScrollTo's settings!
Check its demo to see all of them.

The plugin also adds a function, $.localScroll.hash() , that checks the URL in the address bar, and if there's a hash(#an_id), it will scroll to the element. It accepts a hash of settings, just like $.localScroll. You will likely call it on document ready. Check the regular example to see it in action.

How do I use the settings ?

The most important setting is 'target', you might not want to navigate(scroll) the screen, but only an overflowed element(like the demo).
In that case, you specify the target, with a selector or the element itself.

$('#navigation').localScroll({
   target:'#content'
});

Instead of the window, an element with id 'content' will be scrolled.

Finally, a more complex call to show some customization in action:
Let's say you need to scroll on both axes to uncover all the anchors, then we'll need the option 'axis'.
You want to do an horizontal scroll, and then vertical, the code would be:

$('ul.sections').localScroll({
   target:'#content',
   axis:'xy',
   queue:true //one axis at a time
});

Note that 'axis' and 'queue' actually belong to jQuery.ScrollTo, not to jQuery.LocalScroll.

Dynamic content( AJAX, AHAH, or simply jQuery )

The plugin supports dynamically added/loaded anchors and local links. You need to set the option 'lazy' to true. Note that the matched elements (#navigation in the first example) must be preserved in the DOM. But any content inside it can be modified. You don't have this problem if you use the global call.

Troubleshooting

When using the browser's back button, the scroll isn't reverted

This is a known fact when scrolling overflown elements (as in not the window).

When clicking a link, it jumps directly to the target

That's the browser default behavior (no javascript). You either have a javascript error (check with Firebug) or something's wrong in the call to the plugin.

Strange things happen

Try removing the option 'hash' or set it to false. It can cause problems.

Check ScrollTo's troubleshooting.

Links

• Main post
• Downloads
• Github Repo
• Demo
• AJAX Demo
• jQuery.ScrollTo's demo (must see)
• Changelog