jquery.kinetic

jQuery.kinetic

Dave Taylor http://davetayls.me The MIT License (MIT)

This code has been pretty stable for a while (with it’s few restrictions) and so am not actively making changes. If you want to improve it in any way feel free to submit a pull request (with tests) and we will merge in any that make sense and don’t add bloat to what is a simple plugin.

Master: Build Status

All branches: Build Status

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

NB. @dzek69 has created a version of this plugin without the dependency on jQuery: https://github.com/dzek69/vanilla.kinetic

Installation

Bower

$ bower install jquery.kinetic --save

npm

$ npm install jquery.kinetic

CDN

<script src="https://cdn.jsdelivr.net/npm/jquery.kinetic/jquery.kinetic.js"></script>

Script tag

You can add the script to the page.

<script src="jquery.kinetic.js"></script>

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.

Filtering Clickable elements

If you need to allow events to be passed through the wrapper. For example to allow clicking on a link or an input then you can use filterTarget like so.

$('#wrapper').kinetic({
    filterTarget: function(target, e){
        if (!/down|start/.test(e.type)){
            return !(/area|a|input/i.test(target.tagName));
        }
    }
});

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
threshold       {number|function(target, e)}    default: 0   This is the number of pixels the mouse needs to move before the element starts scrolling
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
invert          {boolean}   default: false  Invert movement direction

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 = the instance of the Kinetic class

moved       {function()}           A function which is called on every move
stopped     {function()}           A function which is called once all
                                           movement has stopped
selectStart {function()}           A function which is called on user try to drag (select text),
                                           return false to prevent selection when dragging

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.

Releasing a new version

Releasing a small fix or change. The following will update the patch version number.

$ grunt release

Releasing a potentially breaking feature. The following will update the minor version number.

$ grunt release:minor

Changes

2.2.2

2.2.1

2.1.0

2.0.6

2.0.5

2.0.4

2.0.3

2.0.1

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

This site is open source. Improve this page.