jQuery Tools / Scrollable - Scroll your HTML with eye candy

• The Story
• Features
• Plugins
• Demos

Forget about scrollbars

The purpose of this library is to make it extremely easy to add scrolling functionality to a website. Whenever you wish to scroll HTML elements in a visually-appealing manner, this is the only library you need. The main design goals of this library are to provide visual customization functionality and programmability. Here are some example scenarios where you would benefit from using the library:

• Home pages, like this one right here
• Product catalogues
• News tickers
• Custom select boxes in forms
• Image galleries
• Video playlists
• All kinds of navigational systems

The first version of the library was released on January 3, 2008. Since then, this tool has come a long way and it is now a stable and mature product.

Rich yet simple

• Horizontal and vertical scrolling.
• Scrolling using navigational buttons, API calls, keyboard arrow keys, and the mouse scroll wheel.
• The number of items scrolled at once is customizable.
• The navigational buttons are setup without a single line of JavaScript.
• Tabbed navigation like this one can be setup without any programming.
• Programmatic actions are available, such as: next, prev, nextPage, prevPage, seekTo, begin, and end.
• Dynamic addition and removal of Scrollable items.
• The ability to customize the scrolling experience with onBeforeSeek and onSeek listeners.

This tool uses a simple and natural syntax and has an advanced programming API. You can extend it with callback methods or with your own plugins. This tool has a similar structure and feel as the other tools. Learn to use this tool and you will know how to use the rest.

This tool is a mature project and is actively maintained. The source code is clean, professional and easy to follow. It passes Douglas Crockford's JavaScript Verifier and it it doesn't assign any global variables. Active forums keep this tool alive and you can expect to see new releases coming out in the future.

Extendable architecture

Just like other tools this tool can be extended with plugins. Currently available plugins include:

• circular   makes an infinite loop from the Scrollable items so they continue cycling back to the beginning once the last item is reached.
• autoscroll   makes the scrolling behaviour automatic and is highly configurable.
• navigator   provides navigation buttons for switching between pages in Scrollable.
• mousewheel   enables mousewheel support for Scrollable.

You can also write your own plugins. Another way to alter the default behaviour is the ability to make your own animation effects. There is lots of room for experimentation!

Look at the first demo to get started

You can study the workings of Scrollable in the following examples. They contain documented source code, along with a standalone page to allow you to easily transfer the examples to your own site. The most important example is the first one, "Minimal setup for Scrollable" because it teaches you the basics of using the library.

• Minimal setup for scrollable
• A vertical scrollable
• A simple scrollable image gallery
• Another gallery with many scrollables
• A scrollable registration wizard
• Scrollable plugins in action
• Large one sized Scrollable
• jQuery Tools demo area setup
• A complete scrollable navigational system
• Add and remove items from scrollable
• Customizing the scrolling animation

« Previous Next »

Besides clicking on the tabs you can also scroll through the elements:

1. Clicking on the content area
2. Clicking on the action buttons below the scrollable
3. Using the left and right arrow keys on your keyboard
4. With your mouse scroll wheel

Configuration

There are many other ways of using this tool than can be illustrated in the demos provided here. It is important to realize that elements being setup for scrolling can contain any HTML: text, images, forms, Flash objects, or any combination of the above.

The tool is always initialized by means of a JavaScript call similar to the following:

// select one or more elements to be scrollable-enabled
$("JQUERY SELECTOR").scrollable({

	// one configuration property
	size: 5,

	// ... the rest of the configuration properties
});

Here is a list of all available configuration options:

// grab second scrollabe and it's API
var instance = $(".horizontal").eq(1).scrollable();

// disable keyboard
instance.getConf().keyboard = false;

// reload is required
instance.reload();

Multiple scrollables and next/prev/nextPage/prevPage actions

If you have multiple scrollables on your page we need to make sure that each navigational element is controlling the right scrollable instance. Let's say we have following call to instantiate multiple scrollables with their own "next" and "prev" elements.

