> 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

  • Super sweet! I can’t wait to put this to use, it looks excellent :)

    Problem is the demo doesn’t appear to work on my 3GS 4.3.5, error being “swipeview.js Line 43. TypeError: Result of expression ‘div.dataset’ [undefined] is not an object”

    • Author: strages
    • Posted on: 2011/10/10
    • At: 10:12

    WOULD LOVe to use this! :D however is doesnt work very well yet on my android device. At least the demo doesn’t. It doesnt scroll to the next image, but goes behond that until the last image is only half visible.

    • more details needed. OS version. Device brand/make

      it works like a charm on my galaxy s2

        • Author: Marcus
        • Posted on: 2011/10/10
        • At: 17:00

        Same problem on my archos A32,but last night it worked fine. Did you change anything today?
        Android 2.2.

      • you may try to download v0.1 https://github.com/cubiq/SwipeView/commit/97646f1b695ee64e34e259fb1b655b15b7ddf0cf

        I don’t have 2.2 at hand now, I’m really targeting 2.3 and above. I’ll try with the simulator.

        • Author: Strages
        • Posted on: 2011/10/10
        • At: 21:58

        Samsung Nexus S i9023, however works like a charm now btw! Did you change anything?

        love this, however, still a littttle shaky when flicking. can you make it even smoother? ( yes i know, asking for the impossible ) really want that iphone smoothness on my website viewed on an android :)

        btw, this ll even work on android 2.1?

        • Author: Strages
        • Posted on: 2011/10/10
        • At: 22:02

        I know it’s maybe not the target, however will it be desktop friendly?

        really like it to use this as it is lighter then iscroll4 and i just use it for this sort of thing ;)

        want to have i scroll to act as swipeview ;)

      • smoothness on android mostly depends on the device CPU. maybe I’ve got an idea to have it a little bit smoother on android, but you cannot squeeze blood from turnip.

        the script should work on desktop webkit already, I’ll widen desktop compatibility soon.

        • Author: Strages
        • Posted on: 2011/10/11
        • At: 12:39

        this is freaking great! tx :D already following you on twitter, so ill keep checking out your stuff! :D

    • Author: cyril
    • Posted on: 2011/10/10
    • At: 15:17

    Always nice to see you created a new gadget to play with! Great work!
    Thanks

  • YOU ARE THE MAN!
    I tested it and it works great and a feature I have been waiting for, for a long time, thanks.

    A couple of suggestions that I think would be really good is if you can go to a specific image, eg having small images and when click on one of them, then go to that image? And of course as you say for release 1, be able to use text underneat the image, maybe be able to have videos instead of images?

    I will start to test and see if it works in my 2wayscroll script app.
    Thanks again for all you amazing work!

    • Author: chris
    • Posted on: 2011/10/11
    • At: 10:12

    is there anyway to use divs or any other container as a page source instead of just using images?

    • I’m working on it. You’ll be able to use v1.0 with any kind of content.

        • Author: chris
        • Posted on: 2011/10/11
        • At: 16:02

        Thanks matteo your work is awesum and using it on many projects – @verritas

        • Author: chris
        • Posted on: 2011/10/11
        • At: 16:07

        oh I also wanted to know if its possible to have a 5 slider carousel, 2 images preloaded on either side and one main image being displayed?
        I think il dive into that, keep up the seriously good work

      • current version is using 3 pages and you have 2 images preloaded 1 image displayed. I’m considering adding 2 more pages to have a 5 page buffer, but I believe is not needed

        • Author: Justin
        • Posted on: 2011/10/26
        • At: 13:42

        WOW! Any idea when v1.0 will be released? Or… Is there possibly a quick n dirty solution to use divs rather than images. I have to do a prototype for a client presentation (IOS5) and would really like to use swipeview.

        Thanks again for your amazing work.

      • in the latest version you can use any tag, not only imgs. have a look at the examples

        • Author: Justin
        • Posted on: 2011/10/27
        • At: 14:40

        Thanks. I’ll have a play.

    • Author: cyril
    • Posted on: 2011/10/13
    • At: 16:46

    Hi Matteo,

    Again thanks. Got it up and running now. Now trying to put a subtitle in there :)

  • Great!
    I would like to show so big pictures that you could swipe down. How do you think it is possible?

    I managed to insert video inside so that it starts automatically when it is shown and stops if you swipe it out.

    Basically I inserter pages.type = html and inside it video tag and then
    if (this.options.pages[image].type == ‘html’) {
    div.innerHTML = this.options.pages[image].source;
    and kind of same to the bottom.

    • Author: Marcos Lavorato
    • Posted on: 2011/10/17
    • At: 00:02

    Huge thanks for that!

    • Author: Benjamin Winslow
    • Posted on: 2011/10/18
    • At: 04:14

    The world needed something like this! Thank you for your work. Would be cool to see some of the iScroll carousel features come to this like being able to programmatically navigate slides in addition to using touch.

    Also, making it easy to use divs as you said, but I’m sure I can figure that out =)

      • Author: chris
      • Posted on: 2011/10/18
      • At: 11:53

      i agree navigation would be really cool, Your new version on the carousel is top notch! very good work

    • Author: Luca
    • Posted on: 2011/10/18
    • At: 16:33

    hey Matteo, first of all i want to thank you for this great work! it runs very smoothly! :)

    i have to asynchronously load my images to create a fullscreen gallery, but i don’t know their dimension.
    so i have to force their width or height ( depending on the orientation of the device), push em into a container and position the images in top: 50% or left 50%.

    do you think it’s possible with your plugin? would it be smooth?

    • yes, sure. width/height parms are optional.
      I’ll soon release a new version with callbacks on swipes, etc, so you can hook to various custom events.

        • Author: Luca
        • Posted on: 2011/10/22
        • At: 20:02

        just tried it with new features you implemented the other day and works perfectly! :)

        only a question…is there a way to avoid the redirection of ‘a’ elements, only while i’m swiping?

        • Author: Luca
        • Posted on: 2011/10/22
        • At: 20:11

        sorry, i was trying on safari. the real question is f there is a way to place some links inside the pages, on iPad/iPhone :)

  • Are there plans for getting functionality like the following?

    SwipeView.goto("imagename.jpg");

    I’m thinking about implementing it myself ( already did some work with capturing the swipe events ), but I’d rather not if you already have it mostly completed.

    Thanks again for your great work. I’m a huge fan of iScroll.

    • Yes. it’s in my to-do.

    • Author: Ethan
    • Posted on: 2011/10/19
    • At: 03:14

    This is awesome.
    The reason I am switching from Iscroll to this, is that it iscroll is not supported by couple of android devices e.g. Samsung Galaxy S2 or Sony Ericsson Xperia.
    But I’m wondering if it is possible to manage the images and texts programmatically? i.e. reading from a data source. Also, how I can display more than one item at the same time on screen? like what the Iscroll do?

    Thanks

    • no issues on my GS2 actually… ;)

      regarding your questions, I’ll soon release a more detailed doc.

    • Author: akrogs
    • Posted on: 2011/10/20
    • At: 01:32

    Nice, but would be better with the pinch to zoom activated.

    • Author: Jon
    • Posted on: 2011/10/23
    • At: 12:49

    Is it possible to add links to the images?

      • Author: Jon
      • Posted on: 2011/10/23
      • At: 13:58

      Ahh- custom events coming soon? Did I miss them in the latest download?

      • I’m trying to consolidate the API. latest version introduced a couple of custom events

    • Author: JDS
    • Posted on: 2011/10/23
    • At: 16:46

    Great tool. I added a “start” option to pick a starting page on the list (rather than only the first). The new GotoPage probably suffices for this as well. I also added a pageSize option (vs. a fixed 100% as swipeview currently assumes) to accommodate full screen edge-to-edge gallery images, so that a gap would be maintained to the next image.

    A note for people tweaking swipeview for gallery use on the iPhone: take the author’s word that any animations during image load causes stutters in the webkit/iPhone animations. I had tried using the very cool spin.js (http://fgnass.github.com/spin.js/) to add a spinner to the loading placeholder, but no matter how I optimized it, spinning a CSS spinner at the same time as loading the images caused glitches and delays in swiping. I ended up using an animated GIF background instead. The same thing holds for pinch to zoom (which I also experimented with).

    One other tweak: I clear the swipeview-loading class on image load, which eliminates the brief incorrect display of the old image as new content loads. See the GitHub issues.

    Thanks for this!

    • both “start page” and “page width” are interesting features. I’m surely adding them both to my to-do.

    • Author: Strages
    • Posted on: 2011/10/23
    • At: 18:24
    • Author: Devin
    • Posted on: 2011/10/23
    • At: 21:49

    can I add links to images inside the slide?

    • Author: Dredy
    • Posted on: 2011/10/24
    • At: 10:14

    Hi Matteo, first: very good piece of code!

    A little question:
    document.addEventListener(‘touchmove’, function (e) { e.preventDefault(); }, false);
    this prevents the user from zooming the contents.
    Because my need is to leave the user zooming in and out the images, i tried to comment the line and the content could be zoomed.
    There are “hidden” consequence commenting this line, in Your experience? I’m having troubles with images that are not all the same size that are cut by the overflow:hidden (some portrait and some landscape oriented, I do not assign the size of objects because unknown as i load images urls from a db)
    Thanks for Your work.

    • I believe that image zooming should be handled by a custom script hooked to gesture events. but you can freely remove the preventDefault on touchmove. it’s there just to prevent the whole page from scrolling.

        • Author: Mike
        • Posted on: 2012/01/05
        • At: 01:53

        I would love to get some help on this. Its perfect except I need to zoom also!

    • Author: Todd
    • Posted on: 2011/10/26
    • At: 16:02

    No luck with Firefox for Android running on a Desire Z with 2.3.7. The image isn’t centered, and it doesn’t swipe. When I tap on a selector bullet (which is square rather than round) the image disappears and then the new image is not loaded.

    • does not support firefox (yet)

    • Author: James Venn
    • Posted on: 2011/10/27
    • At: 23:43

    Current build Does not work on iPads running iOS 5. Tested on 3 ipads to confirm.

    • ahem, works like a charm on my ipad with iOS5. what’s your issue? can you be more detailed?

    • Author: Matthew
    • Posted on: 2011/10/28
    • At: 20:09

    Awesome! Is this cross-platform? (Desktop browsers too?)

    • chrome+safari. Opera, FF and IE9 definitely possible.

    • Author: strages
    • Posted on: 2011/10/30
    • At: 11:26

    working like a charm right now on chrome. will it be possible to have it work on ie 7 and 8?

    oh ye, is it possible to let more than 1 picture show up in the viewport? so this means that the picture you see to the left of the middle picture will become the middle picture.

      • Author: Travis
      • Posted on: 2011/12/28
      • At: 23:40

      Yeah, I would love for the next update to be IE8+ support, and Firefox

      • firefox for sure, IE9 possible, IE8 don’t know

    • Author: jon
    • Posted on: 2011/10/30
    • At: 16:54

    can custom events use links like using goToPage to go to URL? I see the inline demo has links working but I tried to combine the inline with the gallery – to get the select picture nav working – without much luck.

  • Can I use iscroll for the content inside swipeview?
    I want to show news items in swipeview but since the news items are lengthier I want to use iscroll 4 for vertical scroll.

      • Author: Greg
      • Posted on: 2011/11/07
      • At: 23:46

      I wrote such a swipe functionality for iScroll. It even worked with bi-directional scrolling content – like extra large images. It was for an older version of iScroll though. I will look for it and see if it is still usable.

      greg

    • Author: Alan Wong
    • Posted on: 2011/11/16
    • At: 11:52

    Amazing!!!
    I would loke to ask is there any way to load html source to the eReader?

    • Author: Gareth
    • Posted on: 2011/11/21
    • At: 23:25

    This is great, and I have it working nicely.

    Any thoughts on what would be the best approach towards using this on more than one ‘page’ inside a jquery mobile app?

      • Author: donat
      • Posted on: 2011/12/22
      • At: 12:56

      In jQuery Mobile you would need to listen to the pageinit event. However, at the moment SwipeView has some problems with jQuery Mobile.

        • Author: diaconu daniel
        • Posted on: 2011/12/30
        • At: 10:53

        I needed to use swipeview with jquery mobile. Instead of looking for a solution in javascript I added an iframe into my page… removed borders, positioned it into another centered div and voila… no conflicts. There are problems with width 100% when i turn the device so i used a specific pixels number. for small images (like 300px) and text it works. keep up the good work and thank you for swipeview!

    • Author: ivan
    • Posted on: 2011/11/26
    • At: 01:35

    I find your script extremely useful for many things, but….

    Using the inline demo, How do I get 2x carousels to work on one page??

    • Author: tilman
    • Posted on: 2011/12/02
    • At: 10:19

    hey, can this be used as a vertical slider as well?

    • Author: Hessius
    • Posted on: 2011/12/03
    • At: 10:33

    Hi I’m using the code from the inline example (with the asimov robot laws) to rotate between three imgs (.png, with transparency) wrapped in a a href wrapped in a div.

    When I’ve swiped to image no. 2 and tap anywhere on or around the image the first image either flickers or replaces the second one swiping to the left still reveals image number three and tapping on or around that image flickers the image or hides it.

    I’m using it in a phone gap project. Any ideas of what could be wrong? (I’m guessing some sort of conflict with my css?)

    • does the inline demo works as expected?

      It’s hard to say what is going wrong not looking at the code… a css conflict maybe

        • Author: Hessius
        • Posted on: 2011/12/05
        • At: 20:14

        It was a conflict with iScroll!

    • Author: Roberto
    • Posted on: 2011/12/06
    • At: 12:27

    Hi. Thank you for the amazing work (swipeview, iscroll, spinnigwheel,etc.)

    I am trying to display swipeview in landscape mode. When I rotate it (-webkit-transform:rotate(90deg)) it is displayed correctly, but the snap event does not seep to trigger.

    I checked the variable “dist” and had to tweak it to be < to "snapThreshold", but the photo still moves back to its original position.

    I did however notice that if I slide my finger obliquely the photo does slide out. So, I am inclined the assume that despite the rotation, the script is still expecting a horizontal movement as seen from a portrait perspective.

    (I must add that I am using "rotate" because I disabled the automatic browser orientation. I am using swipeview in an app that I do not want to rotate on all pages…)

    I hope you can help me some this last little problem.

    Thank you.

    roberto

      • Author: Roberto
      • Posted on: 2011/12/06
      • At: 13:28

      I found the a solution.

      I reduced the value snapThreshold…

      All good now. :)

    • Author: Roberto
    • Posted on: 2011/12/06
    • At: 14:46

    Just in case someone is interested…

    You can detect the clicking/tapping of a photo by modifying:

    if (!this.moved) return;

    to

    if (!this.moved) { myFunction(); return;}

    And if you want to pass the number of the photo;

    myFunction(this.pageIndex)

      • Author: tom
      • Posted on: 2012/02/27
      • At: 06:09

      THANK YOU!!!!

    • Author: EDELLELI Nizar
    • Posted on: 2011/12/06
    • At: 14:51

    Very impressive work!

    • Author: Snowcrack
    • Posted on: 2011/12/07
    • At: 17:39

    Hi, i have a problem with the swipeview. All works fine without jquery mobile. But as soon as I load the jquery moble script, the slide animation stagnates or have some strange delays.

    I figured out, when the animation stagnates and I tap on the screen a second time, the animation continue correctly …

    I tryed on ios 5.0 (simulator and iphone)

      • Author: Snowcrack
      • Posted on: 2011/12/07
      • At: 19:11

      the problem isn’t in ios 4.3 (simulator). Do you have any ideas?

      • Author: donat
      • Posted on: 2011/12/22
      • At: 12:54

      I have the same problem and I have prepared a small test program for Matteo.

      • Author: wuzehai
      • Posted on: 2012/01/31
      • At: 10:34

      I have been solved,It is OK that run in ios5.
      modify swipeview.js
      handleEvent: function (e) {
      console.log(e.type);
      switch (e.type) {
      case startEvent:
      this.__start(e);
      break;
      case moveEvent:
      this.__move(e);
      break;
      case cancelEvent:
      case endEvent:
      this.__end(e);
      break;
      case resizeEvent:
      this.__resize();
      break;
      case ‘webkitTransitionEnd’:
      if (e.target == this.slider && !this.options.hastyPageFlip) this.__flip();
      break;
      }
      },

      I test OK

    • Author: Leonardo
    • Posted on: 2011/12/08
    • At: 23:21

    how can i put a link on images?

    • Author: CodeSix
    • Posted on: 2011/12/13
    • At: 19:51

    Love your works! I want to create a slideshow with SwipeView, by calling gallery.next() with timeouts I can make a simple slideshow, however in which of the 3 img’s should I put an onload event such that it only flips when the next slide is ready?

    • Author: Yoni
    • Posted on: 2011/12/14
    • At: 23:48

    Great work man!
    I absolutely love it.
    It would be very useful to have this work on other non-webkit browsers like firefox, ie, android etc…
    Thanks

    • Author: JING
    • Posted on: 2011/12/15
    • At: 17:27

    Wonderful job! You have almost everything I need for my mobile website :)

    One question. I am not sure if it was only me who had this problem. The page becomes un-scrollable after I put the SwipeView. Is it a known problem or I did something wrong in my code.

    Thanks

    • have a look at the “inline” demo

        • Author: JING
        • Posted on: 2011/12/15
        • At: 21:30

        Works, thank you!

    • Author: Tania
    • Posted on: 2011/12/16
    • At: 06:04

    Has anyone been able to implement a transparent background on the swipeView object?

    • Author: Ravi
    • Posted on: 2011/12/22
    • At: 07:02

    Hey guys I found div swipe(exactly like in mobile)using Jquery. Please look at the code here. Enjoy!
    http://superdit.com/2011/08/28/swipe-like-effect-based-on-jquery-ui-draggable/

    • Author: John Jackson
    • Posted on: 2011/12/27
    • At: 10:38

    Hi,

    what does this code mean:
    slides = [
    {
    img: 'images/pic01.jpg',
    width: 300,
    height: 213,
    desc: 'Piazza del Duomo, Florence, Italy'
    },
    {
    img: 'images/pic02.jpg',
    width: 300,
    height: 164,
    desc: 'Tuscan Landscape'
    },
    {
    img: 'images/pic03.jpg',
    width: 300,
    height: 213,
    desc: 'Colosseo, Rome, Italy'
    },
    {
    img: 'images/pic04.jpg',
    width: 147,
    height: 220,
    desc: 'Somewhere near Chinatown, San Francisco'
    },
    {
    img: 'images/pic05.jpg',
    width: 300,
    height: 213,
    desc: 'Medieval guard tower, Asciano, Siena, Italy'
    },
    {
    img: 'images/pic06.jpg',
    width: 165,
    height: 220,
    desc: 'Leaning tower, Pisa, Italy'
    }
    ];

    If it is an array, How to create it programmaticly to change images?

    Thank you

    • It’s json. Do a google search and you’ll find plenty info.

    • Author: 26buckets
    • Posted on: 2011/12/29
    • At: 10:42

    Thank you very much for this piece of code! Will use it in my next ipad project!

    • Author: coolest
    • Posted on: 2011/12/29
    • At: 17:07

    Hi! Well done man!
    Is there a way to load different images for different device resolutions?
    Thank you.

    • you may add an “img2x” parameter to the objects array and use that value if devicePixelRatio > 1

    • Author: jason chong
    • Posted on: 2011/12/30
    • At: 09:09

    Just a doubt whether is there any problem when we use “goToPage” method and set loop to false?

    • Author: coolest
    • Posted on: 2011/12/30
    • At: 12:24

    What if I need to disable the swipe till something else ends?
    Suggestions are welcome.
    Thanks.

    • Author: Denham
    • Posted on: 2012/01/03
    • At: 01:15

    Love this and love your work!

    A case you may want to take into account – if someone is having a variety of elements/items included in a single “page” (i.e. a couple of links), users wont be able to click/touch an individual items. This could also be detrimental if someone is trying to highlight text for copying/pasting, playing a video, etc.

    Maybe I’m thinking about doing to much with it, but for a basic gallery utility, it is fantastic. Keep it up :)

    • Author: Travis Cooper
    • Posted on: 2012/01/03
    • At: 16:47

    Any plans to make workable on IE and Firefox for desktop applications? I’d be great to have one tool for desktop and mobile apps.

    • sooner or later it will happen

    • Author: DJB31st
    • Posted on: 2012/01/04
    • At: 16:45

    Appear to have an issue on desire HD.

    Works fine if you load the page in portrait mode and also in landscape, but if you rotate the screen after its loaded your demo doesn’t appear to work as it should. Will post a solution if i find one :-)

    • Author: Ravi SV
    • Posted on: 2012/01/05
    • At: 06:58

    This is very nice. Is there a way where I can use this only for a button click and disable not slide for touch swipe?