If you have any problems, looking for some specific solution, or have a suggestion, please visit private knowledge base and support forum. There are many useful articles there.
1. Upload royalslider folder to your server and add the required files in your page (usually in the head section).
<!-- basic stylesheet -->
<link rel="stylesheet" href="royalslider/royalslider.css">
<!-- skin stylesheet (change it if you use another) -->
<link rel="stylesheet" href="royalslider/skins/default/rs-default.css">
<!-- Plugin requires jQuery 1.8+, use the latest version -->
<!-- If you already have jQuery on your page, you shouldn't include it second time. -->
<script src='royalslider/jquery.min.js'></script>
<!-- Main slider JS script file -->
<script src="royalslider/jquery.royalslider.min.js"></script>Check how to use another skin article in kb.
2. Add the slider HTML code to the body section (rsDefault CSS class means that slider is using default skin). Every child element will be treated as a slide. Type of tag doesn't matter, it can be an unordered list, just list of divs, whatever. You can learn more about slide types in next sections of documentation.
<div class="royalSlider rsDefault">
<!-- simple image slide -->
<img class="rsImg" src="image.jpg" alt="image desc" />
<!-- lazy loaded image slide -->
<a class="rsImg" href="image.jpg">image desc</a>
<!-- HTML content slide -->
<p>Content goes here</p>
<!-- image and content -->
<div>
<img class="rsImg" src="image.jpg" data-rsVideo="https://vimeo.com/44878206" />
<p>Some content after...</p>
</div>
<!-- HTML content -->
<div>
Put any HTML content here
</div>
<!-- HTML content (100% with and height) -->
<div class="rsContent">
Put any HTML content here
</div>
</div> 3. Initialize the slider (usually at the end of the body section. For slider settings, check options section.
<script>
jQuery(document).ready(function($) {
$(".royalSlider").royalSlider({
// options go here
// as an example, enable keyboard arrows nav
keyboardNavEnabled: true
});
});
</script>4. Apply size to slider via CSS (optional). If you want slider to scale height based on width, take a look at the autoScaleSlider option.
.royalSlider {
width: 100%;
height: 300px;
}To make slider scale height based on width, all you need is to enable `autoScaleSlider` options (more about this).
If you're having issues with this section or you don't know where to put some code, please take a look at simple HTML page with slider.
If you want RoyalSlider to resize or preload images, you need to add rsImg class to them. Examples:
<div class="royalSlider rsDefault">
<!-- simple image -->
<img class="rsImg" src="path-to-image.jpg" alt="image description" />
<!-- lazy loaded image-->
<a class="rsImg" href="path-to-image.jpg">image description</a>
<!-- Alternative markup, if you can't use anchor tag -->
<div class="rsImg">path-to-image.jpg</div>
</div>Since 9.3 version, you may specify width and height properties for image to add more natural-looking loading. I strongly recommended to view this article to learn more about this feature.
| Variable | Default Value | Description |
|---|---|---|
| autoScaleSlider | false | Automatically updates slider height based on base width. |
| autoScaleSliderWidth | 800 | Base slider width. Slider will auto-calculate the ratio based on these values. |
| autoScaleSliderHeight | 400 | Base slider height |
| imageScaleMode | 'fit-if-smaller' | Scale mode for images. Can be "fill", "fit", "fit-if-smaller" or "none". Option can be a function that should return one of these values, it has one argument - slide object that is being resized. More about image scaling. |
| imageAlignCenter | true | Aligns image to center of slide. Also, option can be function that should return one of these values, it has one argument - slide object that is being resized. |
| imageScalePadding | 4 | Distance between image and edge of slide (doesn't work with 'fill' scale mode). |
| controlNavigation | 'bullets' | Navigation type, can be 'bullets', 'thumbnails', 'tabs' or 'none' |
| arrowsNav | true | Direction arrows navigation. |
| arrowsNavAutoHide | true | Auto hide arrows. |
| arrowsNavHideOnTouch | false | Hides arrows completely on touch devices. |
| imgWidth | null | Adds base width to all images for better-looking loading. Can be specified separately for each image. Check this article to learn more. Available since 9.3. |
| imgHeight | null | Same as above, just for height. |
| slidesSpacing | 8 | Spacing between slides in pixels. |
| startSlideId | 0 | Start slide index |
| loop | false | Makes slider to go from last slide to first. |
| loopRewind | false | Makes slider to go from last slide to first with rewind. Overrides prev option |
| randomizeSlides | false | Randomizes all slides at start. |
| numImagesToPreload | 4 | Number of slides to preload on sides. If you set it to 0, only one slide will be kept in the display list at once. |
| usePreloader | true | Enables spinning preloader, you may style it via CSS (class rsPreloader). Since 9.3 version. |
| slidesOrientation | 'horizontal' | Can be 'vertical' or 'horizontal'. |
| transitionType | 'move | 'move' or 'fade'. Important note about fade transition, slides must have background as only one image is animating. |
| transitionSpeed | 600 | Slider transition speed, in ms. |
| easeInOut | 'easeInOutSine' | Easing function for simple transition. Read more in the easing section of the documentation. |
| easeOut | 'easeOutSine' | Easing function of animation after ending of the swipe gesture. Read more in the easing section of the documentation. |
| controlsInside | true | If set to true adds arrows and fullscreen button inside rsOverflow container, otherwise inside root slider container.. |
| navigateByClick | true | Navigates forward by clicking on slide. |
| sliderDrag | true | Mouse drag navigation over slider. |
| sliderTouch | true | Touch navigation of slider. |
| keyboardNavEnabled | false | Navigate slider with keyboard left and right arrows. |
| fadeinLoadedSlide | true | Fades in slide after it's loaded. |
| allowCSS3 | true | Allows usage of CSS3 transitions. Might be useful if you're experiencing font-rendering problems, or other CSS3-related bugs. |
| globalCaption | false | Adds global caption element to slider, read more in the global caption section of documentation. |
| addActiveClass | false | Adds rsActiveSlide class to current slide before transition. |
| minSlideOffset | 10 | Minimum distance in pixels to show next slide while dragging. Added in version 9.1.7. |
| autoHeight | false | Scales and animates height based on current slide. Please note: if you have images in slide that don't have rsImg class) or don't have fixed size, use $(window).load() instead of $(document).ready() before initializing slider.Also, autoHeight doesn't work with properties like autoScaleSlider, imageScaleMode and imageAlignCenter. |
| slides | null | Overrides HTML of slides, used for creating of slides from HTML that is not attached to DOM. More info in knowledge base. |
Slider can automatically grab an image caption from alt attribute (if img is used),
from contents of image a tag, or from element with class rsCaption inside slide (tag name doesn't matter).
See examples below:
<div class="royalSlider">
<!-- simple image -->
<img class="rsImg" src="image1.jpg" alt="This is caption text" />
<!-- lazy loaded image -->
<a class="rsImg" href="image1.jpg">This is caption <b>HTML</b> text</a>
<!-- slide with any content -->
<div>
<img class="rsImg" src="image1.jpg" alt="This text will be IGNORED!" />
<figure class="rsCaption">This caption <b>HTML</b> text will be used.</figure>
</div>
</div>globalCaption:true option must be added to slider to make slider parse this data. Generated element with caption will have class rsGCaption class and will be placed in root slider element, you can style and position it however you need.
Content of caption changes before animation of slides start. Global caption module must be present in build. You can see example in visible nearby gallery template.
To get thumbnail slider searches for an element with class rsTmb inside slide. If not found, it searches for image URL in data-rsTmb attribute of slide and creates image based on it. To enable thumbnails you need to set them as navigation in slider options. controlNavigation: 'thumbnails'. If you wish to put navigation on top or at left side of slider, check this article.
In contrast to thumbnails, tabs can have different size but cannot be scrollable. Tabs use same rsTmb markup.
<div class="royalSlider rsDefault">
<!-- simple image with thumbnail -->
<img class="rsImg" src="image.jpg" data-rsTmb="small-image.jpg" alt="image description" />
<!-- lazy loaded image with thumbnail -->
<a class="rsImg" href="image.jpg">image description<img src="small-image.jpg" class="rsTmb" /></a>
<!-- Image with HTML thumbnail -->
<div class="rsContent">
<img class="rsImg" src="image.jpg" alt="image description" />
<div class="rsTmb">Thumbnail HTML content</div>
</div>
</div>Thumbnails options:
| Variable | Default Value | Description |
|---|---|---|
| drag | true | Thumbnails mouse drag |
| touch | true | Thumbnails touch |
| orientation | 'horizontal' | 'horizontal' or 'vertical'. If you want them to appear above the slider, check this article. |
| arrows | true | Thumbnails arrows |
| spacing | 4 | Spacing between thumbs |
| arrowsAutoHide | false | Auto hide thumbnails arrows on hover |
| autoCenter | true | Automatically centers container with thumbs if there are small number of items |
| transitionSpeed | 600 | Thumbnails transition speed. |
| fitInViewport | true | Reduces size of main viewport area by thumbnails width or height, use it when you set 100% width to slider. This option is always true, when slider is in fullscreen mode. |
| firstMargin | true | Margin that equals thumbs spacing for first and last item. |
| arrowLeft | null | Replaces default thumbnail arrow. Variable accepts jQuery element $('This is left arrow') that will be used as arrow. You have to add it to DOM manually. Option added in version 9.1.9 + |
| arrowRight | null | Same as option above, just for right arrow. |
| appendSpan | false | Adds span element with class thumbIco to every thumbnail. Useful for styling. Addeom in 9.2.0. |
Example of initializing slider with thumbnails options:
jQuery(document).ready(function($) {
$(".royalSlider").royalSlider({
autoScaleSlider: true,
controlNavigation: 'thumbnails',
thumbs: {
spacing: 10,
arrowsAutoHide: true
}
});
});You may specify larger images when slider is in fullscreen mode by adding data-rsBigImg attribute to rsImg element. A few examples:
<a class="rsImg" data-rsBigImg="bigimage.jpg" href="normalimage.jpg">Image desc</a>
<img class="rsImg" data-rsBigImg="bigimage.jpg" src="normalimage.jpg" alt="image desc" />Fullscreen module options:
| Variable | Default Value | Description |
|---|---|---|
| enabled | false | Fullscreen functions enabled. |
| keyboardNav | true | Force keyboard arrows nav in fullscreen. |
| buttonFS | true | Fullscreen button at top right. |
| nativeFS | false | Native browser fullscreen. |
JavaScript API to enter and exit fullscreen can be found in API section. Example of using fullscreen options:
jQuery(document).ready(function($) {
$(".royalSlider").royalSlider({
// general options go gere
autoScaleSlider: true,
fullscreen: {
// fullscreen options go gere
enabled: true,
nativeFS: false
}
});
});Deep linking module makes URL automatically change when you switch between slides and you can link to the specific slide. Options:
| Variable | Default Value | Description |
|---|---|---|
| enabled | false | Linking to slides by appending #prefix-SLIDE_INDEX to url. Slides count starts from 1. If change is set to false hash is only read once, after page load. |
| change | false | Automatically change URL after transition and listen for hash change. |
| prefix | empty string | Prefix that will be added before the slide index in the hash. For example if you set it to 'gallery-', url would look like this: http://example.com/#gallery-5. |
Example of slider with deep linking module:
jQuery(document).ready(function($) {
$(".royalSlider").royalSlider({
// general options go gere
autoScaleSlider: true,
deeplinking: {
// deep linking options go gere
enabled: true,
prefix: 'slider-'
}
});
});Autoplay slideshow can be enabled via slider options. Delay between items can be set globally via delay option, or specifically for each item by adding data-rsDelay="1000" to root element of the slide (1000 = 1sec).
| Variable | Default Value | Description |
|---|---|---|
| enabled | false | Enable autoplay or not. |
| stopAtAction | true | Stop autoplay at first user action. |
| pauseOnHover | true | Pause autoplay on hover. |
| delay | 3000 | Delay between items in ms. |
Example of slider with autoplay options:
jQuery(document).ready(function($) {
$(".royalSlider").royalSlider({
// general options go gere
autoScaleSlider: true,
autoPlay: {
// autoplay options go gere
enabled: true,
pauseOnHover: true
}
});
});Example of slide specific delay:
<div class="royalSlider">
<!-- slide with any content -->
<div data-rsDelay="2000">
<img class="rsImg" src="image1.jpg" alt="This text will be IGNORED!" />
<figure class="rsCaption">This caption <b>HTML</b> text will be used.</figure>
</div>
</div>To add video to slide, you need to add data-rsVideo="" attribute to image. It can contain link to YouTube or Vimeo video. Examples:
<div class="royalSlider">
<!-- simple image with Vimeo video -->
<img class="rsImg" src="image.jpg" data-rsVideo="https://vimeo.com/44878206" />
<!-- lazy loaded image with YouTube video -->
<a class="rsImg" href="image.jpg" data-rsVideo="http://www.youtube.com/watch?v=Eip7JrQ6IdE">This is caption <b>HTML</b> text</a>
<!-- slide with any content -->
<div>
<img class="rsImg" src="image.jpg" data-rsVideo="https://vimeo.com/44878206" />
<p>Some content after...</p>
</div>
</div>Video options:
| Variable | Default Value | Description |
|---|---|---|
| autoHideArrows | true | Auto hide arrows when video is playing |
| autoHideControlNav | false | Auto hide navigation when video is playing. |
| autoHideBlocks | false | Auto hide animated blocks when video is playing. |
| youTubeCode | '<iframe src="https://www.youtube.com/embed/%id%?rel=1&autoplay=1&showinfo=0" allowfullscreen frameborder="no"></iframe>' | Youtube embed code. %id% is replaced by video id. |
| vimeoCode | '<iframe src="https://player.vimeo.com/video/%id%?byline=0&portrait=0&autoplay=1" frameborder="no" allowfullscreen></iframe>' | Vimeo embed code. %id% is replaced by video id. |
If you want to use another video player, please check how to add another player article.
Example of slider with video options:
jQuery(document).ready(function($) {
$(".royalSlider").royalSlider({
// general options go gere
autoScaleSlider: true,
video: {
// video options go gere
autoHideBlocks: true,
autoHideArrows: false
}
});
});All elements inside slide that have class rsABlock will be treated by slider as animated blocks (tag name doesn't matter). Blocks can not be nested, but you can put multiple instances of them into one slide, or make slide itself animated block.
Block examples:
<div class="royalSlider rsDefault">
<!-- image + animated block with text -->
<div class="rsContent">
<img class="rsImg" src="image.jpg" data-rsTmb="small-image.jpg" alt="image description" />
<div class="rsABlock">Block content</div>
</div>
<!-- two animated blocks in one slide -->
<div class="rsContent">
<h2 class="rsABlock">Block content 1</h2>
<p class="rsABlock">Block <b>content</b> 2</p>
</div>
<!-- HTML content + animated block as an image -->
<div class="rsContent">
HTML content...
<img class="rsABlock" src="block-image.jpg" />
</div>
<!-- image + animated block with HTML title and text -->
<div class="rsContent">
<img class="rsImg" src="image.jpg" alt="image description" />
<div class="rsABlock">
<h2>Dummy title</h2>
<p>Dummy text of block with title and text.</p>
</div>
</div>
</div>By default blocks have absolute position and can be positioned with left, right, top or bottom CSS properties. Please note, if you set position to bottom or right, so you need to set top:auto and left:auto;. But you may set position: relative; to them too.
It's not recommended to apply any CSS3 transitions or transforms to element with class rsABlock, but you can style it's child elements however you want. Also, you shouldn't set margin to block in percents or em's, as this property is animated.
Please use animation wisely and minify the number of blocks as much as possible.
Block-specific options:
data-fade-effect="true" // fade effect, can be 'true' or 'false'
data-move-effect="left" // direction of move effect,
// can be 'left', 'right', 'top', 'bottom' or 'none'
data-move-offset="20" // distance of move effect in pixels
data-speed="300" // transition speed of block, in ms
data-delay="400" // delay before block will show up
data-easing="easeOutSine" // animation easing function, read more in easing types sectionExample of using block-specific options:
<div class="rsABlock" data-move-effect="left" data-fade-effect="false">Content</div>Animated blocks global options (overriden by block-specific options):
| Variable | Default Value | Description |
|---|---|---|
| fadeEffect | true | true or false |
| moveEffect | 'top' | Move effect direction. Can be 'left', 'right', 'top', 'bottom' or 'none'. |
| moveOffset | 20 | Distance for move effect in pixels. |
| speed | 400 | Transition speed of block, in ms. |
| easing | 'easeOutSine' | Easing function of block animation. Read more in easing section of docs. |
| delay | 200 | Delay between each block show up, in ms. |
Example of slider with block options:
jQuery(document).ready(function($) {
$(".royalSlider").royalSlider({
// general options go gere
autoScaleSlider: true,
block: {
// animated blocks options go gere
fadeEffect: false,
moveEffect: 'left'
}
});
});Module "reveals" next and previous slides, like in this template. Available since 9.3 version.
| Variable | Default Value | Description |
|---|---|---|
| enabled | true | Enable visible-nearby. |
| centerArea | 0.6 | Ratio that determines area of center image. For example for 0.6 - 60% of slider area will get center image and 20% for two images on sides. |
| center | true | Alignment of center image, if you set it to false center image will be aligned to left. |
| navigateByCenterClick | true | Disables navigation to next slide by clicking on current slide (if navigateByClick is true). |
| breakpoint | 0 | Used for responsive design. Changes centerArea value to breakpointCenterArea when width of slider is less then value in this option. Set to 0 to disable. Should be number. |
| breakpointCenterArea | 0.8 | Same as centerArea option, just for breakpoint. Can be changed dynamically via `sliderInstance.st.breakpointCenterArea`. |
Example of slider with visible nearby images:
jQuery(document).ready(function($) {
$(".royalSlider").royalSlider({
// general options go gere
keyboardNavEnabled: true,
visibleNearby: {
enabled: true,
centerArea: 0.5,
center: true,
breakpoint: 650,
breakpointCenterArea: 0.64,
navigateByCenterClick: true
}
});
});If you wish to add zooming or fading effect to nearby slides, you need to activate addActiveClass option and include active-class module, which adds rsActiveSlide CSS class to current slide. And add these effects using CSS3 transitions, like so:
.royalSlider .rsSlide img {
opacity: 0.45;
-webkit-transition: all 0.3s ease-out;
-moz-transition: all 0.3s ease-out;
transition: all 0.3s ease-out;
-webkit-transform: scale(0.9);
-moz-transform: scale(0.9);
-ms-transform: scale(0.9);
-o-transform: scale(0.9);
transform: scale(0.9);
}
.royalSlider .rsActiveSlide img {
opacity: 1;
-webkit-transform: scale(1);
-moz-transform: scale(1);
-ms-transform: scale(1);
-o-transform: scale(1);
transform: scale(1);
}Please note that such opacity transition here may conflict with fadeInLoadedSlide option, so you should disable it.
By default the slider includes easeOutSine, easeInOutSine and linear easing types. If you want more, you should include jQuery easing plugin royalslider/jquery-easing-1.3.js and add CSS3 functions for it.
Functions for CSS3 easing types are stored in jQuery.rsCSS3Easing variable. You can find cubic-bezier function here.
For example, to add support of easeOutBack:
jQuery.rsCSS3Easing.easeOutBack = 'cubic-bezier(0.175, 0.885, 0.320, 1.275)';Important note: if you bind any custom events to elements in slider, you should do this before initialization or using event delegation, as slider doesn't keep all slides in DOM at once (to save memory).
You can easily override any function without modifying slider code (even "private") by extending slider prototype. Learn more.
Public methods:
// All public methods can be called jQuery-way - $(".royalSlider").royalSlider('startAutoPlay');
// Another example: $(".royalSlider").royalSlider('goTo', 3);
// But it's recommended to get instance once if you have many calls:
// You can get slider instance from royalSlider data:
var slider = $(".royalSlider").data('royalSlider');
slider.goTo(3); // go to slide with id
slider.next(); // next slide
slider.prev(); // prev slide
slider.destroy(); // removes all events and clears all slider data
// use on ajax sites to avoid memory leaks
// Dynamic slides adding/removing
// More info in Javascript API section of support desk - http://dimsemenov.com/private/forum.php
slider.appendSlide( HTML_jQuery_object, index(optional) );
slider.removeSlide( index(optional) );
slider.updateSliderSize(); // updates size of slider. Use after you resize slider with js.
slider.updateSliderSize(true); // Function has "forceResize" Boolean paramater.
// Thumbnails public methods
slider.setThumbsOrientation('vertical'); // changes orientation of thumbnails
slider.updateThumbsSize(); // updates size of thumbnails
// Fullscreen public methods
slider.enterFullscreen();
slider.exitFullscreen();
// Autoplay public methods
slider.startAutoPlay();
slider.stopAutoPlay();
slider.toggleAutoPlay();
// Video public methods
slider.toggleVideo();
slider.playVideo();
slider.stopVideo();Public properties:
slider.currSlideId // current slide index
slider.currSlide // current slide object
slider.numSlides // total number of slides
slider.isFullscreen // indicates if slider is in fullscreen mode
slider.nativeFS // indicates if browser supports native fullscreen
slider.width // width of slider
slider.height // height of slider
slider.dragSuccess // Boolean, changes on mouseup, indicates if slide was dragged. Used to check if event is drag or click.
slider.slides // array, contains all data about each slide
slider.slidesJQ // array, contains list of HTML slides that are added to slider
slider.st // object with slider settings
slider.ev // jQuery object with slider eventsEvents:
// In each listener event.target is slider instance
slider.ev.on('rsAfterSlideChange', function(event) {
// triggers after slide change
});
slider.ev.on('rsBeforeAnimStart', function(event) {
// before animation between slides start
});
slider.ev.on('rsBeforeMove', function(event, type, userAction ) {
// before any transition start (including after drag release)
// "type" - can be "next", "prev", or ID of slide to move
// userAction (Boolean) - defines if action is triggered by user (e.g. will be false if movement is triggered by autoPlay)
});
slider.ev.on('rsBeforeSizeSet', function(event) {
// before size of slider is changed
});
slider.ev.on('rsDragStart', function(event) {
// mouse/touch drag start
});
slider.ev.on('rsDragRelease', function() {
// mouse/touch drag end
});
slider.ev.on('rsBeforeDestroy', function() {
// triggers before slider in destroyed
});
slider.ev.on('rsOnCreateVideoElement', function(e, url) {
// triggers before video element is created, after click on play button.
// Read more in Tips&Tricks section
});
slider.ev.on('rsSlideClick', function(event, originalEvent) {
// originalEvent - the original jQuery click event. Parameter available since RoyalSlider v9.5.1
// triggers when user clicks on slide
// doesn't trigger after click and drag
});
slider.ev.on('rsEnterFullscreen', function() {
// enter fullscreen mode
});
slider.ev.on('rsExitFullscreen', function() {
// exit fullscreen mode
});
slider.ev.on('rsVideoPlay', function() {
// video start
});
slider.ev.on('rsVideoStop', function() {
// video stop
});
slider.slides[2].holder.on('rsAfterContentSet', function() {
// fires when third slide content is loaded and added to DOM
});
// or globally
slider.ev.on('rsAfterContentSet', function(e, slideObject) {
// fires when every time when slide content is loaded and added to DOM
});
// Next events TRIGGER DIRECTLY ON SLIDER INITIALIZATION
// if you bind them after slider init they'll not fire
// used for module development
slider.ev.on('rsAfterInit', function() {
// after slider is initialized,
});
slider.ev.on('rsBeforeParseNode', function(e, content, obj) {
// before slide node is parsed
// content - HTML object of slide that is parsed
// obj - RoyalSlider data object (stores image URLs)
});If you don't know where to put code that relies on slider instance in WordPress version, check this guide.
Tips & Tricks section moved to knowledge base, I recommend starting from Slider Performance Tips article.
If you've found a mistake in documentation or something isn't working as it should (any bug, lag, blink) - please open support ticket or just email me. You may also follow me on Twitter to get notified about important plugin updates.
Thank you!