Dave Taylor http://davetayls.me The MIT License (MIT)
jQuery.kinetic is a simple plugin which adds smooth drag scrolling with gradual deceleration to containers.
See release history below for details.
This plugin works with jQuery and Zepto
- ie: 7,8,9
- firefox: 3.6,4,5
- chrome: 13
- safari: 5
- iOS Safari: 4
Take a look at a demo on http://davetayls.me/jquery.kinetic.
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
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 });
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);
};
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
There are manual tests as html files within the /test
folder.
- changes to allow attaching to
<body>
with$('body').kinetic()
#61
After several years, this plugin has had a major refactor. Big thanks to (@skovhus) for helping with this rewrite. Here's what has happened.
- rewrite of plugin to an OO plugin
- BREAKING CHANGES
- call methods are now attached to the
$.Kinetic.prototype
and have slightly different arguments (see docs above) - no more $.kinetic namespace
Kinetic
constructor is attached to $.Kinetic$('#wrapper').data('kinetic-settings')
has been removed in favour ofinstance = $('#wrapper').data('kinetic'); settings = instance.settings
- All events
this
context is now the instance ofKinetic
. To access the$scroller
which was previously the context you can usethis.$el
- call methods are now attached to the
- fix #34, #28, now will discard any subsequent attempts to bind
.kinetic()
- tweak to hardware trigger css (@edmelly)
- upgrade to Grunt 0.4
- add scroll listener to trigger move events (@dennipahmah)
- add cursor option to change the default
move
cursor
- bug fix release for unbinding touch events
- use bind for touch events to fix issues on android
- added ability to prevent capturing scroll depending on the target
- fix for using alongside jQuery UI draggable #14 - thanks @sidoh, @NilsHolmstrom
- added ability to nest containers thanks @cc-lam
- added detach/attach methods
- added triggerHardware option
-
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
The scrollbar plugin is still very much an alpha version.