jQuery Tools / Scrollable - Scroll your HTML with eye candy

Demo

Scroll through the elements below by:

Clicking on the elements themselves
Clicking on the arrows at the sides, or the small, round buttons at the top
Using the left and right arrow keys on your keyboard
Scrolling with your mouse scroll wheel

1. An example title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et felis eget tellus pharetra porttitor. Praesent dui arcu, egestas quis, adipiscing a.

60 sec

2. An example title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et felis eget tellus pharetra porttitor. Praesent dui arcu, egestas quis, adipiscing a.

80 sec

3. An example title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et felis eget tellus pharetra porttitor. Praesent dui arcu, egestas quis, adipiscing a.

100 sec

4. An example title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et felis eget tellus pharetra porttitor. Praesent dui arcu, egestas quis, adipiscing a.

120 sec

5. An example title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et felis eget tellus pharetra porttitor. Praesent dui arcu, egestas quis, adipiscing a.

140 sec

6. An example title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et felis eget tellus pharetra porttitor. Praesent dui arcu, egestas quis, adipiscing a.

160 sec

7. An example title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et felis eget tellus pharetra porttitor. Praesent dui arcu, egestas quis, adipiscing a.

180 sec

8. An example title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et felis eget tellus pharetra porttitor. Praesent dui arcu, egestas quis, adipiscing a.

200 sec

9. An example title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et felis eget tellus pharetra porttitor. Praesent dui arcu, egestas quis, adipiscing a.

220 sec

10. An example title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et felis eget tellus pharetra porttitor. Praesent dui arcu, egestas quis, adipiscing a.

240 sec

11. An example title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et felis eget tellus pharetra porttitor. Praesent dui arcu, egestas quis, adipiscing a.

260 sec

12. An example title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et felis eget tellus pharetra porttitor. Praesent dui arcu, egestas quis, adipiscing a.

280 sec

13. An example title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et felis eget tellus pharetra porttitor. Praesent dui arcu, egestas quis, adipiscing a.

300 sec

Motivation

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 advantage of using scrollable compared to "normal" browser scrolling is that you don't see the browser's default scrollbars, and you can perform scrolling in much more visually sophisticated ways, like the above example. 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 - for example, the Flowplayer front page
Product catalogues
News tickers
Custom select boxes in forms
Image galleries
Video playlists
All kinds of navigational systems

Features

Here is a quick overview of scrollable's feature set:

Horizontal and vertical scrolling.
Scrolling using navigational buttons, API calls, keyboard arrow keys, and the mouse scroll wheel.
(requires the jquery.mousewheel plugin)
The number of items scrolled at once is customizable.
The navigational buttons are setup without a single line of JavaScript.
Tabbed navigation (such as on the Flowplayer front page) 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 make your own animation effects.
Automatic scrolling.
The ability to customize the scrolling experience with onBeforeSeek and onSeek listeners.

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. One of the main reasons we created scrollable was so to have a simple and easy-to-use tool for implementing scrollable Flowplayer video playlists - something which hours of searching for on the web didn't dig up anything. But you can use it for anything. Enjoy!

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.

Usage

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.

Combining scrollable with Flowplayer

These demos provide some examples of how to use scrollable and Flowplayer together:

the Flowplayer home page - uses scrollable for tabbed navigation
a scrollable Flowplayer playlist
a horizontally-scrolling Flowplayer playlist

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:

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:

Property	Default value	Description
size	`5`	The number of visible items within the scrollable-enabled HTML element. This property can also be referred to as the "page size", since it defines how many items are moved in a particular direction when either the `nextPage` or `prevPage` actions are executed.
vertical	`false`	Whether items will be scrolled vertically. If set to `false`, items will be scrolled horizontally.
clickable	`true`	Whether scrolling occurs when an item is clicked inside the scrollable-enabled element.
loop	`false`	Whether scrolling starts from the first item in the list when the last item is reached.
interval	`0`	The time (in milliseconds) between automatic scrolling of items (one step forward). Automatic scrolling is enabled when this property is set to any positive integer value. See this demo for more information. Deprecated. Since scrollable 1.0.5 this configuration variable is a depcreated feature and it will be replaced by an "autoscroll plguin" in scrollable 1.1.0.
speed	`400`	The time (in milliseconds) of the scrolling animation.
keyboard	`true`	Whether keyboard arrow key navigation is enabled. The horizontal scroller moves backwards/forwards with the left/right arrow keys; the vertical scroller moves with the up/down keys.

items	`".items"`	Selector for the element that contains the scrollable items. This must be located inside the parent scrollable-enabled HTML element. See minimal setup for an explanation of this.
prev	`".prev"`	Selector for the sibling element to which a "scroll backwards" action should be bound. If this is an `ID`, then the element can be anywhere on the page. See the demo for more information.
next	`".next"`	Selector for the sibling element to which a "scroll forwards" action should be bound. If this is an `ID`, then the element can be anywhere on the page.
prevPage	`".prevPage"`	Selector for the sibling element to which a "previous page" action should be bound. If this is an `ID`, then the element can be anywhere on the page.
nextPage	`".nextPage"`	Selector for the sibling element to which a "next page" action should be bound. If this is an `ID`, then the element can be anywhere on the page.
navi	`".navi"`	Selector for the sibling element that contains a navigator for switching between pages. If this is an `ID`, then the element can be anywhere on the page. This topic is covered in more depth below.
naviItem	`"a"`	The HTML element name for navigational items which are auto-populated inside the navigator.

activeClass	`"active"`	The CSS class name for: (a) a clicked scrollable item, and (b) the navigator item which corresponds to the current page.
disabledClass	`"disabled"`	The CSS class name for disabled `next`/`nextPage` and `prev`/`prevPage` elements. For example, the `prev` element is disabled when there are no previous items to scroll to.
hoverClass		The CSS class name for the scrollable item which has a mouse pointer over it.
easing	`"swing"`	The type of "easing" applied to the scrolling animation. 'swing' means that there is an acceleration, followed by a constant speed, followed by a deceleration. 'linear' means that the whole animation happens at a constant speed. You can also make your own easing effects.
api	`false`	When this tool is initialized (constructed), the return value is a jQuery object associated with the selector. By setting this property to `true`, the return value is this tool's JavaScript API instead. If the selector returns multiple elements, the API of the last element will be returned. Read more about accessing the tool API for more information.

onBeforeSeek		This callback function is triggered before items are scrolled. A function which returns `false` will prevent scrolling from taking place. This function is fed with one argument that is the target index number.
onSeek		This callback function is triggered after items have been scrolled.

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 
 
});

You can read more about callback functions from the Users Manual.

Using navigator

When you have lots of items in a scrollable list, you may wish to use scrollable's navigator feature. This will allow your users to more easily navigate between different pages in the list. You can create a navigator by placing an HTML element that will function as a navigator beside your scrollable element. By default, this element should have the class navi, but you can change this in your configuration. The 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.

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

<!-- manual navigator configuration --> 
<ul class="tabs"> 
    <li>First item</li> 
    <li>Second item</li> 
    <li>Third item</li> 
</ul>

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

$("jquery selector").scrollable({ 
 
    // ul.tabs now functions as our navigator 
    navi:'ul.tabs' 
});

A navigator can be placed before or after the main scrollable element, but it must be a sibling of it. In other words, the navigator and the main scrollable element must be at the same "level" in the HTML element hierarchy. The same rule applies for the prev, next, prevPage and nextPage elements - they must also be siblings of the scrollable element. This is because if you have multiple scrollable elements on the page and each one has navigational elements, you can initialize those as scrollable with a single call.

Since version 1.0.3, you are able to place navigational elements anywhere on the page. In this case, the selector for the element must have an ID.

Scripting API

scrollable has a clean and well-designed API for scripters, with which it is possible to enrich the overlaying user experience. You can get a handle to the API in numerous ways as described in the Users 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 this variable points to the API 
    this.prev(); 
 
});

Method index

Method	Return value	Description
getConf()	`Object`	Returns the configuration object for the scrollable instance. Note that this object can be modified and the changes are dynamically reflected in the behaviour of the associated scrollable element.
getIndex()	`number`	Returns the current position within the scrollable element. 0 means the first item, 1 the second item, and so on.
getItems()	`jQuery`	Returns the scrollable items as a jQuery object.
getItemWrap()	`jQuery`	Returns the parent element for the scrollable items as a jQuery object.
getPageAmount()	`number`	Returns the number of pages which could depend upon the `size` (as specified in the configuration).
getPageIndex()	`number`	Returns the current page index. As an example, if the page size is 5 and the current position (the index) is 7, then the value returned will be 1 (the second page).
getRoot()	`jQuery`	Returns the main scrollable element as a jQuery object.
getSize()	`number`	Returns the page size (as specified in the configuration). Identical to `getConf().size`
getVisibleItems()	`jQuery`	Returns a list of items that are currently being viewed. Return value is a jQuery object which has as many elements as being defined in the `size` configuration variable.

reload()	`API`	scrollable supports the dynamic addition and removal of scrollable elements. Take a look at this demo for more details. After adding or removing items, calling this method ensures that the navigator has the correct number of elements, `prev`/`next` buttons function correctly, and click handlers are added for new items.
prev()	`API`	Scrolls one item backward.
next()	`API`	Scrolls one item forward.
seekTo(index)	`API`	Seeks to the specified index.
move(offset)	`API`	Moves a certain number of items from the current position. For example, `move(2)` moves two items forward. Negative numbers move backwards.
prevPage()	`API`	Scrolls one page backward.
nextPage()	`API`	Scrolls one page forward.
setPage(index)	`API`	Seeks to the specific page.
movePage(offset)	`API`	Moves a certain number of pages from the current position. For example, `move(2)` moves two pages forward. Negative numbers move backwards.
begin()	`API`	Moves to the beginning. Identical to `seek(0)`.
end()	`API`	Moves to the end.
click(index)	`API`	Programmatically "clicks" the item at the specified index. Scrolling takes place, the item is made active, and any event handlers are triggered.

onBeforeSeek(fn)	`API`	Registers a new callback function that is triggered before items are scrolled. The callback is given as the argument. Returning `false` in the callback will prevent scrolling from taking place. You can assign multiple `onBeforeSeek` listeners with this command. See using callbacks for more information.
onSeek(fn)	`API`	Registers a new callback function that is triggered after items have been scrolled. The callback is given as the argument. You can assign multiple `onSeek` listeners with this command. See using callbacks for more information.

Arguments and return value

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

speed this argument is used to specify how long (in milliseconds) the scrolling animation lasts. This overrides the speed property specified in the configuration.
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.

jQuery Tools / Scrollable - Scroll your HTML with eye candy

Demo

1. An example title

2. An example title

3. An example title

4. An example title

5. An example title

6. An example title

7. An example title

8. An example title

9. An example title

10. An example title

11. An example title

12. An example title

13. An example title

Motivation

Features

Usage

Combining scrollable with Flowplayer

scrollable Graphics

Configuration

Using callback functions

Using navigator

Scripting API

Method index

Arguments and return value

Documentation

The Tools