/Peppermint

Peppermint touch slider

Primary LanguageJavaScript

#Peppermint touch slider

Note: This is a fork of https://github.com/wilddeer/Peppermint with support for dots and slideshow removed, and also some additional callbacks added.

Check out the demo

Yet another touch slider. Only better.

  • Works with mouse, Touch Events, Pointer Events, old IE10 Pointer Events
  • Responsive, works on iPhones, Androids, Windows Phones, Blackberries, Windows 8 devices
  • IE7+ compatible
  • Library agnostic. If jQuery is available, registers itself as a plugin.
  • Uses CSS3 transforms & animations, falls back to timer animations when necessary
  • Only 7.7 Kb minified
  • Perfomance-optimized touch functions
  • API and callback functions for extensibility
  • Doesn't break when tab’bing

##Kit

Also available in Bower:

bower install Peppermint --save

##Usage

HTML markup:

<div class="peppermint peppermint-inactive" id="peppermint">
  <figure> ... </figure>

  <figure> ... </figure>

  <figure> ... </figure>
</div>

Javascript:

var slider = Peppermint(document.getElementById('peppermint'));

Or javascript + jQuery:

$('.peppermint').Peppermint();

peppermint-inactive class is not required. It is replaced with peppermint-active during setup.

You are free to use any other tag instead of figure. When using figure, don't forget to include html5shiv, otherwise it won't work in old IEs.

Place anything you want within the slides.

##Settings

Peppermint can take settings object as an optional second parameter (first when using jQuery). Default settings:

{
  //transition time when changing slides, ms
  speed: 300,

  //transition time when changing slides after touch, ms
  touchSpeed: 300,

  //slide number to start with
  startSlide: 0,

  //use mouse to drag the slider
  mouseDrag: true,

  //don't initialize Peppermint if there's only one slide
  disableIfOneSlide: true,

  //Prefix to be used with Peppermint classes,
  //such as `inactive`, `active`, `mouse`, `drag`, etc.
  //Don't forget to change the stylesheet appropriately!
  cssPrefix: 'peppermint-',

  //element containing slides, defaults to Peppermint's root element
  slidesContainer: undefined,

  //set the slideContainer height as a ratio of it's width
  slideHeightRatio: undefined,

  //set slideWidth to a width (in pixels) to make Peppermint fit in as many complete slides on as possible.
  //Can be useful for responsive designs.
  //Use the keyword 'full' to make Peppermint resize each slide to the full width of the slider.
  slideWidth: undefined,

  //Callback function, called if the user swipes, but the slide change isn't triggered.
  //Receives the touch end / mouse up event as a parameter.
  //This can be used to handle cases where the user wanted to touch / click the slide without swiping.
  onIncompleteSwipe: undefined,

  //Callback function, runs just before slide change
  //Receives previous and new slide numbers as parameters,
  //and 2 parameters indicating if the slider cannot be paged forwards or backwards.
  //Designed to allow previous / next buttons to be disabled.
  beforeSlideChange: undefined,

  //Callback function, runs at slide change.
  //Receives slide number as a parameter.
  //Note: This event is executed as the transition animation is playing,
  //so may cause jank if it causes layout changes, or is CPU intensive.
  onSlideChange: undefined,

  //Callback function, runs at the end of the css transition.
  //Receives slide number as a parameter.
  //Note: This can be used for functions which cause layout changes,
  //or changes that should not be performed when the transition animation is playing.
  onTransitionEnd: undefined,

  //Callback function, runs at setup end.
  //Receives total number of slides as a parameter.
  onSetup: undefined
}

####Examples

JS:

var slider = Peppermint(document.getElementById('peppermint'), {
  speed: 500,
  onSetup: function(n) {
    console.log('Peppermint setup done. Slides found: ' + n);
  }
});

JS + jQuery:

$('.peppermint').Peppermint({
  speed: 500,
  onSetup: function(n) {
    console.log('Peppermint setup done. Slides found: ' + n);
  }
});

##API

Peppermint exposes a set of functions upon installation. These functions can be used to control the slider externally:

slideTo(n) – change active slide to n;

slideTo(n, speed) – change active slide to n with transition speed in ms. Passing a speed of 0 disables the transition;

next() – next slide;

prev() – previous slide;

getCurrentPos() – get current slide number;

getSlidesNumber() – get total number of slides;

recalcWidth() – recalculate slider's and slides' widths. Usefull when the container width is changed. Width recalculation runs automatically on window resize and device orientation change.

####Examples

JS:

//init Peppermint and save the API object
var slider = Peppermint(document.getElementById('peppermint')),
    //save links to HTML nodes
    rightArr = document.getElementById('right-arr'),
    leftArr = document.getElementById('left-arr'),
    getSlidesNumberButton = document.getElementById('getslidesnumber');

//click `#right-arr` to go to the next slide
rightArr.addEventListener('click', slider.next, false);

//click `#left-arr` to go to the previous slide
leftArr.addEventListener('click', slider.prev, false);

//click `#getslidesnumber` to alert total number of slides
getSlidesNumberButton.addEventListener('click', function() {
  alert('There are ' + slider.getSlidesNumber() + ' slides');
}, false);

JS + jQuery:

//save jQuery link to slider's block
var slider = $('#peppermint');

//init Peppermint
slider.Peppermint();

//click `#right-arr` to go to the next slide
$('#right-arr').click(slider.data('Peppermint').next);

//click `#left-arr` to go to the previous slide
$('#left-arr').click(slider.data('Peppermint').prev);

//click `#getslidesnumber` to alert total number of slides
$('#getslidesnumber').click(function() {
    alert('There are ' + slider.data('Peppermint').getSlidesNumber() + ' slides');
});

##Using Peppermint?

Drop me a link → ✉️ wd@dizaina.net.

##License

MIT license.