It is possible to instantiate multiple scrollables with the same call. For example, if you have multiple scrollable root elements with the CSS class name "vertical" they can all be instantiated with this:

$(".vertical").scrollable();

Now each of the scrollable uses the default selectors .next and .next to look for the navigational elements causing multiple elements to be returned. How do we know which navigational element controls which scrollable? The problem can be solved by enclosing each scrollable and it's navigational actions inside a mutual wrapper element. For example:

<!-- 1st scrollable and it's navigational actions are wrapped inside an extra DIV -->
<div>
	<a class="next"/>
	<div class="scrollable">
		...
	</div>
	<a class="next"/>
</div>

<!-- 2nd instance -->
<div>
	<a class="next"/>
	<div class="scrollable">
		...
	</div>
	<a class="next"/>
</div>

Using callback functions

Here is an example of an onSeek callback function. Inside any callback function the this variable is a pointer to the scrollable scripting API.

$("div.scrollable").scrollable({
	onSeek: function() {
		alert("current page is " + this.getPageIndex());
	},

	// another configuration variable as an example
	clickable: false

});

See the Using Callback Functions section of the User's Guide for a more detailed description about this important topic.

Scripting API

scrollable has a clean and well-designed API for scripters, with which it is possible to enrich the scrolling user experience. You can get a handle to the API in numerous ways as described in the User's Manual. Here is an example of how to access the API:

// get handle to the API upon initialization
var api = $("div.scrollable").scrollable({api: true});

// perform a simple API call
api.next();

// register a callback function
api.onSeek(function() {

	// here, the 'this' variable points to the API
	this.getPageIndex();

});

// supply a callback function to a regular API call
api.next(function() {

	// again the 'this' variable points to the API
	this.prev();

});

Method index

Arguments and return value

All seeking methods (the methods from prev onwards in the above list) accept two additional, optional arguments:

1. speed this argument is used to specify how long (in milliseconds) the scrolling animation lasts. This overrides the speed property specified in the configuration.
2. callback this argument is used to specify a function to be called when the scrolling animation finishes. This function is called before the onSeek function and it runs only once (as opposed to onBeforeSeek and onSeek, which are called every time a scolling animation takes place).

Seeking methods always return the current scrollable instance, so you can chain method calls as follows:

// a method chaining example
$("div.scrollable").scrollable().click(0).seekTo(2, 3000, function() {
	this.getConf().easing = 'linear';
	this.end();
});

Although this example probably doesn't represent a real world scenario, it is a good demonstration, and it will work if you try executing it in the Firebug console on the example on this page.

scrollable Graphics

You can use our graphics as the basis for your design. You can freely change the design as you see fit. Click the image on the right to download a zip file. Before using the graphics, you should consult the User's Guide on how graphics can be used when designing the look and feel of the tools.

Here are a few examples of what is included in the zip file:

Plugins

You can find a demo page that shows all of the plugins in action and their installation notes.

Circular plugin version: 0.5.1

The circular plugin generates an infinite loop for the scrollable items. There is no fixed beginning or end and when you surpass the last item it will magically start from the beginning. The same thing happens if you navigate backwards from the first item. Here is this plugin in action:

This circular feature can be used in horizontal scrollables too. The plugin behaves so that the first and last items are cloned at both ends. When those cloned items are visible the scroll position is changed to the real position of the cloned item. Because of this behavioir there are actually more scrollable items than in the original setup.

Usage details

Here is the JavaScript setup for the example above:

// initialize scrollable together with the circular plugin
$("#infinite").scrollable().circular();

Look at a standalone version of the demo above.

Configuration

Here is a full list of available configuration options:

Known issues

This plugin is still in beta stage. It has not been fully tested an in complex setups it may not bahave well. Here are some issues that are not yet solved.

Most of the API methods are overridden so that they return the correct results. As a result of this methodology the following issues exist in the current implementation of this plugin:

