Scrollable basics

The Story
Features
Plugins
Demos

Add custom scrolls to your site

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!

Study the first demo to get a quick start

standalone demo

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

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

Configuration

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; JavaScript
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:

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

JavaScript

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 -->
<div>
  <a class="next"/>
  <div class="scrollable">
    ...
  </div>
  <a class="prev"/>
</div>
 
<!-- 2nd instance -->
<div>
  <a class="next"/>
  <div class="scrollable">
    ...
  </div>
  <a class="prev"/>
</div>

HTML

Events

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

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: