Documentation for v9.5.1+changelog

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.

Basic Usage

1. Upload royalslider folder to your server and add the required files in your page (usually in the head section). Use the online build tool to optimize your slider build and create the main JS file (royalslider.js).

<!-- 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.7+  -->
<!-- If you already have jQuery on your page, you shouldn't include it second time. -->
<script src='royalslider/jquery-1.8.3.min.js'></script>

<!-- Main slider JS script file --> 
<!-- Create it with slider online build tool for better performance. -->
<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;
}

Basically, to make it responsive (scale height based on width), all you need is to apply `autoScaleSlider` options.

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.

Images

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 strong recommended to view this article to learn more about this feature.

Options

Variable Default Value Description
autoScaleSlider false Automatically updates slider height based on base width.
autoScaleSliderWidth 800 Base slider width. Slider will autocalculate the ratio based on these values.
autoScaleSliderHeight 400 Base slider height
imageScaleMode 'fit-if-smaller' Scale mode for images. "fill", "fit", "fit-if-smaller" or "none". Learn more.
imageAlignCenter true Aligns image to center of slide.
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.

Caption

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.

Thumbnails & tabs

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({
    	// general options go gere
    	autoScaleSlider: true,
    	thumbs: {
    		// thumbnails options go gere
    		spacing: 10,
    		arrowsAutoHide: true
    	}
    });  
});

Fullscreen

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

Deep linking module makes URL automatically change when you switch slides and you can easily link to specific slide (aka permalink). Options:

Variable Default Value Description
enabled false Linking to slides by appending #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 '' Prefix that will be added to hash. For example if you set it to 'gallery-', hash would look like this: #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

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>

Video

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="http://www.youtube.com/embed/%id%?rel=1&autoplay=1&showinfo=0" frameborder="no"></iframe>' Youtube embed code. %id% is replaced by video id.
vimeoCode '<iframe src="http://player.vimeo.com/video/%id%?byline=0&amp;portrait=0&amp;autoplay=1" frameborder="no" webkitAllowFullScreen mozallowfullscreen 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
    	}
    });  
});

Animated blocks

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 section

Example 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'
    	}
    });  
});

Visible-nearby

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.

Easing

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)';

API

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 events

Events:

// 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

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!