Skip to content

Latest commit

 

History

History
266 lines (256 loc) · 10.7 KB

README.md

File metadata and controls

266 lines (256 loc) · 10.7 KB

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

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)

  • 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 4 callbacks - onTouchStart, onTouchMove, onTouchEnd, onSlideSwitch

  • 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.0.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: $(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
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

  • mySwiper.swipePrev() - run transition to previous slide

  • mySwiper.swipeTo(index) - run transition to the slide with index number equal to number argument

  • 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

"options"

Swiper support the following list of parameters on initialization:

</tbody>
Parameter Type Default Value Example Description
speed number 300 600 duration of animation between slides (in ms)
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.
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
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-wrapper' 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
onSlideSwitch function - function(){ do something } Callback function, will be executed after the animation to other slide (next or previous). Don't work with freeMode

Example

<script type="text/javascript">
$(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