Top

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" data-carousel>
    <!-- Items to cycle -->
    <div class="carousel-items">
        <ul data-carousel-items>
            <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" data-carousel-tabs>
            <li><a href="javascript:;"></a></li>
            ...
        </ol>
    </div>

    <!-- Next and previous arrows -->
    <a href="javascript:;" class="carousel-prev" data-carousel-prev></a>
    <a href="javascript:;" class="carousel-next" data-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();
The data-carousel-* attributes are required so that the JavaScript layer can find or bind elements in the DOM.

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
});
These options simply ease the calculation process. The sizes of the items will still need to be set manually with CSS.

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.
Top

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 data-carousel-items>
            <li role="tabpanel">...</li>
        </ul>
    </div>

    <div class="carousel-tabs" role="tablist">
        <ol class="bullets" data-carousel-tabs>
            <li><a href="javascript:;" role="tab"></a></li>
        </ol>
    </div>
</div>
The JavaScript component will automatically map all ARIA attributes.
Top

Variables

Variable Default Description
$carousel-class .carousel CSS class name for the carousel wrapper.
$carousel-class-items .carousel-items CSS class name for the carousel items list.
$carousel-class-next .carousel-next CSS class name for the carousel next button.
$carousel-class-prev .carousel-prev CSS class name for the carousel previous button.
$carousel-class-tabs .carousel-tabs CSS class name for the carousel tabs list.
$carousel-class-modifier-square .carousel--square CSS class name for the carousel square modifier.
$carousel-class-modifier-wide .carousel--wide CSS class name for the carousel wide modifier.
$carousel-modifiers ("wide", "square") List of modifiers to include in the CSS output. Accepts wide and square.
$carousel-opacity 0.50 The alpha transparency for the carousel caption element.
$carousel-transition 1s The transition time for all carousel animations.
Top

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.
autoCycle bool true Whether to cycle through items automatically. Makes use of duration for intervals.
defaultIndex int 0 The item to display on initial page load.
duration int 5000 The time in milliseconds when each cycle occurs.
infinite bool true Allows for infinite cycling in either direction.
itemsToCycle int 1 The number of items to move when cycling.
itemsToShow int 1 The number of items to display in the carousel at the same time. The actual item widths will need to be set with CSS.
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.
rtl bool Toolkit.isRTL Will reverse the carousel for right-to-left languages.
stopOnHover bool true Whether to pause the automatic cycling while hovering over the carousel.
swipe bool Toolkit.isTouch Will bind swipe events. If this is true on non-touch devices, it will bind equivalent mouse events.
Top

Events

Inherits all events from the parent Component.

Event Arguments Description
cycling Triggered before the item cycle animation begins.
cycled Triggered after the item cycle animation finishes.
jumping int:oldIndex Triggered before an item is cycled into view. Applies to all next, previous, and cycle calls.
jumped int:newIndex Triggered after an item is cycled into view. Applies to all next, previous, and cycle calls.
start Triggered when the carousel cycle has started. Can be triggered by start() or stopOnHover.
stop Triggered when the carousel cycle has stopped. Can be triggered by stop() or stopOnHover.
Top

Properties

Inherits all properties from the parent Component.

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

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. [data-carousel-tabs] a
next() Go to the next item. [data-carousel-next]
prev() Go to the previous item. [data-carousel-prev]
start() Start automatic cycling. [data-carousel-start]
stop() Stop automatic cycling. [data-carousel-stop]
reset() Reset the cycling timer.