Extending Unslider

Despite being small, Unslider is very flexible and extensible: you can change pretty much anything via options/settings, methods or callback events - all of which are documented below.

Automatic support

Unslider automatically supports a few different scripts, provided the <script> tag is referenced before Unslider.

Right-to-left (RTL) support

Just add dir="rtl" and Unslider will change the slide direction if needed.

<div class="my-slider" dir="rtl"></div>

Velocity.js visit site

A faster alternative to jQuery's .animate(). If you find your sliders are looking a bit sluggish, it's highly recommended to add Velocity, as it can make a marked improvement.

<script src="//cdn.jsdelivr.net/velocity/1.2.3/velocity.min.js"></script>

jquery.swipe.js visit site

Add swipe support for mobile and desktop to your sliders. See the initSwipe and destroySwipe methods below for more info on how this works.

<script src="//stephband.info/jquery.event.move/js/jquery.event.move.js"></script>
<script src="//stephband.info/jquery.event.swipe/js/jquery.event.swipe.js"></script>

Methods

Unslider has a handful of methods you can use to control your slider and two ways you can use these methods, as shown below.

//  Assuming we've got a variable set like this...
var slider = $('.my-demo-slider').unslider();

// Method 1
slider.data('unslider').methodName();
slider.data('unslider').methodName('arguments', 'go', 'here');

// Method 2 (the shorthand version)
slider.unslider('methodName');
slider.unslider('methodName:arguments,go,here');

init args: options

Set everything up with the slider. This is called automatically when you set up .unslider() for the first time, but if there's layout problems or you want to re-initiate the slider for some reason, you can call it here. The options variable is an object (see below). You can't call options with the shorthand .unslider('init') method.

calculateSlides

If a slide gets added or removed, you should call this otherwise things'll probably break.

var slider = $('.my-slider').unslider();

// I don't like this last slide, let's get rid of it
slider.find('li:last').remove();

// Let's recalculate Unslider so it knows what's going on
slider.unslider('calculateSlides');

start

Make the slider move itself between slides. Will use the options object to determine the delay between slides.

stop

Stop the slider moving itself between slides. Will stop any auto-playing.

destroyKeys

Remove any keyboard shortcut handlers for the slider.

initKeys

Manually add keyboard shortcut support. Can be used after destroyKeys to restore keyboard shortcut support, or with {keys: false} in the options object to add support later on.

initSwipe

Set up swipe functionality manually (i.e if you want to defer loading). You can add it automatically by including jquery.event.move and jquery.event.swipe in your code. If you need to add it after page load, you can call initSwipe, like so:

$('.sliderman').unslider();

//  Let's say we want to use $.getScript to load our scripts for some reason
var scripts = [
	'http://stephband.info/jquery.event.move/js/jquery.event.move.js',
	'http://stephband.info/jquery.event.swipe/js/jquery.event.swipe.js'
];

$.getScript(scripts[0]);

//  Once our script is loaded, we can initSwipe to add swipe support
$.getScript(scripts[1], function() {
	$('.sliderman').unslider('initSwipe');
});

destroySwipe

Remove swipe support. Does what it says on the tin.

setIndex args: to

Set the current index and navigation for Unslider. This doesn't move the slider! You can get some goofy results doing this - if you want to move the slider to a specific slide, I'd recommend you use animate() instead.

The argument to can be an integer with the index of the slide you want to set (remember: indexes start at zero!), or the strings 'first' or 'last' if you don't know how many slides there are.

animate args: to, dir

Move the slider to a specific slide, update any navigation and fire a unslider.change event. Use like so:

//  Our trusty slider!
var slider = $('.slider').unslider();

//  Move to the first slide
slider.unslider('animate:first');

//  Move to the third slide
//  Remember, slides are zero-indexed so 0 is first slide, 1 is second, etc.
slider.unslider('animate:2');

//  Move to the last slide
slider.unslider('animate:last');

//  Move to the last slide and add a direction
slider.unslider('animate:last,prev');

The argument to is required and can be an integer with the index of the slide you want to set (remember: indexes start at zero!), or the strings 'first' or 'last' if you don't know how many slides there are.

The argument dir is optional and can either be the string 'prev' or 'next'. This doesn't do anything, yet.

next

Manually move to the next slide (or the first slide if you reach the last slide).

prev

Same thing as .unslider('next') but in the other direction. Moves the slider backwards manually or to the last slide if there's no more behind it.

Events

Unslider triggers some event listeners which might be handy for whatever reason, I guess.

//  Set up our slider to automatically move every second so we can see what's happening
var slider = $('.slider').unslider({ autoplay: true, delay: 1000 });

//  When the slider has been set up, fire the event off.
slider.on('unslider.ready', function() {
	alert('Slider is set up!');
});

//  Listen to slide changes
slider.on('unslider.change', function(event, index, slide) {
	alert('Slide has been changed to ' + index);
});

Options

Unslider uses a standard jQuery plugin options object, which looks like the highlighted example below:

$('.my-demo-slider').unslider({
	settingName: settingValue,
	anotherSetting: anotherValue
});

It's not required to have any of these options set — you can leave these all blank and they'll fall back to the defaults highlighted in the table below.

autoplay default: false

Should the slider move by itself or only be triggered manually?

speed default: 750

How fast (in milliseconds) Unslider should animate between slides.

delay default: 3000

If autoplay is set to true, how many milliseconds should pass between moving the slides?

index default: 'first'

If this is set to an integer, 'first' or 'last', it'll set the default slide to that position rather than the first slide.

keys default: true

Do you want to add keyboard shortcut support to Unslider? This can be set to either true, false, or an options/keycode object, like so:

keys: {
	prev: 37,
	next: 39,
	stop: 27 //  Example: pause when the Esc key is hit
}

This can be useful if you want to extend the functionality built-in to Unslider.

nav default: true

Do you want to generate an automatic clickable navigation for each slide in your slider?

You can over-ride what appears in each link by adding a data-nav="nav title" parameter to each slide element (replacing 'nav title' with whatever you'd like the title to be).

If you want to add dot-navigation to a slide, simply include unslider-dots.css to your CSS file.

New You can also provide a function to calculate the slide label:

nav: function(index, label) {
	//  $(this) is the current index slide
	//  label is the current label
	//  index is the slide index, starting at 0

	//  On the third slide, append " third slide!"
	if(index === 2) {
		return label + ' third slide!';
	}

	//  Only show the number
	return index + 1;
}

arrows default: true

Do you want to add left/right arrows to your slider? You can style these in your CSS by writing rules for .unslider-arrow (or alternatively you can change the HTML string to whatever you like and style that).

This can be set to either true, false, or an options object. If you set an options object, the default behaviour will be overwritten. The default object looks like this:

arrows: {
	//  Unslider default behaviour
	prev: '<a class="unslider-arrow prev">Previous slide</a>',
	next: '<a class="unslider-arrow next">Next slide</a>',

	//  Example: generate buttons to start/stop the slider autoplaying
	stop: '<a class="unslider-pause" />',
	start: '<a class="unslider-play">Play</a>'
}

This option is a bit of a misnomer, as you can set it to generate anything, not just arrows.

animation default: 'horizontal'

How should Unslider animate each slide? Right now, there's three different animation types:

1. 'horizontal', which moves the slides from left-to-right
2. 'vertical', which moves the slides from top-to-bottom
3. 'fade', which crossfades slides

selectors

If you're not using an unordered list to display your slider, you'll need to add a selectors object referencing what elements Unslider should look for. The container should be the "conveyor belt" that gets moved, and the slides are - well - the slides.

selectors: {
	container: 'ul:first',
	slides: 'li'
}

Note: you'll probably also need to update/write custom CSS in order for Unslider to work. Check the source files for unslider.less to get a better idea of what needs styling.

animateHeight default: false

Should Unslider animate the height of the container to match the current slide's height? If so, set to true.

activeClass default:
'unslider-active'

What class should Unslider set to the active slides and navigation items? Use this if you want to match your CSS.

infinite default:
false

Make the slides loop infinitely; when they reach the end, they won't slide back to the start but will continue sliding in the same direction.

noloop default:
false

The opposite of infinite: true, this will stop the slider looping around at all. Will not work if infinite is set.