About

Cycle through your content without writing a single line of Javascript. To keep things simple, transition effects are optional and have been limited to slide and cross-fade. In browsers that don't support CSS transitions, jQuery's animate is used.

Usage

Setup

Before getting started, make sure everything is setup properly. Below is a basic HTML template to use as an example for including the plugin into your projects.

<!DOCTYPE html>
<html>
<head>
    <title>Cycle.js</title>
    <meta charset="utf-8">
    <link rel="stylesheet" href="./path/to/cycle.css">
</head>
<body>
    <!-- Your HTML goes here -->
    <script src="./path/to/jquery.js"></script>
    <script src="./path/to/cycle.js"></script>
</body>
</html>

Attention! This is just an example and contains the minimum requirements for including Cycle.js into your project. All ./path/to references need to be replaced with proper paths.

Via data attributes

To initialize a plugin instance, simply add data-cycle="go" to your element. Be sure to add the cycle class for proper styling.

<div data-cycle="go" class="cycle">
    ...
</div>

Via Javascript

$('.cycle').cycle();

Accessing instances

Plugin instances are stored in the cyclejs key on each element's data store and can easily be accessed by using jQuery's data method.

var myCycle = $('.cycle').data('cyclejs');

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-interval="3000".

Name Type Default Description
interval number 5000 The amount of time (in milliseconds) to display an item between cycles. To disable the auto-cycle, set to false.
pause string hover

When to pause the auto-cycle. Set to false to disable.

Value Pauses
hover when an item is hovered
prev when the prev() method is called
next when the next() method is called
to when the to() method is called
transitionSpeed number 500 The amount of time (in milliseconds) that corresponds to the CSS transition speed specified in cycle.css. This value is used to ensure transitions are completed and as the animation speed for browsers that don't support CSS transitions.

Methods

All methods can be executed with the data-cycle attribute and require a data-target or href attribute whose value must correspond to the ID of a Cycle.js element. See below for examples.

.cycle(options)

Initializes an instance with an optional options object.

$('.cycle').cycle({
    interval: 3000
});
.cycle('cycle')

Starts/resumes the auto-cycle.

Via data attribute

<div id="myCycle" class="cycle">
    ...
</div>

<a data-cycle="cycle" href="#myCycle">Cycle</a>
.cycle('pause')

Pause the auto-cycle.

Via data attribute

<a data-cycle="pause" href="#myCycle">Pause</a>
.cycle('next')

Cycle to the next item.

Via data attribute

<a data-cycle="next" href="#myCycle">Next</a>
.cycle('prev')

Cycle to the previous item.

Via data attribute

<a data-cycle="prev" href="#myCycle">Previous</a>
.cycle('to', position)

Cycle to the item at the specified position.

Be aware! The position argument is one-based. A value of 1 corresponds to the first item. Negative, zero and out-of-range positions will be ignored.

Via data attribute

<a data-cycle="to" data-args="3" href="#myCycle">Go to item 3</a>

The data-args attribute is used to pass arguments to a method.

Events

Name Description
init Fires after an instance has been initialized.
cycle

Fires before a new item is cycled into view.

Property Description
relatedTarget The item element being cycled into view.
relatedIndex The index of the item element being cycled into view.

Use e.preventDefault() on this event to cancel the cycling of an item.
cycled

Fired after a new item has been cycled into view.

Property Description
relatedTarget The item element that was cycled into view.
relatedIndex The index of the item element cycled into view.

Transitions

Items can be cycled with a sliding and/or cross-fade effect. To apply a transition, simply add the proper CSS class. For a sliding transition, add slide. For a cross-fade effect, add xfade. The slide transition has 3 optional classes: right, up and down. Each optional class corresponds to the sliding direction.

Default slide from the right

<div class="cycle slide">
    ...
</div>

Slide up

<div class="cycle slide up">
    ...
</div>

Cross-fade

<div class="cycle xfade">
    ...
</div>

Slide down with cross-fade

<div class="cycle xfade slide down">
    ...
</div>

Examples

Images for these examples are provided by the amazing lorempixel service.

Basic

The following example will auto-cycle through items at the specified duration without a transition.

