This is a jQuery plugin that allows to create responsive scrollers (carousels) with grid and simple horizontal layouts. RadiantScroller can be cuztomized with the variety of options. API methods and callbacks are available. Elements may also have animated captions.
JavaScript CSS
Switch branches/tags
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.gitignore
CHANGELOG.md
LICENSE.txt
README.md
jquery.radiant_scroller.css
jquery.radiant_scroller.js
jquery.radiant_scroller.min.js
package.json

README.md

jQuery RadiantScroller plugin

npm version

This is a jQuery plugin that allows to create responsive scrollers (carousels) with grid and simple horizontal layouts. RadiantScroller can be cuztomized with the variety of options. API methods and callbacks are available. Elements may also have animated captions.

Demos

Images were taken from FreeImages.

Requirements

  1. jQuery 1.7.0+
  2. MouseWheel plugin (only if you want to provide mousewheel support)

Installation and usage

  • Hook up required files

  • Hook up jquery.radiant_scroller.min.js and jquery.radiant_scroller.css

  • Set up basic layout for the scroller:

<div id="your_scroller_id">
    <div class="scroller-el"><img src="image1.jpg" alt="Image1" /></div>
    <div class="scroller-el"><img src="image2.jpg" alt="Image2" /></div>
    <div class="scroller-el"><img src="image3.jpg" alt="Image3" /></div>
</div>

The scroller-el class is required.

  • Set up basic styling. In fact, only specifying margins and dimensions for the elements in the scroller is required. This can be done like:
.radiant_scroller .scroller-el {
    width: 200px;
    height: 200px;
    margin-right: 10px;
    margin-bottom: 10px; /* This is optional but recommended - otherwise your images will have no horizontal spacing */
}
  • Initialize the scroller. The values for elementWidth and elementMargin should be the same as your specified in the previous step otherwise the scroller's grid will be built incorrectly. You will probably want to specify scroller's grid dimensions with the cols and rows attributes (the default is 2x2 grid). All available options are listed in the "Options" section.
$(document).ready(function() {
    $('#myScroller').radiantScroller({
        elementWidth: 200,
        elementMargin: 10,
        cols: 3,
        rows: 3
    });
});

Options

Property Default Description
animateDuration 700 Integer Animation duration for the scrolling. The value is specified in milliseconds.
addPagination false Boolean Whether the scroller should have pagination (often displayed as small navigational dots) enabled.
captionsAnimateDuration 400 Integer Animation duration for the captions.
captionsAnimateEasingType 'swing' Integer Easing type for the captions' animation. You can specify any other type of easing but bear in mind that jQuery has only swing and linear easings included. You will have to include jQueryUI's effects and easings plugin to get more.
cols 2 Integer How many (maximum) columns should the scroller have - basically this means how many elements will be visible at once horizontally (but if the scroller's width changes this value will also change).
delayDuration 500 Integer How long the scroller will wait after the resizing to initiate recalculation (this is done to ensure that the recalculation takes place only after the user has finished resizing the screen).
easingType "swing" String Easing type for the scrolling. You can specify any other type of easing but bear in mind that jQuery has only swing and linear easings included. You will have to include jQueryUI's effects and easings plugin to get more.
elementMargin 10 Integer Horizontal (left/right) margin for the scroller's elements. This value should correspond to the value that is provided in the styles.
elementWidth 200 Integer Width for the scroller's elements. This value should correspond to the value that is provided in the styles.
nextButtonText "" String Text to be shown on the "next" button.
prevButtonText "" String Text to be shown on the "previous" button.
rows 2 Integer How many rows should the scroller have.
useCaptions false Boolean Whether captions should be enabled. Check Captions section for more information.
useMouseWheel false Boolean Whether support for the mousewheel scrolling should be enabled. Please note that when this value is set to true, you should hook up MouseWheel plugin.

Styling

jquery.radiant_scroller.css provides only required styles so you have to write some more styles to make the scroller look nice. When the scroller is initialized the following layout is being built (pagination will not be shown until you set addPagination option to true):

<div class="radiant_scroller">
    <div class="radiant_scroller_wrapper">
        <div id="myScroller">
            <div class="radiant_scroller_row">
                <div class="scroller-el"><img src="image1.jpg" alt="Image1" /></div>
                <div class="scroller-el"><img src="image2.jpg" alt="Image2" /></div>
            </div>
            <div class="radiant_scroller_row">
                <div class="scroller-el"><img src="image3.jpg" alt="Image3" /></div>
                <div class="scroller-el"><img src="image4.jpg" alt="Image4" /></div>
            </div>
        </div>
    </div>
    <div class="radiant-pagination">
        <div class="radiant-page current-page" data-page="1"></div>
        <div class="radiant-page" data-page="2"></div>
    </div>
    <div class="radiant-navigation">
        <div class="radiant-prev"></div>
        <div class="radiant-next"></div>
    </div>
</div>

All elements except for #myScroller and .scroller-el are added dynamically.

  • .radiant-pagination contains navigational pages; the active page has the current-page class, so you can style it differently.
  • .radiant-navigation contains next and previous buttons. .radiant-prev and .radiant-next are positioned absolutely (and main wrapper .radiant_scroller is positioned relatively) so you can adjust its position as necessary.

See demos to get the basic idea how the scroller can be styled.

Captions

Starting from version 0.1.0 scroller elements may have animated captions. To use them few things have to be done:

  • Set useCaptions option to true
  • Adjust captionsAnimateDuration and captionsAnimateEasingType if needed
  • Add title attribute to your elements like this:
<div id="your_scroller_id">
    <div class="scroller-el"><img src="image1.jpg" alt="Image1" title="This is a caption" /></div>
    <div class="scroller-el"><img src="image2.jpg" alt="Image2" title="Another caption" /></div>
</div>
  • Enjoy the captions!

By default captions appear at the bottom of the element with white centered text and black semi-opaque background. If you wish to style it differently, assign your styles to .radiant-caption class.

API

To get access to the RadiantScroller's API you should initialize your scroller like this:

var my_scroller = $('#myScroller').radiantScroller({...});

And then you can manage your scroller by calling radiantScroller on the my_scroller variable and passing it an API action to invoke. Currently there are a few API methods available:

  • radiantScroller('next') - scroll one page forward
  • radiantScroller('prev') - scroll one page backward
  • radiantScroller(<number>) - scroll to a page with the specified number. Page numeration starts from 1. If a non-existent page is provided nothing happens.
  • radiantScroller('by', <number>) - scroll by a specified number of pages. For example if you are at the 1st page and call my_scroller.radiantScroller('by', 2) you scroll by 2 pages and end up at the 3rd page.

To see them all in action open this demo. More methods coming soon.

Callbacks

Starting from version 0.1.0 the following callbacks are available:

Callback Description
loaded Fires when the scroller has finished loading and is ready. Scroller is being passed as an argument.
beforeMove Fires before each scroller's moving animation. Scroller is being passed as an argument.
afterMove Fires before after scroller's moving animation. Scroller is being passed as an argument.
lastPageReached Fires when the scroller has finished loading and is ready. Scroller is being passed as an argument.
afterHidingCaption Fires after the caption was hidden. Caption is being passed as an argument.
afterShowingCaption Fires after the caption was showed. Caption is being passed as an argument.

For Rails developers

jquery-radiantscroller-rails gem provides an easy way to integrate Radiant Scroller into your Rails project.

License

This plugin is licensed under the MIT License.

Copyright (c) 2016 Ilya Bodrov