Configuration

The carouFredSel-plugin provides a lot of options for customizing your carousel. Luckily for you, all options are OPTIONAL...
The default option values can be overridden by passing new values to the method or by redefining the default option values.

The following options are provided by the plugin. Really sweet customized carousels can be created by using these options. Have a look at the configuration code examples page to see just how.

Need help with all those options? Click here to use the Configuration Robot >

Please note:
As of version 5.1.0, the effect of "even+" and "odd+" for the items.visible option has changed.

Option Default value Datatype Description
circular true Boolean Determines whether the carousel should be circular.
infinite true Boolean 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 Boolean Determines whether the carousel should be responsive.
If true, the items will be resized to fill the carousel.
direction "left" String The direction to scroll the carousel, determines whether the carousel scrolls horizontal or vertical and -when the carousel scrolls automatically- in what direction.
Possible values: "right", "left", "up" or "down".
width null Number The width of the carousel.
If null, the width will be calculated (and set to "variable" if necessary, depending on the item-widths).
String Enter "variable" to automatically resize the carousel when scrolling items with variable widths.
String Enter "auto" to measure the widest item.
String Enter a percentage to automatically resize (and re-configurate) the carousel onWindowResize.
Note: Only applies on horizontal carousels.
For example: "100%".
height null Number The height of the carousel.
If null, the height will be calculated (and set to "variable" if necessary, depending on the item-heights).
String Enter "variable" to automatically resize the carousel when scrolling items with variable heights.
String Enter "auto" to measure the highest item.
String Enter a percentage to automatically resize (and re-configurate) the carousel onWindowResize.
Note: Only applies on vertical carousels.
For example: "100%".
align "center" String Whether and how to align the items inside a fixed width/height.
Possible values: "center", "left", "right" or false.
padding null Number Padding around the carousel (top, right, bottom and left).
Array Padding in an Array.
For example: [10, 20, 30, 40] (top, right, bottom, left)
or [0, 50] (top/bottom, left/right).
synchronise null String Selector for the carousel to synchronise.
Array Selector and options for the carousel to synchronise:
[string selector, boolean inheritOptions, boolean sameDirection, number deviation] For example: ["#foo2", true, true, 0]
Array A collection of arrays.
cookie false Boolean Determines whether the carousel should start at its last viewed position.
The cookie is stored until the browser is closed.
String A specific name for the cookie to prevent multiple carousels from using the same cookie.
onCreate null Function Function that will be called after the carousel has been created.
This function receives 2 parameters:
  • items: a jQuery-object of the items that are currently visible.
  • sizes: a map of the sizes of the carousel:
     sizes.width and sizes.height
> items
Click to showhide the options for this object.		 Object A map of the configuration for the items: visible, minimum, start, width, height and filter.
{
visible null Number The number of visible items.
If null, the number will be calculated (and set to "variable" if necessary).
String Enter "variable" to measure the number of visible items
(based on the available size).
Object A map for min and max.
String A string consisting of three sections:
  • base:"odd", "even" or ""(an empty string, default).
  • adjustment:"+" or "-".
  • amount:any number (1 by default)
For example: "odd+2" will measure the number of items needed to fill the available size, decrease it to an odd number and increase it by two.
Function A function that returns the number of visible items.
This function receives 1 parameter:
  • visibleItems: the number of items that would fit the available size.
minimum null Number The minimum number of items needed to create a carousel.
If null, the number for items.visible is inherited and increased by 1.
start 0 Number The nth item to start the carousel.
Hint: This can also be a negative number.
String Enter "random" to let the plugin pick a randon item to start the carousel.
String A jQuery-selector of the item to start the carousel.
For example: "#foo li:first".
jQuery-object A jQuery-object of the item to start the carousel.
For example: $("#foo li:first").
Boolean If true, the plugin will search for an item-anchor to start the carousel using the url-hashtag.
For example: http://domain.com#startitem
Array An array of the options above in the order they should be tested for a valid value.
width null Number The width of the items.
If null, the width will be measured (and set to "variable" if necessary).
String Enter "variable" to create a carousel that supports variable item-widths.
String Enter a percentage to automatically resize the width of the items onWindowResize.
Note: Only applies on responsive, vertical carousels.
For example: "50%".
height null Number The height of the items.
If null, the height will be measured (and set to "variable" if necessary).
String Enter "variable" to create a carousel that supports variable item-heights.
String Enter a percentage to automatically resize the height of the items onWindowResize.
Note: Only applies on responsive, horizontal carousels.
For example: "50%".
filter null String The selector elements should match to be considered an item.
If null, all elements inside the carousel will be considered to be an item.
If the carousel contains :hidden-elements, it is set to ":visible".
Note: this option is not (yet) compatible with non-circular carousels.
}
Number A number for items.visible.
String Enter "variable" for items.width, items.height and items.visible.
> scroll
Click to showhide the options for this object.		 Object A map of the configuration used for general scrolling: items, fx, easing, duration, pauseOnHover, queue, mousewheel, event, wipe, conditions, onBefore, onAfter and onEnd.
{
items null Number The number of items to scroll.
If null, the number of visible items is used.
String Enter "page" to scroll to the first item of the previous/next "page".
String A string consisting of three sections:
  • base:"odd", "even" or ""(an empty string, default).
  • adjustment:"+" or "-".
  • amount:any number (1 by default)
For example: "odd+2" will decrease the number of visible items to an odd number and increase it by two.
fx "scroll" String Indicates which effect to use for the transition.
Possible values: "none", "scroll", "directscroll", "fade", "crossfade", "cover" or "uncover".
Note: these effects are considered to be built in workarounds, therefore it is not guaranteed that they will work with all other options.
easing "swing" String Indicates which easing function to use for the transition. jQuery defaults: "linear" and "swing", built in: "quadratic", "cubic" and "elastic".
duration 500 Number Determines the duration of the transition in milliseconds.
If less than 10, the number is interpreted as a speed (pixels/millisecond).
This is probably desirable when scrolling items with variable sizes.
pauseOnHover false Boolean Determines whether the timeout between transitions should be paused "onMouseOver" (only applies when the carousel scrolls automatically).
String Enter "resume" to let the timeout resume instead of restart "onMouseOut".
String Enter "immediate" to immediately stop "onMouseOver" and resume "onMouseOut" a scrolling carousel.
String Enter "immediate-resume" for both the options above.
queue false Boolean Determines whether the scrolling should be queued if the carousel is currently being animated.
mousewheel false Boolean Determines whether the carousel can be scrolled via the mousewheel. To enable this feature, you'll need to include the jquery.mousewheel plugin.
Number Enter a numeric value to specify the amount of items to scroll.
event "click" String The event to trigger the prev-, next- and pagination-buttons.
wipe false Boolean Determines whether the carousel can be scrolled via wipe-gestures (for smartphones). To enable this feature, you'll need to include the jquery.touchwipe plugin.
conditions null Function Function that tests whether the carousel should start scrolling.
If it doesn't return true, the carousel will not scroll.
onBefore null Function Function that will be called right before the carousel starts scrolling.
This function receives 4 parameters:
  • oldItems: a jQuery-object of the items that are visible before scrolling.
  • newItems: a jQuery-object of the items that will be visible after scrolling.
  • newSizes: a map of the new sizes of the carousel:
     newSizes.width and newSizes.height
  • duration: the duration of the transition.
onAfter null Function Function that will be called right after the carousel finished scrolling.
This function receives 3 parameters:
  • oldItems: a jQuery-object of the items that were visible before scrolling.
  • newItems: a jQuery-object of the items that are visible after scrolling.
  • newSizes: a map of the new sizes of the carousel:
     newSizes.width and newSizes.height
onEnd null Function Function to call when a non-circular carousel reaches its start or end.
}
Number A number for scroll.items or -if greater than 50- for scroll.duration.
String A string for scroll.easing.
> auto
Click to showhide the options for this object.		 Object A map of the configuration used for automatic scrolling: play, button, pauseDuration, delay, items, fx, easing, duration, pauseOnHover, pauseOnEvent, pauseOnResize, queue, event, conditions, onBefore, onAfter, onEnd, onPauseStart, onPauseEnd and onPausePause.

