Skip to content
Touch scrolling for the browser
JavaScript HTML CSS
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Overscroll v1.5.1.1

Wednesday, December 7th 2011

Overscroll is a jQuery Plugin that emulates the iPhone scrolling experience in a browser. It is intended for use with the latest version of jQuery



Copyright 2011, Jonathan Azoff

Dual licensed under the MIT or GPL Version 2 licenses.



  • selector The jQuery selector, targeting an element to apply overscroll to
  • options An optional JavaScript object that you may pass if you would like to customize the experience of the overscroll element. Below is a list of properties that you may set on the options object and their respective effect.
    • options.showThumbs {Boolean: true}
      • Designates whether or not to show the scroll-bar thumbs on the scrollable container
    • options.persistThumbs {Boolean: false}
      • Designates whether or not to fade the thumbs in and out
    • options.scrollLeft {Integer: undefined}
      • Start the overscrolled element at a particular left offset. Defers to the browser default if not set
    • options.scrollTop {Integer: undefined}
      • Start the overscrolled element at a particular top offset. Defers to the browser default if not set
    • options.direction {String: 'auto'}
      • The scroll direction of the overscrolled element, by default it will auto-detect the available directions. You can also restrict direction by setting this property equal to 'vertical' or 'horizontal'
    • options.cancelOn {String: ""}
      • An optional jQuery selector to ignore on drag events. Note: must match an element inside the overscrolled element.
    • options.wheelDirection {String: 'vertical'}
      • The direction scrolled when the mouse wheel is triggered. Options are 'horizontal' for left/right scrolling and 'vertical' for up/down scrolling.
    • options.wheelDelta {Number: 20}
      • The amount of drift to apply per mouse wheel 'tick'
    • options.scrollDelta {Number: 5.7}
      • The amount of drift to apply per drag interval
    • options.zIndex {Number: 999}
      • The z-index applied to the thumb elements


  • Returns an overscrolled element to its pre-overscroll state. This is essentially a deconstructor for overscrolled elements.


Apart from regular DOM events, overscrolled elements emit events to capture dragging and drifting boundaries. To listen to these events, simply listen for one of the following events on an overscrolled element:

  • overscroll:dragstart
    • The beginning of the drag event, happens when a user drags the overscrolled elemnent
  • overscroll:dragend
    • The end of the drag event, happens after the drag, but before the drift
  • overscroll:driftstart
    • Happens right after overscroll:dragend, but only if the drag had enough inertia
  • overscroll:driftend
    • The end of a drift, happens after the drift effect completes

Here is an example using jQuery's bind() method, listening for drag start:

$('#selector').overscroll().bind('overscroll:dragstart', function(){ console.log('Drag started!') });


In order to get the most out of this plugin, make sure to only apply it to parent elements that are smaller than the collective width and/or height then their children. This way, you can see the actual scroll effect as you pan the element.

While you can programatically control whether or not overscroll allows horizontal and/or vertical scroll, it is best practice to size the child elements accordingly (via CSS) and not depend on programatic restrictions.

As of 1.3.1, if you would like to add click handlers to links inside of overscroll, you can dynamially check the state of the overscrolled element via the jQuery's data() method. This ability should allow you to prevent default behavior of a click handler if a drag state is detected. For example, an overscrolled jQuery element elm can be checked for drag state via"dragging").

As of 1.4.4 you can call the overscroll constructor on a jQuery element as much as you like, without worrying about memory leaks. What this means is that you may dynamically add elements to the overscrolled element, and then re-call the overscroll method to take into account the new height. This would have been done programatically if DOM Elements supported the resize event, alas only the window object supports this event.

Change Log

Something went wrong with that request. Please try again.