This is a message.

Scrollable basics

Add custom scrolls to your site

Flying screens

You can use this tool on

  • 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 main design goals of this tool are to provide visual customization, ease of use and programmability. 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.
  • Any amount of items on one "page". Pages can have variable width.
  • The navigational buttons are setup without a single line of JavaScript.
  • Tabbed navigation like this example can be setup without any programming.
  • Programmatic actions are available, such as: next, prev, seekTo, begin,and end.
  • Dynamic addition and removal of Scrollable items.
  • The ability to customize the scrolling experience with onBeforeSeek and onSeek listeners.
  • Ability to setup infinite loops without beginning or end

All of this in just a 1.02 Kb file! Unmatched. Uncomparable.

Extendable architecture

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

  • autoscroll   makes the scrolling behaviour automatic and is highly configurable.
  • navigator   provides navigation buttons for switching between pages in Scrollable. Can be enabled with a history feature so that you can scroll with your browser's back (and forward) button.

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!

standalone demo

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

  1. By using the left and right arrow keys on your keyboard
  2. With your mouse scroll wheel
  3. By clicking on the action buttons below the scrollable


Here is a list of all available configuration options:

Property Default value Description
clonedClass 'cloned' The plugin behaves so that the first and last items are cloned at both ends. These cloned items are assigned the CSS class name given in this configuration variable.
disabledClass "disabled" The CSS class name for disabled next and prev elements. For example, the prev element is disabled when there are no previous items to scroll to. Typically you assign the visibility: 'hidden' CSS definition to disabled elements.
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.
items ".items"

The scrollable root element is not directly used as a parent for the scrollable items. The root must have one nested element that contains the actual items. By default scrollable uses the first and only element inside the root as a wrapper for the items. It does not have to have any particular CSS class name. A simple div is fine.

If for some reason you have multiple elements inside the root element, then scrollable looks for the element specified by this property. By default an element with the class name "items" is used, but you can use any jQuery selector you like for this property.

See the minimal setup for an understanding of the HTML setup for scrollable.

keyboard true

Whether or not 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. The arrow keys are valid for the scrollable that was used most recently. Since version 1.1.0 you can also supply the value 'static' here which means that the scrollable is always controlled with the arrow keys and it does not have to be active.

You can also use the focus() method to force the focus to a certain scrollable on the page. You can take a look at the A complete scrollable navigational system demo which takes advantage of the "static" value and the focus() method.

If you want to disable the keyboard for a particular scrollable, you can do the following:

        // grab second scrollabe and its API
var instance = $(".horizontal").eq(1).data("scrollable");
// disable keyboard navigation
instance.getConf().keyboard = false;

circular false A property indicating whether scrolling starts from the beginning when the last item is exceeded making an "infinite loop".
next ".next" Selector for the elements to which a "scroll forwards" action should be bound. These elements should have a mutual wrapper element together with the scrollable itself.
prev ".prev" Selector for the elements to which a "scroll backwards" action should be bound. These elements should have a mutual wrapper element together with the scrollable itself.
speed 400 The time (in milliseconds) of the scrolling animation.
vertical false The scrollable is good at guessing whether it's vertical or horizontal by investigating it's dimensions. If the height is larger than the width then the scrollable is vertical. This can also be manually configured with this configuration option which overrides the automatic determination.

Multiple scrollables with next and prev links

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



Now each of the scrollable uses the default selectors .next and .prev 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 its navigational actions inside a mutual wrapper element. For example:

<!-- 1st scrollable and its navigational actions are wrapped inside an
extra DIV -->
<a class="next"/>
<div class="scrollable">
<a class="prev"/>
<!-- 2nd instance -->
<a class="next"/>
<div class="scrollable">
<a class="prev"/>



Make sure you have read about Events in jQuery Tools. All event listeners receive the Event Object as the first argument and the second argument is the index number of the scrollable being scrolled to.

event When does it occur?
onBeforeSeek Before items are scrolled.

You have the ability to change the speed of the animation inside this function by changing the api.getConf().speed configuration option.

onSeek After items have been scrolled.
onAddItem When an item was added to the scrollable via the addItem method.

JavaScript API

First make sure you have familiarized yourself with jQuery Tools scripting.

Method index

Method Return value Description
addItem() API scrollable supports the dynamic addition and removal of scrollable elements and all core functionalities such as circular looping, navigator resizing, browser back button navigation (via toolbox.history) which will work as expected. Take a look at this demo for more details.
begin(speed) API Moves to the beginning. Identical to seekTo(0).
end(speed) API Moves to the end.
focus() API After this call the keyboard arrow keys will control this particular scrollable instance.
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 scroll position. This is the index number of the first visible item of the scrollable. Indexing starts from zero.
getItems() jQuery Returns the scrollable items as a jQuery object.
getItemWrap() jQuery Returns the parent element for the scrollable items as a jQuery object.
getNaviButtons() jQuery Returns navigational buttons (next/prev/prevAll/nextAll) as a single jQuery object. If you are using the navigator plugin it is also appended to this return value.
getRoot() jQuery Returns the main scrollable element as a jQuery object.
getSize() number Returns the amount of items in the scrollable. Identical to getItems().size().
move(offset, speed) API Moves a certain number of items from the current position. For example, move(2) moves two items forward. Negative numbers move backwards.
next(speed) API Scrolls one item forward.
prev(speed) API Scrolls one item backward.
seekTo(index, speed) API Seeks to the specified index.

The speed argument is used to specify how long (in milliseconds) the scrolling animation lasts. This overrides the speed property specified in the configuration.

scrollable Graphics

Download graphics pack

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: