> SwipeView

swipeview-icon

SwipeView is the super simple solution to endless seamlessly loopable carousels for the mobile browser. It’s memory conservative as it uses only three elements at any given time, it’s smooth as velvet since it takes advantage of hardware acceleration, it’s bandwidth friendly with its 1.5kb minified/gzipped footprint.

Project info

Last code update: 2012.08.25 – v1.0
Device compatibility: Safari, Firefox, Opera, iPhone/Ipod touch >=4.x, iPad >=3.2, Android >=2.3
QR Code opens demo page.

Support development

If this script saved your day and you wish to support future developments you may consider sending some funds via PayPal or Flattr.





Overview

Due to memory constraints and limited resources, endless –or very long– carousels are problematic on the mobile browser. A common trick is to use only three switching master pages. Once the user swipes right the first element to the left is placed at the end of the row, the content inside the switched element is cleared and filled with new data. This way you get a virtually infinite loop. The viewport always shows the middle master page, while the pages to the left and right are used as buffer.

On desktop this page switching is so fast that you don’t need to take care of any special issues, on mobile things are a little more complicated.

First of all, any connection to the server –no matter how fast is the connection or small the data to download– interferes with hardware animations. This means that data must be fetched when no animations are executing.

Secondly, the elements repositioning needed by this technique causes little glitches to the mobile engine.

The following is my solution:

The slider is the DIV which takes care of the main pan/slide effect and therefore is animated in the hardware layer. The element position is set with transform:translate3d(x,0,0). When you swipe what is actually moving is the slider.

As soon as the finger is released (touchend), the switching pages are rearranged to meet the new location but the new content is not loaded. Only when the slide animation ends or the user stops swiping the new content is fetched and placed inside the pages.

This technique brings 4 key benefits: 1) the animation is smooth and doesn’t lag waiting for new contents to be loaded; 2) the hasty user can swipes very quickly, if a page is not ready a “loading” indicator can be shown; 3) content is loaded only when needed, if you quickly swipe from page 1 to page 10, pages in between are ignored (namely 3-4-5-6-7-8, boundaries pages 2 and 9 are kept as buffer); 4) we don’t need to reset the viewport position at each swipe (no flickering).

You’ll notice that the slider is indefinitely slided in both directions. This leads of course to a minor drawback: there’s a limit to the amount of panning (I cannot position over 134,217,726px). It’s in the order of 420,000 swipes per side, so you can freely swipe 416 times the entire The Lord or the Rings. Please note that this NOT the maximum number of swipes you can perform, but rather the distance you can travel in one direction (eg: you can swipes 420,000 times to the right and then other 840,000 to the left).

How to use it

The demo page contains an application example built on SwipeView. You can also place inline horizontal carousels that do not interfere with the default vertical scroll.

Please note that now SwipeView is completely general purpose (ie: not just for image galleries). I’ve set up a rudimentary e-reader to prove it.

Follow me Twitter if you wish to receive script updates (I’m often too lazy to update the blog).

More detailed documentation will follow when APIs consolidate, in the meanwhile I suggest you to have a look at the source and enjoy the show (it’s pretty straightforward I believe).

Future development

Suggestions are very much welcomed, especially in this preliminary phase. If there will be enough interest I’ll keep updating the script.

  • Add custom events and callbacks
  • Make it general purpose (not just for galleries)
  • Widen device compatibility

/Share the joy

