carousel.md

Carousel

Cycles through items using a slide or fade animation.

Usage

Manual implementation of the carousel markup is required, as there is no automatic generation of elements in the JavaScript layer. The reasoning behind this is simple. It allows elements within the carousel to be added or removed easily, without having to alter options in JavaScript, or define overrides in CSS. The following markup can be used for basic carousel functionality.

<div class="carousel">
    <!-- Items to cycle -->
    <div class="carousel-items">
        <ul>
            <li><a href=""><img src="/img/carousel/item-1.png" alt="" class="fluid"></a></li>
            ...
        </ul>
    </div>

    <!-- Tabs for each item -->
    <div class="carousel-tabs">
        <ol class="bullets">
            <li><a href="javascript:;"></a></li>
            ...
        </ol>
    </div>

    <!-- Next and previous arrows -->
    <a href="javascript:;" class="carousel-prev"></a>
    <a href="javascript:;" class="carousel-next"></a>
</div>

If we don't want next and previous arrows, don't add the markup for it. If we don't want the tab list, don't add the markup for it. If we want additional elements, we can freely add them! So on and so forth. The only elements that are required, are the .carousel wrapper, and the .carousel-items list.

Once the markup is in place, a carousel can be initialized.

$('.carousel').carousel();

Cycle Animation

There are 3 kinds of animation, slide (default), slide-up, and fade. The type of animation must be passed as an option when the carousel is initialized.

$('.carousel').carousel({
    animation: 'slide-up'
});

The .carousel element will receive a class with the animation name. This allows for styling based on the type of animation used.

Toolkit makes use of CSS3 transitions for animation, which older browsers do not support. Instead of animations in these browsers, an immediate show or hide will occur.

Aspect Ratios

By default the carousel is designed for a 4:3 aspect ratio. To use a 16:9 aspect ratio, the .carousel--wide modifier can be used.

<div class="carousel carousel--wide">
    ...
<div>

To use a 1:1 (square) aspect ratio, the .carousel--square modifier can be used.

<div class="carousel carousel--square">
    ...
<div>

To use a custom aspect ratio, or to use a fixed height, modify the padding-bottom on .carousel-items. For example, the 4:3 has a bottom padding of 75%, while the 16:9 has a value of 56.25%, and the 1:1 has a value of 100%. This technique allows for automatic height scaling based on the width of the carousel.

Scrolling Mechanisms

There are 3 types of scrolling offered by the carousel: infinite scrolling (default), looped scrolling, and one-way scrolling.

Infinite scrolling will allow the next and previous buttons to continuously cycle through all items without a visual break. This can be toggled through the infinite option (default true).

$('.carousel').carousel({
    infinite: true
});

Looped scrolling will rewind the items to the beginning of the list when the last item is reached, and vice versa. This can be toggled through the loop option (default true).

$('.carousel').carousel({
    infinite: false,
    loop: true
});

One-way scrolling will stop cycling when the first or last item is reached. This is the fallback option when both infinite and loop are disabled.

$('.carousel').carousel({
    infinite: false,
    loop: false
});

Multiple Items

Modify the itemsToShow option to display multiple items at a single time in the carousel viewport. This option will automatically calculate the correct widths and percentages and apply them to the list items.

$('.carousel').carousel({
    itemsToShow: 3
});

We can also change the number of items to move when cycling occurs by modifying the itemsToCycle option.

$('.carousel').carousel({
    itemsToShow: 3,
    itemsToCycle: 3
});

Responsive Support

The carousel was designed with responsiveness in mind by utilizing percentages and a fluid structure. We suggest using inline images within each carousel item, sized to the correct aspect ratio (above). The carousel will take care of everything else.

Notes

• The currently shown index will have an .is-active class applied to the respective tab.
• A .no-next and .no-prev class is added to the carousel to hide next and previous buttons.
• Modifying padding-bottom on .carousel-items allows for fixed or custom heights.
• Supports arrow and escape key events.

ARIA

The tab, tablist, and tabpanel roles, and the appropriate aria-* attributes are required when supporting ARIA.

<div class="carousel">
    <div class="carousel-items">
        <ul>
            <li role="tabpanel">...</li>
        </ul>
    </div>

    <div class="carousel-tabs" role="tablist">
        <ol class="bullets">
            <li><a href="javascript:;" role="tab"></a></li>
        </ol>
    </div>
</div>

The JavaScript component will automatically map all ARIA attributes.

Variables

Variable	Default	Description
$carousel-opacity	0.50	The alpha transparency for the carousel caption element.
$carousel-transition	1s	The transition time for all carousel animations.

Options

Inherits all options from the parent component.

Option	Type	Default	Description
animation	string	slide	The type of animation to use for cycling. Accepts slide, slide-up, and fade.
duration	int	5000	The time in milliseconds when each cycle occurs.
autoCycle	bool	true	Whether to cycle through items automatically. Makes use of duration for intervals.
stopOnHover	bool	true	Whether to pause the automatic cycling while hovering over the carousel.
infinite	bool	true	Allows for infinite cycling in either direction.
loop	bool	true	Will rewind the cycle pointer when the last item is reached (only applies when infinite is disabled).
reverse	bool	false	Will reverse the direction for automatic cycling.
itemsToShow	int	1	The number of items to display in the carousel at the same time.
itemsToCycle	int	1	The number of items to move when cycling.
defaultIndex	int	0	The item to display on initial page load.

Events

Inherits all events from the parent component.

Option Event	Element Event	Arguments	Description
onJump	jump.toolkit.carousel	int:index	Triggered after an item is cycled into view. Applies to all next, previous, and cycle calls.
onStart	start.toolkit.carousel		Triggered when the carousel cycle has started. Can be triggered by start() or stopOnHover.
onStop	stop.toolkit.carousel		Triggered when the carousel cycle has stopped. Can be triggered by stop() or stopOnHover.
onCycle	cycle.toolkit.carousel		Triggered when autoCycle is enabled, immediately before the next item is cycled.

Properties

Inherits all properties from the parent component.

Property	Type	Description	Found With
container	element	The parent element for all item elements.	.carousel-items > ul
items	collection	A collection of item elements that will be cycled through.	container > li
tabs	collection	A collection of tab elements that can be clicked to jump to items.	.carousel-tabs a
index	int	The index of the currently shown item.
timer	int	The automatic cycle timer instance.
stopped	bool	Has the carousel stopped cycling.
animating	bool	Is the carousel currently animating.

Methods

Inherits all methods from the parent component.

Method	Description	Bound To
calculate()	Calculate the sizes of the wrapper and items based on browser width and defined options.
jump(int:index)	Go to a specific item defined by the index in the collection.	.carousel-tabs a
next()	Go to the next item.	.carousel-next
prev()	Go to the previous item.	.carousel-prev
start()	Start automatic cycling.	.carousel-start
stop()	Stop automatic cycling.	.carousel-stop
reset()	Reset the cycling timer.