jQuery.kinetic

Fork me on GitHub

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

Demo

Drag a mouse or use touch gestures over the windows below to scroll the pane. If you let go with momentum the scrolling will slow gradually.

wembley stadium
< left | right >    --    end (decelerates)    --    stop (stop immediately)

Comments and Issues

If you have any issues with the plugin then please log them in the issue tracker on github and I'll do my best to help.

Options

jQuery.kinetic


Dave Taylor http://davetayls.me

The MIT License (MIT)

Master: Build Status

All branches: Build Status

jQuery.kinetic is a simple plugin which adds smooth drag scrolling with

gradual deceleration to containers.

Major new release 2.0 has BREAKING CHANGES

See release history below for details.

Compatibility

This plugin works with jQuery and

Zepto

Browsers

Demos

Take a look at a demo on http://davetayls.me/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 methods

There are some example methods in the extra-methods folder. You can also add your own.

$.Kinetic.prototype.do = function(options){

    // this -> instance of Kinetic

    // this.settings -> get current settings

    // options -> options passed in from call

    };



    // use the method

    $('#elem').kinetic('do', { options });

Hack the core

You can now hook in to the core functionality to make changes.

var _start = $.Kinetic.prototype.start;
    $.Kinetic.prototype.start = function(options){
    // -> do something
    _start.apply(this, arguments);
    };

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.

Then run from the root of the source

$ grunt

Manual tests

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

Changes


2.0

After several years, this plugin has had a major refactor. Big thanks to (@skovhus) for helping with this rewrite. Here's what has happened.

1.8.2

1.8.1

1.8

1.7

1.6.1

1.6

1.5

1.4

1.3

Notes


The scrollbar plugin is still very much an alpha version.

blog comments powered by Disqus