Skip to content

Latest commit

 

History

History
320 lines (312 loc) · 14.6 KB

README.md

File metadata and controls

320 lines (312 loc) · 14.6 KB
Raw

Swiper - Mobile touch slider with hardware accelerated transitions

About

Swiper - is the free and ultra lightweight mobile touch slider with hardware accelerated transitions (where supported) and amazing native behavior. It is intended to use in mobile websites, mobile web apps, and mobile native apps. Designed mostly for iOS, but also works on Android and latest Desktop browsers. Swiper is created by iDangero.us

Change Log

Swiper 1.3 - Updated on April 15, 2012

  • External functions swipeNext, swipePrev, swipeTo now return true or false.
  • .previousSlide property returns the index of previously displayed slide
  • Added onSlideInitialize callback

Swiper 1.3 - Updated on April 2, 2012

  • Added onSlideChangeStart callback
  • Added onSlideReset callback
  • onSlideChange is renamed to onSlideChangeEnd
  • Now .swipeTo() method accepts 3 parameters - index (number), speed (number) and runCallbacks (boolean)
  • Now .swipeTo() method will produce 'onSlideChangeStart' and 'onSlideChangeEnd' callback functions (if "runCallbacks" is not equal to "false")
  • New mySwiper.destroy() method to release all events assigned by Swiper
  • Fixed serious bug when using fluid (responsive) Swiper to re-calculate slides' position on window resize

Swiper 1.2 - Updated on March 31, 2012

  • Improved mouse events to get the same behaviour as on touch devices

Swiper 1.1 - Updated on March 18, 2012

  • Added autoPlay parameter to enable auto play
  • mySwiper.startAutoPlay() - external function to start auto play
  • mySwiper.startAutoPlay() - external function to stop auto play
  • Optimized for usage as a fallback for upcoming "iDangero.us S6" 3D slider
  • Added small plugin to use Swiper with Zepto.js

Swiper 1.0 - Initial release on March 15, 2012

Demos

http://www.idangero.us/sliders/swiper/

Features

  • 1:1 Touch movement. But this ratio can be configured

  • Touch emulation. This function will be useful if you are going to use Swiper on desktop sites. In this case Swiper will accept mouse events like touch events (click and drag to change slides)

  • Vertical/Horizontal. Swiper comes with 2 main modes - horizontal (for horizontal animation and horizontal swipes) and vertical (for vertical animation and vertical swipes)

  • Free Mode. When this mode enabled slides will not have fixed positions, like usual scroller (see demos bellow)

  • Auto Play. Just set the delay and Swiper will change the slides automatically untill you touch it

  • Rotation/resize adjustment. Swiper will be reinitialized after rotation of device

  • Responsive. Can be used with a width or/and height defined in percents, not fixed. Useful for usage on devices with a different resolutions

  • Scroll prevention. Swiper will prevent vertical scroll when you touch it in "horizontal" mode, and horizontal scroll in "vertical" mode

  • Resistant bounds. Swiper will increase resistance when you try to swipe it over than most left and most right positions (most top and most bottom for "vertical" mode)

  • Built-in pagination control. Can be disabled

  • Any HTML. You can put any HTML content inside of slide, not only images

  • Rich API. Swiper comes with very rich API. It allows to create your own pagination, "next" and "previous" buttons and comes with 7 callbacks - onTouchStart, onTouchMove, onTouchEnd, onSlideReset, onSlideChangeStart, onSlideChangeEnd, onSlideInitialize.

  • Flexible configuration. Swiper accepts a lot of parameters on initialization to make it much flexible as possible. You can configure animation speed, mode (vertical or horizontal), free mode, enable/disable pagination, touch ratio, etc.

  • Good compatibility. Swiper compatible and tested with: Mobile Safari (tested on iOS5), Android 2.1+, latest desktop versions of Google Chrome, Safari, Firefox and Opera

  • Standalone. Swiper doesn't require any JavaScript libraries like jQuery, it makes Swiper much more smaller and faster.

  • Ultra lightweight. Only 2.3 KB minified and gzipped

Usage

1. Download the latest version of Swiper from GitHub here.

2. Add to HEAD Swiper's CSS and JS:

<head>
  ....
  <link rel="stylesheet" href="path_to_css/idangerous.swiper-1.0.css">
  <script defer src="path_to_js/idangerous.swiper-1.3.min.js"></script>
  ....
</head>

3. Use the following HTML layout: 

<div class="swiper-container">
  <div class="swiper-wrapper">
      <!--First Slide-->
      <div class="swiper-slide">
        <!-- Any HTML content of the first slide goes here -->
      </div>

  <strong>&lt;!--Second Slide--&gt;</strong>
  &lt;div class=&quot;swiper-slide&quot;&gt;
    <wm>&lt;!-- Any HTML content of the second slide goes here --&gt;</wm>
  &lt;/div&gt;
  
  <strong>&lt;!--Third Slide--&gt;</strong>
  &lt;div class=&quot;swiper-slide&quot;&gt;
    <em>&lt;!-- Any HTML content of the third slide goes here --&gt;</em>
  &lt;/div&gt;
  &lt;!--Etc..--&gt;



</div>
</div>

4. Open idangerous.swiper-1.0.css and set the Swiper's width and height (in the end of the file):