This object is the same as the scroll object, except for play, button, pauseDuration, delay, pauseOnEvent, pauseOnResize, onPauseStart, onPauseEnd and onPausePause. What is not specified in this object, will be inherited from the scroll object.
{
play true Boolean Determines whether the carousel should scroll automatically or not.
button null String A jQuery-selector for the HTML element that should toggle the carousel between playing and paused.
jQuery-object A jQuery-object of the HTML element that should toggle the carousel between playing and paused.
Function A function that returns any of the other valid values.
pauseDuration 5 * [auto.duration] Number The amount of milliseconds the carousel will pause.
If auto.duration is less then 10 -to use a speed (in pixels/milliseconds) instead of a duration-, the default value is 2500.
delay 0 Number Additional delay in milliseconds before the carousel starts scrolling the first time.
Hint: This can also be a negative number.
items [scroll.items] See the description for scroll.items.
fx [scroll.fx] See the description for scroll.fx.
easing [scroll.easing] See the description for scroll.easing.
duration [scroll.duration] See the description for scroll.duration.
pauseOnHover [scroll.pauseOnHover] See the description for scroll.pauseOnHover.
pauseOnEvent false Boolean Determines whether the timeout between transitions should be paused when the event on the button is triggered.
See the description for scroll.pauseOnHover.
pauseOnResize true Boolean Determines whether the timeout between transitions should be paused when resizing the window.
Note: Only applies on responsive carousels.
queue [scroll.queue] See the description for scroll.queue.
event [scroll.event] See the description for scroll.event.
conditions [scroll.conditions] See the description for scroll.conditions.
onBefore [scroll.onBefore] See the description for scroll.onBefore.
onAfter [scroll.onAfter] See the description for scroll.onAfter.
onEnd [scroll.onEnd] See the description for scroll.onEnd.
onPauseStart null Function Function that will be called when starting the pausing-timer.
This function receives 2 parameters:
  • percentage: The percentage the auto.pauseDuration is at.
  • duration: The remaining time left in milliseconds.
onPauseEnd null Function Function that will be called when ending the pausing-timer.
Functionality is the same as for the onPauseStart-function.
onPausePause null Function Function that will be called when pausing the pausing-timer.
Functionality is the same as for the onPauseStart-function.
}
Boolean True or false for auto.play.
Number A number for auto.pauseDuration.
> prev
Click to showhide the options for this object.		 Object A map of the configuration used for scrolling backwards using the "previous" button or key (or via the mousewheel): button, key, items, fx, easing, duration, pauseOnHover, queue, mousewheel, event, wipe, conditions, onBefore, onAfter and onEnd.

This object is the same as the scroll object, except for button and key. What is not specified in this object, will be inherited from the scroll object.
{
button null String A jQuery-selector for the HTML element that should scroll the carousel backward.
jQuery-object A jQuery-object of the HTML element that should scroll the carousel backward.
Function A function that returns any of the other valid values.
key null Number The keyCode of the keyboard-key that should scroll the carousel backward.
String Can be: "up", "down", "left" or "right".
items [scroll.items] See the description for scroll.items.
fx [scroll.fx] See the description for scroll.fx.
easing [scroll.easing] See the description for scroll.easing.
duration [scroll.duration] See the description for scroll.duration.
String Enter "auto" to let the plugin calculate a speed for the transition instead of using a duration. This is probably desirable when using the slideTo event.

Note: The speed is calculated by deviding scroll.duration by scroll.items and multiplying it with the amount of items to scroll.
pauseOnHover [scroll.pauseOnHover] See the description for scroll.pauseOnHover.
queue [scroll.queue] See the description for scroll.queue.
mousewheel [scroll.mousewheel] See the description for scroll.mousewheel.
event [scroll.event] See the description for scroll.event.
wipe [scroll.wipe] See the description for scroll.wipe.
conditions [scroll.conditions] See the description for scroll.conditions.
onBefore [scroll.onBefore] See the description for scroll.onBefore.
onAfter [scroll.onAfter] See the description for scroll.onAfter.
onEnd [scroll.onEnd] See the description for scroll.onEnd.
}
String Any valid string for prev.button or prev.key.
Number A number for prev.key.
> next
Click to showhide the options for this object.		 Object A map of the configuration used for scrolling forward using the "next" button or key (or via the mousewheel): button, key, items, fx, easing, duration, pauseOnHover, queue, mousewheel, event, wipe, conditions, onBefore, onAfter and onEnd.

