jQuery.kinetic

Dave Taylor http://the-taylors.org The MIT License (MIT)

Master:

All branches:

jQuery.kinetic is a simple plugin which adds smooth drag scrolling with gradual deceleration to containers.

Compatibility

This plugin works with jQuery and Zepto

Browsers

ie: 7,8,9
firefox: 3.6,4,5
chrome: 13
safari: 5
iOS Safari: 4

Demos

Take a look at a demo on http://the-taylors.org/jquery.kinetic.

Options

cursor          {string}    default: move   Specify the cursor to use on the wrapper
slowdown        {number}    default: 0.9    This option affects the speed at which the scroll slows
x               {string}    default: true   Toggles movement along the x axis
y               {string}    default: true   Toggles movement along the y axis
maxvelocity     {number}    default: 40     This option puts a cap on speed at which the container
                                            can scroll
throttleFPS     {number}    default: 60     This adds throttling to the mouse move events to boost
                                            performance when scrolling
triggerHardware {boolean} false             This adds css to the wrapper which
                                            will trigger iOS to use hardware acceleration

filterTarget    {function(target)}          Return false from this function to
                                            prevent capturing the scroll

movingClass     {object}
    up:         {string}    default: 'kinetic-moving-up'
    down:       {string}    default: 'kinetic-moving-down'
    left:       {string}    default: 'kinetic-moving-left'
    right:      {string}    default: 'kinetic-moving-right'

deceleratingClass {object}
    up:         {string}    default: 'kinetic-decelerating-up'
    down:       {string}    default: 'kinetic-decelerating-down'
    left:       {string}    default: 'kinetic-decelerating-left'
    right:      {string}    default: 'kinetic-decelerating-right'

Listeners:  All listeners are called with:
            - this = jQuery object holding the scroll container
            - a single settings argument which are all the options and
              { scrollLeft, scrollTop, velocity, velocityY }

moved       {function(settings)}           A function which is called on every move
stopped     {function(settings)}           A function which is called once all
                                           movement has stopped

Methods:    You can call methods by running the kinetic plugin
            on an element which has already been activated.

            eg  $('#wrapper').kinetic(); // activate
                $('#wrapper').kinetic('methodname', options);

start       Start movement in the scroll container at a particular velocity.
            This velocity will not slow until the end method is called.

            The following line scrolls the container left.
            $('#wrapper#).kinetic('start', { velocity: -30 });

            The following line scrolls the container right.
            $('#wrapper#).kinetic('start', { velocity: 30 });

            The following line scrolls the container diagonally.
            $('#wrapper#).kinetic('start', { velocity: -30, velocityY: -10 });

end         Begin slowdown of any scrolling velocity in the container.
            $('#wrapper#).kinetic('end');

stop        Stop the scrolling immediately

detach      Detach listeners and functionality from the wrapper

attach      Re-attach listeners and functionality previously detached using
            the detach method

Add your own method:
            // add the method
            $.kinetic.callMethods.do = function(settings, options){
                // method functionality
            };

            // use the method
            $('#elem').kinetic('do', { ... });

Running the tests

The test suite uses grunt's server and qunit functionality. The tests are being built up but currently cover the core functionality. This runs all qUnit Html specs in the /test/specs folder.

grunt npm install -g grunt
install devDependencies npm install from the root of the source

Then run from the root of the source

$ grunt

Manual tests

There are manual tests as html files within the /test folder.

Selenium suite

The selenium tests are not functioning at the moment and are a work in progress.

Changes

1.8.2

fix #34, #28, now will discard any subsequent attempts to bind .kinetic()

1.8.1

tweak to hardware trigger css (@edmelly)
upgrade to Grunt 0.4

1.8

add scroll listener to trigger move events (@dennipahmah)

1.7

add cursor option to change the default move cursor

1.6.1

bug fix release for unbinding touch events

1.6

use bind for touch events to fix issues on android

1.5

added ability to prevent capturing scroll depending on the target
fix for using alongside jQuery UI draggable #14 - thanks @sidoh, @NilsHolmstrom

1.4

added ability to nest containers thanks @cc-lam
added detach/attach methods
added triggerHardware option

1.3

IE bug fixes when dragging images

Adding extensibility for methods by attaching functions to jQuery.

  // add the method
  $.kinetic.callMethods.do = function(settings, options){
      // method functionality
  };

  // use the method
  $('#elem').kinetic('do', { ... });

Added stop method
Fix bug with ignored axis triggering animation frames

Notes

The scrollbar plugin is still very much an alpha version.

LekisS / jquery.kinetic