...
/* Specify Swiper's Size: */
.swiper-container, .swiper-slide {
	width: 500px;
	height: 200px;
}

5. Initialize Swiper on document ready (or when window is loaded):

<script type="text/javascript">
//Use document ready or window load events
// For example:
// With jQuery / Zepto: $(function() { ...code here... })
// Or window.onload = function() { ...code here ...}
// Or document.addEventListener('DOMContentLoaded', function(){ ...code here... }, false)

window.onload = function() {
var mySwiper = new Swiper('.slider-container',options);
//Or with jQuery or Zepto
var mySwiper = $('.slider-container').swiper(options);
}
</script>

API

new Swiper(container, options)

  • container - string, required. CSS selector of Swiper's container. In the HTML code above it should be equal to '.swiper-container'

  • options - object, optional. Swiper parameters, see bellow

**Usage:**

var mySwiper = new Swiper('.swiper-container')

Returns the object with couple of useful functions and methods:

  • mySwiper.swipeNext() - run transition to next slide. returns true/false.

  • mySwiper.swipePrev() - run transition to previous slide. returns true/false.

  • mySwiper.swipeTo(index, speed, runCallbacks) - run transition to the slide with index number equal to 'index' parameter for the speed equal to 'speed' parameter. You can set 'runCallbacks' to false (by default it is 'true') and transition will not produce onSlideChange(Start/End) callback functions.

  • mySwiper.isSupportTouch() - returns true if browser supports Touch events

  • mySwiper.isSupport3D() - returns true if browser supports CSS3 3D transforms

  • mySwiper.activeSlide - returns the index number of currently active slide

  • mySwiper.previousSlide - returns the index number of previously displayed slide

  • mySwiper.startAutoPlay() - start auto play. It may be useful for custom "Play" and "Pause" buttons.

  • mySwiper.stopAutoPlay() - stop auto play. It may be useful for custom "Play" and "Pause" buttons.

  • mySwiper.destroy(removeResizeEvent) - will remove all attached event listeners (resize event on window (if removeResizeEvent not equal to 'false') , touch events on wrapper, and mouse events on document). Useful if you add/remove swiper(s) to document dynamically to release browser's memory.

Options

Swiper support the following list of parameters on initialization:

Parameter Type Default Value Example Description
speed number 300 600 duration of animation between slides (in ms)
autoPlay number 5000 - delay between transitions (in ms). If this parameter is not specified, auto play will be disabled
mode string 'horizontal' 'vertical' slides will be positioned horizontally (for horizontal swipes) or vertically (for vertical swipes)
freeMode boolean false true If 'true' then slides will not have fixed positions
freeModeFluid boolean false true If true, then if you release the slide it will keep moving for a while
ratio number 1 0.8 Touch ratio
simulateTouch boolean true false If true, Swiper will accept mouse events like touch events (click and drag to change slides)
onlyExternal boolean false true If true, then the only way to switch the slide is use of external API functions like swipeRight or swipeLeft. Useful for tabs like in example above
followFinger boolean true false If false, then slider will be animated only when you release it, it will not move while you hold your finger on it
pagination string - '.my-pagination' CSS selector of the container with pagination.
createPagination boolean true false if true, then Swiper will create as many SPAN element as many slides in slider. All these spans will be created in the container specified in the "pagination" parameter. Every SPAN will have a 'swiper-pagination-switch' class, active span (of the current slide) will have a 'swiper-active-switch' class. They will be useful for styling them.
wrapperClass string 'swiper-wrapper' 'my-wrapper' CSS class of the Swiper's wrapper. See the HTML demo above
paginationClass string 'swiper-pagination-switch' 'my-switch' CSS class of the Swiper's pagination switch
paginationActiveClass string 'swiper-active-switch' 'my-active-switch' CSS class of the active Swiper's pagination switch
onTouchStart function - function(){ do something } Callback function, will be executed when you touch the slider
onTouchMove function - function(){ do something } Callback function, will be executed when you touch and move finger over the slider
onTouchEnd function - function(){ do something } Callback function, will be executed when you release the slider
onSlideReset function - function(){ do something } Callback function, will be executed when you release the slide and it going to be reseted to currently active slide. Don't work with freeMode.
onSlideChangeStart function - function(){ do something } Callback function, will be executed in the beginning of animation to other slide (next or previous). Don't work with freeMode.
onSlideChangeEnd function - function(){ do something } Callback function, will be executed after animation to other slide (next or previous). Don't work with freeMode. Changed name from "onSlideChange" to "onSlideChangeEnd" in 1.3
onSlideInitialize function - function(mySwiper, slide) { do something } Callback function, will be executed when init() is run. Note that this callback is executed for each slide elements.

Example

<script type="text/javascript">
$(document).ready(function(){
  var mySwiper = new Swiper('.swiper-container', {
    mode : 'vertical', //Switch to vertical mode
    speed : 500, //Set animation duration to 500ms
    freeMode : true, //Enable free mode
    freeModeFluid : true, //Enable 'fluid' free mode
    onTouchStart : function() {
      alert('OMG you touch the slide!') //Do something when you touch the slide
    }
  }
})
</script>

License

Swiper is licensed under GPL & MIT