carouFredSel jQuery Plugin

Download: http://dev7studios.com/plugins/caroufredsel

Old Documentation: http://docs.dev7studios.com/caroufredsel-old

Install files

Installing the carouFredSel jQuery plugin is actually pretty simple. You just need to add the Following code to the <head> of your web page:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.10.1/jquery.min.js" type="text/javascript"></script>
<script src="jquery.carouFredSel.js" type="text/javascript"></script>

This will make sure all the required files are loaded properly. If you have the carouFredSel CSS and Javascript files in a subfolder you will need to add it to the path. Note that the carouFredSel jQuery plugin requires jQuery v1.7+ to work.

Add markup

The HTML markup for carouFredSel is also very simple. You simply need to create a div with an id (#carousel in this case) and add some content to it:

<div id="carousel">
    <img src="img1.jpg" width="300" />
    <img src="img2.jpg" width="300" />
    <img src="img3.jpg" width="300" />
    <img src="img4.jpg" width="300" />
</div>

The content can be whatever you want, including HTML. For example:

<div id="carousel">
    <div>
        <h3>Infinity</h3>
        <p>A concept that in many fields refers to a quantity without bound or end.</p>
    </div>
    <div>
        <h3>Circular journey</h3>
        <p>An excursion in which the final destination is the same as the starting point.</p>
    </div>
    <div>
        <h3>jQuery</h3>
        <p>jQuery  is a cross-browser JavaScript library designed to simplify the client-side scripting.</p>
    </div>
</div>

Hook up the carousel

Finally you need to hook up the carousel by adding the following code after the three links we included in the <head>:

<script type="text/javascript">
$(document).ready(function() {
    // Using default configuration
    $('#carousel').carouFredSel();

    // Using custom configuration
    $('#carousel').carouFredSel({
        items               : 2,
        direction           : "up",
        scroll : {
            items           : 1,
            easing          : "elastic",
            duration        : 1000,                         
            pauseOnHover    : true
        }                   
    });
});
</script>

Note: After the plugin has been executed, the container-element has been wrapped inside a div-element with the class caroufredsel_wrapper.

Play with settings

carouFredSel has plenty of settings to fiddle with. Below is an example of the code with all available options and their defaults:

$('#carousel').carouFredSel({
    circular: true,         // Determines whether the carousel should be circular.
    infinite: true,         // Determines whether the carousel should be infinite. Note: It is possible to create a non-circular, infinite carousel, but it is not possible to create a circular, non-infinite carousel.
    responsive: false,      // Determines whether the carousel should be responsive. If true, the items will be resized to fill the carousel.
    direction: "left",      // The direction to scroll the carousel. Possible values: "right", "left", "up" or "down".
    width: null,            // The width of the carousel. Can be null (width will be calculated), a number, "variable" (automatically resize the carousel when scrolling items with variable widths), "auto" (measure the widest item) or a percentage like "100%" (only applies on horizontal carousels)
    height: null,           // The height of the carousel. Can be null (width will be calculated), a number, "variable" (automatically resize the carousel when scrolling items with variable heights), "auto" (measure the tallest item) or a percentage like "100%" (only applies on vertical carousels)
    align: "center",        // Whether and how to align the items inside a fixed width/height. Possible values: "center", "left", "right" or false.
    padding: null,          // Padding around the carousel (top, right, bottom and left). For example: [10, 20, 30, 40] (top, right, bottom, left) or [0, 50] (top/bottom, left/right).
    synchronise: null,      // Selector and options for the carousel to synchronise: [string selector, boolean inheritOptions, boolean sameDirection, number deviation] For example: ["#foo2", true, true, 0]
    cookie: false,          // Determines whether the carousel should start at its last viewed position. The cookie is stored until the browser is closed. Can be a string to set a specific name for the cookie to prevent multiple carousels from using the same cookie.
    onCreate: null          // Function that will be called after the carousel has been created. Receives a map of all data.
});

Note: In all callback functions, this refers to the HTML-element of the carousel, except for the auto.progress.updater callback function, where it refers to the HTML-element of auto.progress.bar and the pagination.anchorBuilder callback function, where it refers to the HTML-element of the current item.

Advanced configuration

See the carouFredSel Advanced configuration page.

Options for the plugin

After the configuration-object, a second object can be passed to the method containing options for the plugin itself.

Option Default value Datatype Description
debug false Boolean Determines whether to log debugging information to the console.
transition false Boolean Determines whether to use CSS3 transitions instead of javascript animations.

To enable this feature, you'll need to include the jQuery.transit-plugin.

onWindowResize throttle String Enter "throttle" to use the throttle-plugin to rate-limit the carousel updating onWindowResize. Or "debounce" to use the debounce-plugin.

To enable this feature, you'll need to include the jQuery.throttle-debounce-plugin.

wrapper Object A map of the configuration for the wrapper: element and classname.
{
element "div" String Type of DOM-element to create for the wrapper.
classname "caroufredsel_wrapper" String The classname to use for the wrapper.
}
String Enter "parent" to use the parent element as the carousel-wrapper.
events Object A map of the configuration for the events: prefix and namespace.
{
prefix "" String Prefix for all events.
namespace "cfs" String Namespace for all events.
}
classnames Object A map of the configuration for the classnames: selected, hidden and disabled.
{
selected "selected" String Classname for the selected pagination anchor.
hidden "hidden" String Classname for the hidden navigational buttons.
disabled "disabled" String Classname for the disabled navigational buttons.
paused "paused" String Classname for the play-button if the carousel is paused.
stopped "stopped" String Classname for the play-button if the carousel is stopped.
}

Use block elements that float left

To ensure the plugin is able to measure the correct sizes, always use display: block; for the items. In a horizontal carousel, you should also make the items float: left;.

Preventing F.O.U.C.

When using the carouFredSel plugin, you may see a Flash Of Unstyled Content (F.O.U.C.). This is because the browser may render elements before the DOM is fully loaded and before the DOMContentLoaded event is fired. Fortunately it can be prevented, pretty easy actually. Simply apply something like the following CSS to your HTML element.

#carousel {             
    width: 870px;       
    height: 175px;      
    overflow: hidden;
}