.nodemonignore (36, 2016-06-27)
bower.json (662, 2016-06-27)
build (0, 2016-06-27)
build.js (4266, 2016-06-27)
build\iscroll-infinite.js (41899, 2016-06-27)
build\iscroll-lite.js (26331, 2016-06-27)
build\iscroll-probe.js (54249, 2016-06-27)
build\iscroll-zoom.js (58281, 2016-06-27)
build\iscroll.js (53613, 2016-07-31)
CONTRIBUTING.md (306, 2016-06-27)
demos (0, 2016-06-27)
demos\2d-scroll (0, 2016-06-27)
demos\2d-scroll\index.html (7618, 2016-06-27)
demos\barebone (0, 2016-06-27)
demos\barebone\index.html (3962, 2016-06-27)
demos\bounce-easing (0, 2016-06-27)
demos\bounce-easing\index.html (3705, 2016-06-27)
demos\carousel (0, 2016-06-27)
demos\carousel\gaugin.jpg (10618, 2016-06-27)
demos\carousel\giotto.jpg (16561, 2016-06-27)
demos\carousel\index.html (3397, 2016-06-27)
demos\carousel\leonardo.jpg (7894, 2016-06-27)
demos\carousel\warhol.jpg (12457, 2016-06-27)
demos\click (0, 2016-06-27)
demos\click\index.html (3870, 2016-06-27)
demos\event-passthrough (0, 2016-06-27)
demos\event-passthrough\index.html (5397, 2016-06-27)
demos\forms (0, 2016-06-27)
demos\forms\index.html (3733, 2016-06-27)
demos\horizontal (0, 2016-06-27)
demos\horizontal\index.html (3455, 2016-06-27)
demos\infinite (0, 2016-06-27)
demos\infinite\dataset.php (393, 2016-06-27)
demos\infinite\index.html (5108, 2016-06-27)
demos\key-bindings (0, 2016-06-27)
demos\key-bindings\index.html (3680, 2016-06-27)
demos\minimap (0, 2016-06-27)
demos\minimap\ermine.jpg (155092, 2016-06-27)
... ...
iScroll, smooth scrolling for the web
iScroll is a high performance, small footprint, dependency free, multi-platform javascript scroller.
It works on desktop, mobile and smart TV. It has been vigorously optimized for performance and size so to offer the smoothest result on modern and old devices alike.
iScroll does not just *scroll*. It can handle any element that needs to be moved with user interaction. It adds scrolling, zooming, panning, infinite scrolling, parallax scrolling, carousels to your projects and manages to do that in just 4kb. Give it a broom and it will also clean up your office.
Even on platforms where native scrolling is good enough, iScroll adds features that wouldn't be possible otherwise. Specifically:
* Granular control over the scroll position, even during momentum. You can always get and set the x,y coordinates of the scroller.
* Animation can be customized with user defined easing functions (bounce, elastic, back, ...).
* You can easily hook to a plethora of custom events (onBeforeScrollStart, onScrollStart, onScroll, onScrollEnd, flick, ...).
* Out of the box multi-platform support. From older Android devices to the latest iPhone, from Chrome to Internet Explorer.
iScroll is all about optimization. To reach the highest performance it has been divided into multiple versions. You can pick the version that better suits your need.
Currently we have the following fragrances:
* **iscroll.js**, it is the general purpose script. It includes the most commonly used features and grants very high performance in a small footprint.
* **iscroll-lite.js**, it is a stripped down version of the main script. It doesn't support snap, scrollbars, mouse wheel, key bindings. But if all you need is scrolling (especially on mobile) *iScroll lite* is the smallest, fastest solution.
* **iscroll-probe.js**, probing the current scroll position is a demanding task, that's why I decided to build a dedicated version for it. If you need to know the scrolling position at any given time, this is the iScroll for you. (I'm making some more tests, this might end up in the regular `iscroll.js` script, so keep an eye on it).
* **iscroll-zoom.js**, adds zooming to the standard scroll.
* **iscroll-infinite.js**, can do infinite and cached scrolling. Handling very long lists of elements is no easy task for mobile devices. *iScroll infinite* uses a caching mechanism that lets you scroll a potentially infinite number of elements.
Getting started
So you want to be an iScroll master. Cool, because that is what I'll make you into.
The best way to learn the iScroll is by looking at the demos. In the archive you'll find a `demo` folder [stuffed with examples](https://github.com/cubiq/iscroll/tree/master/demos). Most of the script features are outlined there.
`IScroll` is a class that needs to be initiated for each scrolling area. There's no limit to the number of iScrolls you can have in each page if not that imposed by the device CPU/Memory.
Try to keep the DOM as simple as possible. iScroll uses the hardware compositing layer but there's a limit to the elements the hardware can handle.
The optimal HTML structure is:
```html
```
iScroll must be applied to the wrapper of the scrolling area. In the above example the `UL` element will be scrolled. Only the first child of the container element is scrolled, additional children are simply ignored.
box-shadow, opacity, text-shadow and alpha channels are all properties that don't go very well together with hardware acceleration. Scrolling might look good with few elements but as soon as your DOM becomes more complex you'll start experiencing lag and jerkiness.
Sometimes a background image to simulate the shadow performs better than box-shadow. The bottom line is: experiment with CSS properties, you'll be surprised by the difference in performance a small CSS change can do.
The minimal call to initiate the script is as follow:
```html
```
The first parameter can be a string representing the DOM selector of the scroll container element OR a reference to the element itself. The following is a valid syntax too:
```js
var wrapper = document.getElementById('wrapper');
var myScroll = new IScroll(wrapper);
```
So basically either you pass the element directly or a string that will be given to `querySelector`. Consequently to select a wrapper by its class name instead of the ID, you'd do:
```js
var myScroll = new IScroll('.wrapper');
```
Note that iScroll uses `querySelector` not `querySelectorAll`, so only the first occurrence of the selector is used. If you need to apply iScroll to multiple objects you'll have to build your own cycle.
You don't strictly need to assign the instance to a variable (myScroll), but it is handy to keep a reference to the iScroll.
For example you could later check the scroller position or unload unnecessary events when you don't need the iScroll anymore.
Initialization
The iScroll needs to be initiated when the DOM is ready. The safest bet is to start it on window `onload` event. `DOMContentLoaded` or inline initialization are also fine but remember that the script needs to know the height/width of the scrolling area. If you have images that don't have explicit width/height declaration, iScroll will most likely end up with a wrong scroller size.
Add position:relative or absolute to the scroll container (the wrapper). That alone usually solves most of the problems with wrongly calculated wrapper dimensions.
To sum up, the smallest iScroll configuration is:
```html
...
...
```
Refer to the [barebone example](http://lab.cubiq.org/iscroll5/demos/barebone/) for more details on the minimal CSS/HTML requirements.
If you have a complex DOM it is sometimes smart to add a little delay from the onload event to iScroll initialization. Executing the iScroll with a 100 or 200 milliseconds delay gives the browser that little rest that can save your ass.
Configuring the iScroll
iScroll can be configured by passing a second parameter during the initialization phase.
```js
var myScroll = new IScroll('#wrapper', {
mouseWheel: true,
scrollbars: true
});
```
The example above turns on mouse wheel support and scrollbars.
After initialization you can access the *normalized* values from the `options` object. Eg:
```js
console.dir(myScroll.options);
```
The above will return the configuration the `myScroll` instance will run on. By *normalized* I mean that if you set `useTransform:true` (for example) but the browser doesn't support CSS transforms, `useTransform` will be `false`.
Understanding the core
iScroll uses various techniques to scroll based on device/browser capability. **Normally you don't need to configure the engine**, iScroll is smart enough to pick the best for you.
Nonetheless it is important to understand which mechanisms iScroll works on and how to configure them.
###
options.useTransform
By default the engine uses the `transform` CSS property. Setting this to `false` scrolls like we were in 2007, ie: using the `top`/`left` (and thus the scroller needs to be absolutely positioned).
This might be useful when scrolling sensitive content such as Flash, iframes and videos, but be warned: performance loss is huge.
Default: `true`
###
options.useTransition
iScroll uses CSS transition to perform animations (momentum and bounce). By setting this to `false`, `requestAnimationFrame` is used instead.
On modern browsers the difference is barely noticeable. On older devices transitions perform better.
Default: `true`
###
options.HWCompositing
This option tries to put the scroller on the hardware layer by appending `translateZ(0)` to the transform CSS property. This greatly increases performance especially on mobile, but there are situations where you might want to disable it (notably if you have too many elements and the hardware can't catch up).
Default: `true`
If unsure leave iScroll decide what's the optimal config. For best performance all the above options should be set to true (or better leave them undefined as they are set to true automatically). You may try to play with them in case you encounter hiccups and memory leaks.
Basic features
###
options.bounce
When the scroller meets the boundary it performs a small bounce animation. Disabling bounce may help reach smoother results on old or slow devices.
Default: `true`
###
options.click
To override the native scrolling iScroll has to inhibit some default browser behaviors, such as mouse clicks. If you want your application to respond to the *click* event you have to explicitly set this option to `true`. Please note that it is suggested to use the custom `tap` event instead (see below).
Default: `false`
###
options.disableMouse
options.disablePointer
options.disableTouch
By default iScroll listens to all pointer events and reacts to the first one that occurs. It may seem a waste of resources but feature detection has proven quite unreliable and this *listen-to-all* approach is our safest bet for wide browser/device compatibility.
If you have an internal mechanism for device detection or you know in advance where your script will run on, you may want to disable all event sets you don't need (mouse, pointer or touch events).
For example to disable mouse and pointer events:
```js
var myScroll = new IScroll('#wrapper', {
disableMouse: true,
disablePointer: true
});
```
Default: `false`
###
options.eventPassthrough
Sometimes you want to preserve native vertical scroll but being able to add an horizontal iScroll (maybe a carousel). Set this to `true` and the iScroll area will react to horizontal swipes only. Vertical swipes will naturally scroll the whole page.
See [event passthrough demo](http://lab.cubiq.org/iscroll5/demos/event-passthrough/) on a mobile device. Note that this can be set to `'horizontal'` to inverse the behavior (native horizontal scroll, vertical iScroll).
###
options.freeScroll
This is useful mainly on 2D scrollers (when you need to scroll both horizontally and vertically). Normally when you start scrolling in one direction the other is locked.
Sometimes you just want to move freely with no constrains. In these cases you can set this option to `true`. See [2D scroll demo](http://lab.cubiq.org/iscroll5/demos/2d-scroll/).
Default: `false`
###
options.keyBindings
Set this to `true` to activate keyboard (and remote controls) interaction. See the [Key bindings](#key-bindings) section below for more information.
Default: `false`
###
options.invertWheelDirection
Meaningful when mouse wheel support is activated, in which case it just inverts the scrolling direction. (ie. going down scrolls up and vice-versa).
Default: `false`
###
options.momentum
You can turn on/off the momentum animation performed when the user quickly flicks on screen. Turning this off greatly enhance performance.
Default: `true`
###
options.mouseWheel
Listen to the mouse wheel event.
Default: `false`
###
options.preventDefault
Whether or not to `preventDefault()` when events are fired. This should be left `true` unless you really know what you are doing.
See `preventDefaultException` in the [Advanced features](#advanced-features) for more control over the preventDefault behavior.
Default: `true`
###
options.scrollbars
Wheter or not to display the default scrollbars. See more in the [Scrollbar](#scrollbar) section.
Default: `false`.
###
options.scrollX
options.scrollY
By default only vertical scrolling is enabled. If you need to scroll horizontally you have to set `scrollX` to `true`. See [horizontal demo](http://lab.cubiq.org/iscroll5/demos/horizontal/).
See also the **freeScroll** option.
Default: `scrollX: false`, `scrollY: true`
Note that scrollX/Y: true has the same effect as overflow: auto. Setting one direction to false helps to spare some checks and thus CPU cycles.
###
options.startX
options.startY
By default iScroll starts at `0, 0` (top left) position, you can instruct the scroller to kickoff at a different location.
Default: `0`
###
options.tap
Set this to `true` to let iScroll emit a custom `tap` event when the scroll area is clicked/tapped but not scrolled.
This is the suggested way to handle user interaction with clickable elements. To listen to the tap event you would add an event listener as you would do for a standard event. Example:
```js
element.addEventListener('tap', doSomething, false); \\ Native
$('#element').on('tap', doSomething); \\ jQuery
```
You can also customize the event name by passing a string. Eg:
```js
tap: 'myCustomTapEvent'
```
In this case you'd listen to `myCustomTapEvent`.
Default: `false`
The scrollbars are more than just what the name suggests. In fact internally they are referenced as *indicators*.
An indicator listens to the scroller position and normally it just shows its position in relation to whole, but what it can do is so much more.
Let's start with the basis.
###
options.scrollbars
As we mentioned in the [Basic features section](#basic-features) there's only one thing that you got to do to activate the scrollbars in all their splendor, and that one thing is:
```js
var myScroll = new IScroll('#wrapper', {
scrollbars: true
});
```
Of course the default behavior can be personalized.
###
options.fadeScrollbars
When not in use the scrollbar fades away. Leave this to `false` to spare resources.
Default: `false`
###
options.interactiveScrollbars
The scrollbar becomes draggable and user can interact with it.
Default: `false`
###
options.resizeScrollbars
The scrollbar size changes based on the proportion between the wrapper and the scroller width/height. Setting this to `false` makes the scrollbar a fixed size. This might be useful in case of custom styled scrollbars ([see below](#styling-the-scrollbar)).
Default: `true`
###
options.shrinkScrollbars
When scrolling outside of the boundaries the scrollbar is shrunk by a small amount.
Valid values are: `'clip'` and `'scale'`.
`'clip'` just moves the indicator outside of its container, the impression is that the scrollbar shrinks but it is simply moving out of the screen. If you can live with the visual effect this option **immensely improves overall performance**.
`'scale'` turns off `useTransition` hence all animations are served with `requestAnimationFrame`. The indicator is actually varied in size and the end result is nicer to the eye.
Default: `false`
Note that resizing can't be performed by the GPU, so scale is all on the CPU.
If your application runs on multiple devices my suggestion would be to switch this option to 'scale', 'clip' or false based on the platform responsiveness (eg: on older mobile devices you could set this to 'clip' and on desktop browser to 'scale').
See the [scrollbar demo](http://lab.cubiq.org/iscroll5/demos/scrollbars/).
So you don't like the default scrollbar styling and you think you could do better. Help yourself! iScroll makes dressing the scrollbar a snap. First of all set the `scrollbars` option to `'custom'`:
```js
var myScroll = new IScroll('#wrapper', {
scrollbars: 'custom'
});
```
Then use the following CSS classes to style the little bastards.
* **.iScrollHorizontalScrollbar**, this is applied to the horizontal container. The element that actually hosts the scrollbar indicator.
* **.iScrollVerticalScrollbar**, same as above but for the vertical container.
* **.iScrollIndicator**, the actual scrollbar indicator.
* **.iScrollBothScrollbars**, this is added to the container elements when both scrollbars are shown. Normally just one (horizontal or vertical) is visible.
The [styled scrollbars demo](http://lab.cubiq.org/iscroll5/demos/styled-scrollbars/) should make things clearer than my lousy explanation.
If you set `resizeScrollbars: false` you could make the scrollbar of a fixed size, otherwise it would be resized based on the scroller length.
Please keep reading to the following section for a revelation that will shake your world.
Indicators
All the scrollbar options above are in reality just wrappers to the low level `indicators` option. It looks more or less like this:
```js
var myScroll = new IScroll('#wrapper', {
indicators: {
el: [element|element selector]
fade: false,
ignoreBoundaries: false,
interactive: false,
listenX: true,
listenY: true,
resize: true,
shrink: false,
speedRatioX: 0,
speedRatioY: 0,
}
});
```
###
options.indicators.el
This is a mandatory parameter which holds a reference to the scrollbar container element. The first child inside the container will be the indicator. Note that the scrollbar can be anywhere on your document, it doesn't need to be inside the scroller wrapper. Do you start perceiving the power of such tool?
Valid syntax would be:
```js
indicators: {
el: document.getElementById('indicator')
}
```
Or simply:
```js
indicators: {
el: '#indicator'
}
```
###
options.indicators.ignoreBoundaries
This tells the indicator to ignore the boundaries imposed by its container. Since we can alter the speed ratio of the scrollbar, it is useful to just let the scrollbar go. Say you want the indicator to go twice as fast as the scroller, it would reach the end of its run very quickly. This option is used for [parallax scrolling](#parallax-scrolling).
Default: `false`
###
options.indicators.listenX
options.indicators.listenY
To which axis the indicator listens to. It can be just one or both.
Default: `true`
###
options.indicators.speedRatioX
options.indicators.speedRatioY
The speed the indicator moves in relation to the main scroller size. By default this is ... ...