rcarousel – a continuous jQuery UI carousel

Table of Content

  1. Announcement
  2. Examples
  3. News
  4. About
  5. Features
  6. Compatibility
  7. Getting started
  8. Configuration options
  9. Public API
  10. Navigation
  11. Changelog
  12. Where to get help?

Announcement

rcarousel development is discontinued at the moment. Maybe If I have more time and feel like it I will resume the work on the project. Anyway I encourage you to share it, fork it and whaterver you feel like. But please – respect the licence.

Examples

  1. simple carousel
  2. carousel with margin between elements
  3. vertical carousel
  4. carousel with custom step and visible elements
  5. carousel with the auto mode
  6. elements loaded on demand
  7. multiple carousels on one page
  8. carousel with custom navigation
  9. carousel wrapped with links
  10. carousel with HTML content
  11. carousel + lightbox

News

About

rcarousel is a jQuery UI continuous carousel with many cool features. It is highly customizable and supports even older browsers (No IE6, please).

Features

simple to use

Now rcarousel is very simple to use. Just add some elements into a container and run the widget on it!

highly customizable

rcarousel does not force you to use one pre-defined theme. You can add your own custom navigation with no effort!

many options to choose from

There are many options to choose from. Configure your carousel whatever you like!

Any element

As of 1.1 version you can use hopefully any HTML element inside a carousel. To illustrate this, take a look at the carousel I used at the top of the page.

images with links

As of 1.1 version there is no problem with wrapping IMG elements with links. Another nice feature!

Multiple carousels

You can add as many carousels as you like to a page without a problem. To see a working example, take a look at multi carousels example.

Vertical carousels

rcarousel supports also vertical orientation of carousels.

Loading elements on demand

With the help of append method, you can load elements on demand. It can come in handy in AJAX calls.

Auto mode

Thanks to the Auto mode you do not even have to use navigation.

cool pagination

The pagination algorithm that is a part of rcarousel allows you to use a custom number of visible elements and a step to scroll by.

simple API

Available API allows you to control rcarousel at the run-time!

Compatibility

rcarousel was tested and has been tested in many browsers. If you come across a bug, please report it in the bug tracker. Some browsers like Internet Explorer 6 are too old and will not be supported. Because of some browsers release cycle like that of Chrome (and Firefox until recently), it is very hard to keep track of rcarousel behaviour in these browsers. Thus the widget was tested just in Chrome/Chromium. Also please note, it is not so easy to estimate the number of browsers to test in especially when it comes to minor releases or a bug fix releases. The more the better is not the answer. If the browser you want to use rcarousel in, is for some reason important to you, and the widget doesn't work in it, you can fill in a bug report in the bug tracker.

rcarousel was tested in the following browsers:

Getting Started

To get started, add the following JavaScript scripts. rcarousel is built on jQuery 1.7. Since rcarousel is a jQuery UI widget, some additional dependencies are required.

In examples below, replace path with the path to the folder where rcarousel is kept:

<script type="text/javascript" src="path/widget/lib/jquery-1.7.1.min.js"></script>
<script type="text/javascript" src="path/widget/lib/jquery.ui.core.min.js"></script>
<script type="text/javascript" src="path/widget/lib/jquery.ui.widget.min.js"></script>
<script type="text/javascript" src="path/widget/lib/jquery.ui.rcarousel.min.js"></script>

Then add the following style sheet in the head section:

<link type="text/css" rel="stylesheet" href="path/widget/css/rcarousel.css" />

To make it work, add images, or any html content inside some DIV element. For example:

<div id="carousel">
	<img src="flowers/tulip.jpg" alt="a tulip"/>
	<img src="flowers/rose.jpg" alt="a rose"/>
	<img src="flowers/daisy.jpg" alt="a daisy"/>
	<img src="flowers/sunflower.jpg" alt="a sunflower"/>
	<img src="flowers/pansy.jpg" alt="a pansy"/>
</div>

Then run it:

<script type="text/javascript">
	jQuery(function($) {
		$( "#carousel" ).rcarousel();
	});
</script>

Now rcarousel will be run with the default options. You should at least change default size of an element, for instance:

<script type="text/javascript">
	jQuery(function($) {
		$( "#carousel" ).rcarousel( {width: 200, height: 200} );
	});
</script>

Remember that number of elements you add to a carousel have to be at least number of elements you specify in ‘visible’ option! Otherwise the carousel will not run.

Configuration Options

Option Type Default value Description
visible integer 3 Number of visible elements. This number is the minimum number of elements you have to add.
step integer 3 Number of elements to scroll by
width integer 100 Width of carousel's elements
height integer 100 Height of carousel's elements
speed integer 1000 Speed in milliseconds of scrolling animation
margin integer 0 Margin between elements
orientation string ["horizontal" | "vertical"] "horizontal" Orientation of carousel
auto object {enabled: boolean, direction: string ["next" | "prev"], interval: integer {enabled: false, direction: "next", interval: 5000} Enables or disables automatic scrolling.
startAtPage integer 0 Which page load first
navigation object {next: string, prev: string} {next: "#ui-carousel-next", prev: "#ui-carousel-prev"} Attach click handler to a given class ".class" or an id "#id"
start event Triggered when carousel is ready to use
pageLoaded event Triggered when page is loaded (scrolled into view)

Public API

Method Usage example Description
next $( "#carousel" ).rcarousel( "next" ); load next elements by step - elements are scrolled left
prev $( "#carousel" ).rcarousel( "prev" ); load previous elements by step - elements are scrolled right
goToPage $( "#carousel" ).rcarousel( "goToPage", 5 ); goes to a given page
getTotalPages $( "#carousel" ).rcarousel( "getTotalPages" ); returns number of total pages
getCurrentPage $( "#carousel" ).rcarousel( "getCurrentPage" ); returns number of current page
append $( "#carousel" ).rcarousel( "append", $jQueryElements ); adds $jQueryElements to carousel; it’s handy in Ajax calls; see the example

Navigation

Changelog

1.1.2 → 1.1.3

Version 1.1.3 is a point release that fixes the issue #14. As you can read there, this one-character typo makes html carousel example broken in IE7. Sorry for inconvenience!

1.1.1 → 1.1.2

Version 1.1.2 is a point release that fixes the issue #10.

1.1 → 1.1.1

Version 1.1.1 is a quick release to help you use rcarousel with a lightbox. Now event handlers and data are copied as well. Have a peek at this awesome example. Please consider donating some money. As this is the last day of 2011 year, I wish you all the best in the coming 2012 year!

1.0 → 1.1

Simple to use

Now, using rcarousel is even more simple. Just add some content into a container and run it!

Any content

Version 1.1 supports any kind of content in a carousel. Not only images!

Ajax handling

Ajax calls have been delegated to third parties. See the example.

Simplified pagination algorithm

Main pagination algorithm has been further improved and well documented.

New public methods

append and getCurrentPage are new public methods.

Where to get help?

First, do not use bug tracker to get help! It’s not meant to be a helping center. Also do not e-mail me directly with a problem that could easily be solved by someone else. To get help, I encourage you to ask, for example on stackoverflow or other Q&A service.
Remember, bug tracker is for reporting bugs and, to some extent, asking for features.