This object is the same as the scroll object, except for button and key. What is not specified in this object, will be inherited from the scroll object.
{
button null String A jQuery-selector for the HTML element that should scroll the carousel forward.
jQuery-object A jQuery-object of the HTML element that should scroll the carousel forward.
Function A function that returns any of the other valid values.
key null Number The keyCode of the keyboard-key that should scroll the carousel forward.
String Can be: "up", "down", "left" or "right".
items [scroll.items] See the description for scroll.items.
fx [scroll.fx] See the description for scroll.fx.
easing [scroll.easing] See the description for scroll.easing.
duration [scroll.duration] See the description for scroll.duration.
String Enter "auto" to let the plugin calculate a speed for the transition instead of using a duration. This is probably desirable when using the slideTo event.

Note: The speed is calculated by deviding scroll.duration by scroll.items and multiplying it with the amount of items to scroll.
pauseOnHover [scroll.pauseOnHover] See the description for scroll.pauseOnHover.
queue [scroll.queue] See the description for scroll.queue.
mousewheel [scroll.mousewheel] See the description for scroll.mousewheel.
event [scroll.event] See the description for scroll.event.
wipe [scroll.wipe] See the description for scroll.wipe.
conditions [scroll.conditions] See the description for scroll.conditions.
onBefore [scroll.onBefore] See the description for scroll.onBefore.
onAfter [scroll.onAfter] See the description for scroll.onAfter.
onEnd [scroll.onEnd] See the description for scroll.onEnd.
}
String Any valid string for next.button or next.key.
Number A number for next.key.
> pagination
Click to showhide the options for this object.		 Object A map of the configuration used for scrolling via the "pagination" buttons or keys: container, keys, anchorBuilder, items, fx, easing, duration, pauseOnHover, queue, event, conditions, onBefore, onAfter and onEnd.

This object is the same as the scroll object, except for container, keys and anchorBuilder. What is not specified in this object, will be inherited from the scroll object.
{
container null String A jQuery-selector for the HTML element that should contain the pagination-links.
jQuery-object A jQuery-object of the HTML element that should contain the pagination-links.
Function A function that returns any of the other valid values.
keys false Boolean Determines whether the pagination can be controlled via the keyboard-key 1-9.
Note: any page after page 9 will not be accessible via the keyboard.
anchorBuilder null Function Function to use for building the anchors of the pagination.
This function receives 2 parameters:
  • nr: the page number.
  • item: a jQuery object of the first visible item on the page.
If null, the public method pageAnchorBuilder is used:
$.fn.carouFredSel.pageAnchorBuilder: function(nr, item) {
    return '<a href="#'+nr+'"><span>'+nr+'</span></a>';
};
Boolean If false, instead of building the pagination, the elements allready available in the container will be used as anchors.
items [items.visible] The number of items per page.
fx [scroll.fx] See the description for scroll.fx.
easing [scroll.easing] See the description for scroll.easing.
duration [scroll.duration] See the description for scroll.duration.
String Enter "auto" to let the plugin calculate a speed for the transition instead of using a duration.

Note: The speed is calculated by deviding scroll.duration by scroll.items and multiplying it with the amount of items to scroll.
pauseOnHover [scroll.pauseOnHover] See the description for scroll.pauseOnHover.
queue [scroll.queue] See the description for scroll.queue.
event [scroll.event] See the description for scroll.event.
conditions [scroll.conditions] See the description for scroll.conditions.
onBefore [scroll.onBefore] See the description for scroll.onBefore.
onAfter [scroll.onAfter] See the description for scroll.onAfter.
onEnd [scroll.onEnd] See the description for scroll.onEnd.
}
String Any valid string for pagination.container.
Boolean True or false for pagination.keys.

Note: In all callback-functions, this refers to the HTML-element of the carousel.

Have a look at the configuration code examples page for more detailed information on how to use the configuration options.
Working examples can be found on these examples pages.


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.
> wrapper
Click to showhide the options for this object.		 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.
}
> events
Click to showhide the options for this object.		 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
Click to showhide the options for this object.		 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-buttons if the carousel is stopped.
}

Override by passing new values to the method

<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="jquery.carouFredSel.js"></script>
<script type="text/javascript">
	$(document).ready(function() {
		$("#foo1").carouFredSel();
		$("#foo2").carouFredSel();
		$("#foo3").carouFredSel({
			items		: 3,
			direction	: "up"
		}, {
			debug		: true
		});	
	});
</script>

Note: These changes will only apply to the #foo3 carousel.


Override by redefining the default option values

<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="jquery.carouFredSel.js"></script>
<script type="text/javascript">
	$.fn.carouFredSel.defaults.items.visible 	= 3;
	$.fn.carouFredSel.defaults.direction 		= "up";
	$(document).ready(function() {
		$("#foo1").carouFredSel();
		$("#foo2").carouFredSel();
		$("#foo3").carouFredSel();
	});
</script>

Note: These changes will apply to all the carousels on the page.

Need some help?

When you're in desperate need of help, you might want to visit the examples-pages or have a peak at the tips & tricks and maybe the known issues. Or -if everything else fails- try the support forum.

Feedback

Any kind of feedback is more than welcome in this forum-topic.
Thank you!


Share to Facebook Share to Twitter Stumble it More...