If you are using the navigator plugin together with this plugin, you must chain the navigator plugin after this plugin. For example:

// always place the navigator plugin AFTER the circular plugin
$("#myroot").scrollable().circular().navigator();

Autoscroll plugin

Autoscroll plugin provides an automatic scrolling capability. It advances to the next items in pre-configured intervals. Here is a autoscroll plugin in action:

Play Pause Stop

You can configure the number of items being scrolled and the interval of the scrolls. When navigational elements are mouseovered the automatic scrolling is paused.

Usage

Here is the JavaScript setup for the example above:

$("#scroller").scrollable().autoscroll({autoplay: false});

Configuration

Here is a full list of available configuration options:

JavaScript API

The following methods are added to the main JavaScript API of the scrollable and they are ready to be used after the plugin has been installed.

Navigator plugin

Navigator plugin will allow your users to more easily navigate between different pages in the scrollable. This plugin is convenient if you have lots of items in a scrollable list. Here is the navigator plugin in action:

HTML setup

Here is the HTML setup for the example above.

<!-- wrapper for navigator elements -->
<div class="navi"></div>

This navigator element will be auto-populated with the type of HTML elements specified by your configuration's naviItem property, as follows:

<div class="navi">
	<a href="0" class="active"></a>
	<a href="1" ></a>
	<a href="2" ></a>
	<a href="3" ></a>
</div>

The number of nested naviItem elements depends on the number of scrollable items you have. It's up to you how you visualize those elements using CSS. The navigator knows which page you are currently viewing, and will assign the class name specified in the activeClass configuration property to the active navigation element.

JavaScript setup

Here is the JavaScript setup for the example above.

// initialize scrollable together with the navigator plugin
$("#browsable").scrollable().navigator();

Manual setup

You can also use an existing HTML structure as a navigator. Here is an example:

<!-- manual navigator configuration -->
<ul class="tabs">
	<li><a href="#first">First item</a></li>
	<li><a href="#second">Second item</a></li>
	<li><a href="#third">Third item</a></li>
</ul>

This can be setup as a navigator by doing the following:

$("jquery selector").scrollable().navigator({

	// ul.tabs now functions as our navigator
	navi:'ul.tabs'
});

The items inside navigator can be anything such as LI, A, SPAN or P elements. By default the plugin uses the direct children as navigator items but you can supply naviItem configuration that will select the specified child elements to be used as navigator items.

If you are using A tags inside the wrap and you supply href attributes for them you have the added benefit of automatically the seeking to the correct item when you enter the page with a matching "hash" on the URL. For example if you go to an URL mypage.html#second for the above setup the scrollable will automatically seek to the Second item. You can see an example of this here. Note that the third tab is automatically opened.

Configuration

Here is a full list of available configuration options:

JavaScript API

The navigator plugin overrides the getNaviButtons methods of the scrollable API so that it will also contain the navigator element.

Mousewheel plugin

Mousewheel plugin enables scrolling with your mousewheel. Use the mousewheel on top of the scrollable below to see it in action:

Usage

Here is the JavaScript setup:

// initialize scrollable together with the mousewheel plugin
$("#wheeled").scrollable().mousewheel();

Configuration

Here is a full list of available configuration options:

The wheel plugin

This plugin is based on Three Dub Media's wheel plugin which is a smaller, simplified interpretation of the Brandon Aaron's well-known special event, "Mouse Wheel Extension". Thank you! If you have downloaded the mousewheel plugin this wheel plugin is also ready to be used as a standalone tool. Here is how you can use it:

// make #myelement listen to mousewheel events
$("#myelement").wheel(function(event, delta) {

});

Whenever the mousewheel is used with the selector element, the supplied function is called. It is fed with two arguments. The first one is the jQuery event object and the second one specifies how much the wheel was rotated. A positive value for delta means movement downwards and a negative value means movement upwards.

Release Notes

  follow jQuery Tools on