HTML
<div data-cycle="go" class="cycle">
    <div class="cycle-inner">
        <div class="item">
            <img src="http://lorempixel.com/320/240/sports" alt="">
        </div>
        <div class="item">
            <img src="http://lorempixel.com/320/240/animals" alt="">
        </div>
        <div class="item">
            <img src="http://lorempixel.com/320/240/food" alt="">
        </div>
    </div>
</div>
Result

Transitions

Slide

This example will auto-cycle through items with a slide transition.

HTML
<div data-cycle="go" class="cycle slide">
    <div class="cycle-inner">
        <div class="item">
            <img src="http://lorempixel.com/320/240/sports" alt="">
        </div>
        <div class="item">
            <img src="http://lorempixel.com/320/240/animals" alt="">
        </div>
        <div class="item">
            <img src="http://lorempixel.com/320/240/food" alt="">
        </div>
    </div>
</div>
Result

Slide up

HTML
<div data-cycle="go" class="cycle slide up">
    <div class="cycle-inner">
        <div class="item">
            <img src="http://lorempixel.com/320/240/sports" alt="">
        </div>
        <div class="item">
            <img src="http://lorempixel.com/320/240/animals" alt="">
        </div>
        <div class="item">
            <img src="http://lorempixel.com/320/240/food" alt="">
        </div>
    </div>
</div>
Result

Cross-fade

HTML
<div data-cycle="go" class="cycle xfade">
    <div class="cycle-inner">
        <div class="item">
            <img src="http://lorempixel.com/320/240/sports" alt="">
        </div>
        <div class="item">
            <img src="http://lorempixel.com/320/240/animals" alt="">
        </div>
        <div class="item">
            <img src="http://lorempixel.com/320/240/food" alt="">
        </div>
    </div>
</div>
Result

Slide down cross-fade

HTML
<div data-cycle="go" class="cycle xfade slide down">
    <div class="cycle-inner">
        <div class="item">
            <img src="http://lorempixel.com/320/240/sports" alt="">
        </div>
        <div class="item">
            <img src="http://lorempixel.com/320/240/animals" alt="">
        </div>
        <div class="item">
            <img src="http://lorempixel.com/320/240/food" alt="">
        </div>
    </div>
</div>
Result

With controls

HTML
<div id="controlCycle" data-cycle="go" class="cycle slide">
    <div class="cycle-inner">
        <div class="item">
            <img src="http://lorempixel.com/320/240/sports" alt="">
        </div>
        <div class="item">
            <img src="http://lorempixel.com/320/240/animals" alt="">
        </div>
        <div class="item">
            <img src="http://lorempixel.com/320/240/food" alt="">
        </div>
    </div>
    <nav>
        <a class="cycle-control" data-cycle="prev" href="#controlCycle">
            <i class="icon-chevron-left"></i>
        </a>
        <a class="cycle-control right" data-cycle="next" href="#controlCycle">
            <i class="icon-chevron-right"></i>
        </a>
    </nav>
</div>
Result

With controls and navigation

Click on the bullets to navigate to the corresponding item.

HTML
<div id="bulletCycle" data-cycle="go" class="cycle slide">
    <div class="cycle-inner">
        <div class="item">
            <img src="http://lorempixel.com/320/240/sports" alt="">
        </div>
        <div class="item">
            <img src="http://lorempixel.com/320/240/animals" alt="">
        </div>
        <div class="item">
            <img src="http://lorempixel.com/320/240/food" alt="">
        </div>
    </div>
    <nav>
        <a class="cycle-control" data-cycle="prev" href="#bulletCycle">
            <i class="icon-chevron-left"></i>
        </a>
        <a class="cycle-control right" data-cycle="next" href="#bulletCycle">
            <i class="icon-chevron-right"></i>
        </a>
        <ul class="cycle-nav">
            <li><a href="#bulletCycle" data-cycle="to" data-args="1">&bull;</a></li>
            <li><a href="#bulletCycle" data-cycle="to" data-args="2">&bull;</a></li>
            <li><a href="#bulletCycle" data-cycle="to" data-args="3">&bull;</a></li>
        </ul>
    </nav>
</div>
Javascript
<script>
    jQuery(function($){
        $('#bulletCycle').on('cycled', function(e){
            $('.cycle-nav > li', this)
                    .removeClass('active')
                    .eq(e.relatedIndex)
                        .addClass('active');
        });
    });
</script>
Result

License Apache 2.0

Copyright © 2013 Ry Racherbaumer

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.