/Reactions

    • Author: fab
    • Posted on: 2012/01/10
    • At: 16:11

    Hi! very good job.
    quick question: is the “Add custom events and callbacks” present in your last release? And what’s the difference between OnFlip, OnMoveIn and OnMoveOut ?
    what I’d like to do is to call an ajax function (the content won’t be preloaded) each time I swipe on left or right.

    thanks!

    • yes, the latest version has some custom events. onFlip is called on page flip.

        • Author: N. Manoj
        • Posted on: 2012/01/26
        • At: 03:52

        Hi Matteo,
        This is great, thanks for the hard work.
        I’m also looking into loading pages using ajax, but what my problem is when the user swipes the pages faster onFlip is not called. I try using onMoveOut listener but it don’t updates the data-page-index. Can we get this fixed? Also onFlip is called always if I slightly move the page but not flip.
        Again, thank you very much for this util..

    • Author: MRRAY
    • Posted on: 2012/01/12
    • At: 19:14

    Love it! Thanks so much for your effort. Question: any chance this will be ported into a jQuery plugin? Or perhaps even jQM?

    • Author: Nigel Severing
    • Posted on: 2012/01/17
    • At: 09:14

    Hello Matteo,

    Is there a solution already for the swipeview inside a jquerymobile page? Looks like jquerymobile is blocking something..

    Thanks for all ya great job
    -Nigel

    • it must be a very simple fix, I’ll have a look at it sooner or later.

        • Author: Deepak
        • Posted on: 2012/01/20
        • At: 01:49

        Really great work with swipeview js. Works like a charm. However, I am also having issues with swipeview and jquery mobile page and getting them to play well together. Any help here is appreciated.

        Thanks,
        Deepak

        • Author: Donat
        • Posted on: 2012/01/26
        • At: 10:59

        I finally switched the iScroll 4. This has no problems with jQuery Mobile. The snap mode works like a charm fpr making caroussels. However, the light weight of Swipeview would make me switch back…

        • Author: thomas
        • Posted on: 2012/02/13
        • At: 05:16

        I’m using the latest version of jQm and SwipeView is working beautifully.

        As an aside — I’ve noticed a slight delay before the end transition takes effect (even on the demo pages). I added a debounced call to __checkPosition at the end of __move after 50ms, which cleaned it up.

        Anyway, thank you so much for releasing this –

    • Author: xzed
    • Posted on: 2012/01/21
    • At: 11:37

    nice,
    but I usually need one solution for all modern browsers, so at least it should also work on FireFox.

    • You can use iscroll (another fine project of Matt) in conjunction with swipeview.
      With a Browser Switch you can load either swipeview, when the UA is safari or chrome, or load iscroll for all other UA’s.

      @Matt: Are you planning to integrate other Browser support into swipeview?

    • Author: Justin
    • Posted on: 2012/01/23
    • At: 05:33

    This is really, really, really useful. Testing it out on a super-secret and super-awesome project. I’ll let you know if it makes the cut.

    • Author: N. Manoj
    • Posted on: 2012/01/26
    • At: 03:56

    Hi Matteo,
    This JS library is really helping me out on a important project I’m working on.
    I’m trying to load pages of different sizes using ajax when user swipes. Right now I scale down the pages using webkitTransform and align in the center to fit the page. But some pages are big and user really wants to zoom and pan. How hard is to integrate such changes from iScroll into this one?
    Thanks

    • it’s not horribly complicated. It’s in my to-do actually, but don’t ask ETA :)

    • Author: Anthony
    • Posted on: 2012/01/31
    • At: 00:07

    Hi,

    I want to use a goToPage function, it’s possible ? How to ?

    Great work !

    Thanks and sorry for my english.

      • Author: Anthony
      • Posted on: 2012/01/31
      • At: 00:28

      Sorry, i want just choose the start slide (send by GET).

      Like “selected” in a HTML.

  • Hi Matt,

    Great library. I am facing a problem though. When I change some of the other DIVs on the page, the Swipeview stops working. It shows the first slide, but the touch events does not fire. Any idea.

    Cheers,
    Vikrant

    • impossible to say without looking at the code

    • Author: coolest
    • Posted on: 2012/02/01
    • At: 17:45

    Hi Matteo,
    is there a simple way to make it non circular?
    Thank you.

    • loop:false

        • Author: coolest
        • Posted on: 2012/02/02
        • At: 19:49

        So simple!

    • Author: Brandon
    • Posted on: 2012/02/05
    • At: 20:27

    how do i make this autoplay?

    • with a timeout…

        • Author: Brandon
        • Posted on: 2012/02/07
        • At: 04:53

        I’m really sorry, I just realized what I wrote…that was super rude of me. Your work is amazing and I am grateful for what you do because it makes my life easier. Would you kindly elaborate? I’m not great with JS…what exactly does that JS look like? Thanks!

      • try with:
        setInterval(function () { gallery.next(); }, 1000);

      • Author: Brandon
      • Posted on: 2012/02/08
      • At: 19:22

      thanks i’m gonna give it a try!

    • Author: Gary
    • Posted on: 2012/02/08
    • At: 09:54

    Instead of selling these libraries for shitload of money, you make it available free for everyone. Hats off to you, sir.

    Internet would be a better place if there are more people like you improving the standard without asking a return and less people like Microsoft who keep breaking the standard and causing trouble for everyone.

    • Author: Simon
    • Posted on: 2012/02/08
    • At: 18:52

    Nice carousel – thanks. Can I ask three cheeky questions? Being a bit of a web dunce myself I was wondering:

    1/ Is it possible to make the images fit to the exact width of the device or do you have to set dimensions in the script?
    2/ Did you release the documentation?
    3/ Have you had a chance to look into why it might not work with jquerymobile?

      • Author: Brandon
      • Posted on: 2012/02/08
      • At: 22:23

      i’d like to know the answer to the first question too.

    • 1) swipeview itself is just an event handler + paginator. Anything else must be tailored to your needs. So basically, yes, you can have full screen images, but it must be coded. Swipeview gives you all the tools you need to do that.

      2,3) sorry, not yet.

        • Author: Simon
        • Posted on: 2012/02/09
        • At: 16:52

        Many thanks for the response. I think I need to improve my webcoding skills significantly as I am not sure how to do this!

        I will follow you on Twitter though so I can keep an eye out for the last two questions. Thanks again.

    • Author: John
    • Posted on: 2012/02/09
    • At: 04:08

    Very cool. I am working to see if I can extend use further as an ebook reader with more formatting and page numbering. Any update coming that might help. Thanks.

    • Author: joa
    • Posted on: 2012/02/13
    • At: 14:54

    Hi, first of all thanks for sharing this great work!

    I am trying to touchdrag elements inside the swipeview to a drop container outside the swipeview. (I am using http://www.gotproject.com/blog/post2.html) Unfortunately the elements within the swipeview always lay under the droptarget. I’ve tried to change the z-index and the translate3d z-position at multiple places without success. Can u give an advice where to change these values to get this working?

    • Author: Eugen
    • Posted on: 2012/02/15
    • At: 14:35

    First of all, great work!
    And now a question: Is it possible to have page 0 and page 2 overlap a little towards page 1 (current), in order to have a “preview” of the prev/next image?

      • Author: Matt
      • Posted on: 2012/04/18
      • At: 15:48

      Yes this would also be very helpful for a project I’m working on. Is this possible? Great work Matteo!

    • Author: Matthew
    • Posted on: 2012/02/20
    • At: 20:17

    Love the script, but i do have a quick question. I’m(hopefully) using the script for an ipad web app, i need to use the inline slider which works perfectly, the only thing i need to have multiple(dynamicly created) inline sliders. An example would be 5 inline sliders on one page.

    any quick direction to accomplish this would be great

    • Author: Eugen
    • Posted on: 2012/02/27
    • At: 13:09

    Hi, I have another problem that I like to share (maybe I’m not the only one). If I have 4 pages and I use goToPage(4), page 3 will not be displayed onFlip. Looking at the code I managed to find that this only happens when loop: false. Any idea how to fix this?

    • Author: Burn
    • Posted on: 2012/02/28
    • At: 11:30

    this is great! thanks!

    • Author: Reed Enger
    • Posted on: 2012/02/28
    • At: 19:46

    Matteo, this is splendid – elegant code, and slick as could be on my phone. I’ve been using iScroll extensively, and this seems like a perfect evolution.

    I can’t wait for Firefox support!

    - Reed

    • Author: Ivan
    • Posted on: 2012/03/05
    • At: 09:56

    Hi there

    I just came across this project and it looks great!
    I’m wondering if you can use this for sliding any html tag ?- eg. an ul where you use the li (filled with html content) instad of the img.
    or is there another project more suitable for this?

    Hope it makes sense to you…

    Thanks in advance!

    • Author: Jason
    • Posted on: 2012/03/06
    • At: 04:50

    How to show more than one DIV at a time?

    • Author: Erik
    • Posted on: 2012/03/06
    • At: 19:47

    This looks fabulous, but when I put the wrapper inside a div that uses jquery (1.7.1) it breaks. It just scrolls regularly. It’s probably a simple fix but I can’t quite figure out what is causing it to break. Any solutions?

    Many thanks.

    • Author: Kenneth
    • Posted on: 2012/03/08
    • At: 10:27

    Amazing piece of software that works very fluently on all devices I’ve tested on.

    But I have an important issue on Android 2.3 with horizontal swiping. You can experience it on the horizontal demo here as well. Swipe to page two, and then scroll the page vertically. This will show the first page while scrolling! Once you stop scrolling, it displays normally again. Obviously a bug in the browser, but I have been unable to find a fix/hack. Anyone has any suggestions?

      • Author: A.F.
      • Posted on: 2012/03/08
      • At: 15:50

      Second this, we see it even more severe on our page with a lot more DOM elements than the demo page here. This is a showstopper for us at the moment.

    • please report this kind of issues on github. I’d also need to know which device you are testing on

        • Author: Kenneth
        • Posted on: 2012/05/15
        • At: 13:10

        Reported the bug on github – not that it receives any comments. Does noone else see this problem? Affects all Android 2.3 phones I’ve tested on.

      • thanks for the report, it should be an easy fix, probably just some CSS properties. I just need to find the time to debug it ;)

        • Author: Kenneth
        • Posted on: 2012/06/04
        • At: 10:26

        Do you have any theory of what might cause it? I’ll gladly look into it myself, but I am hitting a wall trying to find a workaround..

    • Author: Hallakol
    • Posted on: 2012/03/16
    • At: 10:19

    This, and your other projects look great. Swipeview seems to be exactly what I was looking for. Now I just hope I get it to work with the rest of the framework I’ll be using :)

  • Thanks for the code! I’ve used it to implement a magazine viewer on our site (only for iPhone/iPad, though), and I was able to use the published interface to reuse the same instance for different magazines (with different numbers of pages) and to show one or two pages at a time depending on aspect.

    However, I would love to add ‘native’ two-finger zooming to the viewer as well, any hints on how it should behave? Assume the zoom happens ‘inside’ the original picture dimensions: how would people expect horizontal scrolling to work when the picture is zoomed? Move the zoomed content? Move the slider? Move the picture if it’s not at the edge, the slider otherwise?

    (Then there’s a programming problem of creating a div to zoom the picture inside and steering the touch events to the right recipient, but that’s solvable. And I know that iScroll does zoom, but I need the light weight of slideView).

    • I think you should pan the zoomed content until you reach the end of the page, if you keep dragging you then move to the next (not-zoomed) page.

      • Thanks, that’s what I will aim for!

  • Matteo,
    This is indeed excellent workmanship you’ve done! I was searching for some code to borrow in my effort to make a magazine swipe style for a small catalog that to be displayed on an iPad, and your app has done justice!!! I’m a print graphic designer who adores the web, and I’ve got mad respect for web designers and developers…fascinated by the sourcecode!
    I’m having a bit of trouble trying to figure out how to get the “loading” animated gif (which I added because it wasn’t in the download files) to show whenever a page sometimes stalls. I’d rather have a “loading” animated gif show itself when pages stall, then to have mere empty area show. I would whole most definitely appreciate if you can offer me guidance pointing where in the code can this be implemented to make this work (html, css, js??). And secondly, is it possible to make it (slideshow) downloadable to the iPad (ala FT.com – Financial Times web app)? Can you offer code to help achieve this matter?

    Again, many, many Thank Yous!

    • Author: Tomy
    • Posted on: 2012/03/22
    • At: 16:39

    Extraordinary!!!!
    One question: It’s possible to “click” in a photo and go to http://www.example.com?

    • Author: Callum
    • Posted on: 2012/03/24
    • At: 21:45

    Hi, great useful tool, just wondering how do I tell when the page is loaded but off screen e.g. It’s the next one to come on, as I need to redraw a html5 canvas.
    Thanks

    • Author: Kelly
    • Posted on: 2012/03/26
    • At: 06:09

    Indeed a great library. very smooth.
    However, I don’t know if this is a bug worthy of reporting on Github or if this is just how it is, but on my Android 2.3 phone, the demo goes all to heck after I switch orientation on my phone. the panels get chopped in half at one side or the other and some panels disappear all together and it doesn’t fix until I refresh the page.

      • Author: Ankur garha
      • Posted on: 2012/06/16
      • At: 00:29

      Im also facing the same problem, I also tried calling the swipeview’s refresh method but still its getting chopped…

      has any body got any solution for this one yet

  • Hi,
    do you have some simplified version for Windows Phone?

    • Author: Damien
    • Posted on: 2012/03/29
    • At: 06:37

    Hello, have been testing SwipeView and iScroll in an xcode ipad project. Initial testing showed scrolling/swiping were not snapping as expected. For iScroll the problem was fixed with the code sample on the iScroll page under LOAD adding the setTimeout function etc. How can this be implemented for SwipeView. I have one page with the inline demo and another the gallery demo.

    Also, what is the best way to have multiple inline carousels on one page?

    thanks in advance

    • Author: Christian
    • Posted on: 2012/04/03
    • At: 20:59

    What happens when I use less than 3 items? Will the script prevent flips when there is only a single item in the slider? What will it do when there is only 2 items? – I ask because I was trying to build a dynamic carousel but is not certain that I will have 3+ items at any given time.

    • the script breaks with less the 3 items. I need to fix this, I know ;)

        • Author: Ankur garha
        • Posted on: 2012/06/16
        • At: 12:59

        Hello Matteo,

        When can we expect that feature to be released?
        Can you please give us any rough idea, how can we temporarily make it happen for items less than three

    • Author: Maykel Barcala
    • Posted on: 2012/04/07
    • At: 07:27

    Hi Matteo,

    Very nice swipe gallery congratulation. I would like to ask you some questions if you don’t mind.
    1) how is possible to create a link from each image?
    2) in case that I want to see the gallery in an iPhone how i can decrease the size of the picture to any other size?
    3) Is possible to done the same kind of swipe gallery placing the images in HTML code, inside ‘wrapper’ div tag i mean?

    Regards

    MB

      • Author: Marcelo
      • Posted on: 2013/03/14
      • At: 14:21

      Any luck with the linking from images? I am needing the same thing!

      Thanks.

      -Marcelo

    • Author: AM
    • Posted on: 2012/04/12
    • At: 13:08

    Hi Matteo,

    Great work! just a quick note, on Safari (iOS4.2) as well as PC version (not sure about latest version) when you use a high css % property (the script does something like left = p*100+’%’ on the masterpages); Safari fails to render the page. Using your gallery demo, create 2000 slides for example and try carousel.goToPage(1000); this will fail.

    I’m not sure why this happens, but if you use px instead of % then it works. FYI only, great job btw!

    • Author: paolo
    • Posted on: 2012/04/13
    • At: 09:36

    there is a way to load new pages at runtime?
    i will try to explain better the issue:

    i’ve 3 images (prev, current, next)
    going next i will make an ajax call that give me the next one… and i want to push on the images array, and refresh the swipeview (the same going previous)

    • Author: Harry E J Gordon
    • Posted on: 2012/04/13
    • At: 10:25

    Hi Matteo,

    I noticed other readers asking about JQM compatibility. I ran into this problem myself but I got around it by wrapping the swipeview initialisation code in a JQM ‘pageshow’ trigger:


    $('#page-area-of-expertise').live('pageshow', function() {
    // swipeview init code here
    });

    I hope this is of some use to someone.

    Thanks,

    Harry

    • Author: undefined
    • Posted on: 2012/04/16
    • At: 20:36

    Hi Matteo, First of all, great work! but i have a question. can you expand the amount of pictures in the carousel and and nav bar?

    • Author: subhrajit
    • Posted on: 2012/04/17
    • At: 15:00

    hi,
    its really a good work,
    Can you please tell me, how its works for multiple rows?

    is there any quick fix?

    • Author: lorenzo
    • Posted on: 2012/04/23
    • At: 16:54

    Hi, amazing script but I think I might have found a bug:

    If I use loop: false in the initialization, and then goToPage(2) as soon as swipeview has initialized, the masterpage-0 still has visibility:hidden and I can’t see it… this also happens with goToPage(5, 8, 11 ecc). Is there a simple fix?
    Thanks so much,

    Lorenzo

    • Author: fabien
    • Posted on: 2012/04/26
    • At: 00:56

    excellent plugin. Is there a way or a fix to work with firefox?

    • Author: Manmade
    • Posted on: 2012/05/03
    • At: 19:24

    Hi Matteo
    I have made my swipes higher then the webview so I can scroll down on them.
    And if I swipe when Im at the bottom, then the new swipe is at the bottom too, so my question is if it is possible to start from the top of a new swipe?
    I hope you undstand what I mean.
    Thanks a lot!

    • I’m sorry, not sure I got it…

  • I will immediately clutch your rss feed as I can not to find your email subscription link or newsletter service. Do you’ve any? Kindly let me recognise in order that I could subscribe. Thanks.

  • Hi there What does this mean please? – from the demo

    /(^|\s)swipeview-active(\s|$)/.test(className) ||

    Sorry I hate to admit it, but I don’t really know what that is.

    Thanks !

  • check if className contains “swipeview-active”

    • Thank you

  • The idea of having just 3 pages in the DOM and actualizing them after each swipe is smart.
    Wouldn’t this behaviour also make sense for iscroll?

    • indeed but scrolling is too fast, the engine can’t keep up

  • Hi Matteo, Can you recommend any feature detection to use with Swipeview? A http://modernizr.com/ sort of approach to check if the browser can use it? Thank you.

    • Author: CT Wong
    • Posted on: 2012/05/17
    • At: 11:15

    Hi Matteo, It is great library. And I also add iscroll to it successfully and smoothly.
    However, there is a problem. Since your swipeview only contains 3 container, the content will be replaced when i swipe to fourth page(etc), can i add more container, so i do not need to redefin iscroll again and again?

    Thanks you for your kind comment.

    • Author: Robert
    • Posted on: 2012/05/22
    • At: 11:21

    Hi Matteo,

    Great script :)
    I need to use it in an right to left application, which means that the swype directions should be refersed. Do you think this would be simple to accomplish with your code?

    • Author: Ernie
    • Posted on: 2012/05/22
    • At: 17:54

    Matteo, Thanks for a great script. I am running into a issue that is likely a simple fix. I’m pulling in data from 4 separate pages as ASP includes. Each swipe loads a different set of content from each include. But if the content in the include has single quotes it errors the javascript or causes the script to think there is another slide. Is there a way of not putting the content directly into the javascript and simply calling separate divs by ID. I think if you called separate divs by ID instead of placing content directly into the slide javascript container I could avoid characters causing issues. BTW, I cannot control the content of the include files, so escaping characters and content in the include files is not possible. Thanks for your help.

    • Author: andreas
    • Posted on: 2012/06/12
    • At: 16:10

    I just wanted to thank you for this amazing little piece of software, it helped me a lot making a quick prototype of an application.