Feb 7, 2013

TouchSwipe: a jQuery plugin for touch and gesture-based interaction

TouchSwipe: a jQuery plugin for touch and gesture-based interaction

The TouchSwipe plugin was originally written for an iPad specific website for Renault. The main feature was a gallery of cars, where the user could swipe up/down to change the model, and left/right to change the specific view of the car. At the time (2010) jQuery mobile was very much in its infancy, so we decided to write our own plugin to bring touch events to jQuery.

  • Swipe

    At it most basic, the plugin will add swipe detection to a DIV. Using the swipe handler, you can detect which direction the user swiped in.

    
    $("#swipe").swipe({
      swipe:function(event, direction, distance, duration, fingerCount) {
        $(this).text("You swiped " + direction );
      }
    });
    
    
    Swipe me

    For convenience we added handlers that are only triggered in a particular direction: swipeLeft, swipeRight, swipeUp, swipeDown, each of which are passed the following arguments; event, direction, distance, duration, fingerCount.

    
    $("#swipe").swipe({
      swipeLeft:function(event, direction, distance, duration, fingerCount) {
        //This only fires when the user swipes left
      }
    });
    
    
  • Distance Threshold

    To ensure that the gesture was an intentional swipe, a minimum distance threshold was added, the default being 75px. If the user moved less than this then the swipe[Direction] handlers are not triggered.

    
    $("#threshold").swipe({
      swipe:function(event, direction, distance, duration, fingerCount){
        $(this).text("You swiped " + direction + " for " + distance + "px" );
      },
      threshold:100
    });
    
    
    Swipe me more than 100 pixels
  • Fingers

    We can also restrict the swipe to only trigger on 1,2,3 or "all" combination of fingers, with the fingers property. 0 fingers will be reported if run on a non touch device (desktop).

    
    $("#fingers").swipe({
      swipe:function(event, direction, distance, duration, fingerCount){
        $(this).text("You swiped " + direction + " with " + fingerCount + " fingers" );
      },
      fingers:'all'
    });
    
    
    Swipe me with different combinations of fingers
  • Swipe Status

    To enable more complex UI interactions, you can also receive events for every phase of the swipe,using the swipeStatus handler.

    
    $("#status").swipe( {
    swipeStatus:function(event, phase, direction, distance, duration, fingerCount)
    {
      //Here we can check the:
      //phase : 'start', 'move', 'end', 'cancel'
      //direction : 'left', 'right', 'up', 'down'
      //distance : Distance finger is from initial touch point in px
      //duration : Length of swipe in MS 
      //fingerCount : the number of fingers used
      },
      threshold:100,
      maxTimeThreshold:2500,
      fingers:'all'
    });
    
    
    Swipe me
  • Simple image scroller demo

    This simple example uses the swipe status to detect when the user is moving, but hasn't yet reached the swipe threshold. The images are dragged until the threshold is met, and then they are scrolled to the next image. If the swipe is not completed, the image snaps back to where it started.

  • More info

    For the source, documentation, detailed demos, or to contribute, see: