FTScroller

FTScroller is a library for adding momentum scrolling to web content on devices with a touch interface, compatible across most modern platforms including desktop browsers. Although recently support for overflow: scroll (or touch equivalents) has increased, this is often still not implemented in a cross-platform or backwards-compatible way, and with no support for features like snapping.

FTScroller is developed by FT Labs, part of the Financial Times. It is inspired by Touchscroll and Zynga Scroller, but is a complete rewrite. It is extensively used in the FT Web App, and was developed to achieve better performance and compatibility, including mouse and touch input.

Usage

Include ftscroller.js in your JavaScript bundle or add it to your HTML page like this:

<script type='text/javascript' src='/path/to/ftscroller.js'></script>

The script must be loaded prior to instantiating a scroller on any element of the page.

To create a scroller, with a few minimal options:

var containerElement, scroller;

containerElement = document.getElementById('scrollcontainer');

scroller = new FTScroller(containerElement, {
	scrollbars: false,
	scrollingX: false
});

Examples

FTScroller is designed to accommodate a range of use cases. Here are some examples - feel free to copy the code and use as the basis for your own projects.

Vertical continuous list
Horizontal paged (and a strict version, constrained to scrolling one page at a time)
Multiple vertical scrollers in a horizontally paged scroller
Whole page scroller

Options

Options must be specified at create-time by passing a JSON object as the second argument to the FTScroller constructor.

alwaysScroll Whether to always enable scrolling, even if the content of the scroller is not large enough to spill out of the container. This makes the scroller behave more like an element set to "overflow: scroll", with bouncing always occurring if enabled (boolean, default false)
baseAlignments Determines where to anchor the content when the scroller is set up, specified individually for each axis using a JSON object with the keys x and y. Valid alignments for each axis are -1 (top or left), 0 (center), and 1 (bottom or right). For example, the default baseAlignments of {x:-1,y:-1} will display the scroller initially scrolled to the top left of its range. This also affects the alignment of content where the content is smaller than the scroller.
bouncing Allow scroll bouncing and elasticity near the ends of the range and at snap points (boolean, default true)
contentWidth Define the scrollable width; if not defined, this will match the content width (numeric, default undefined)
contentHeight Define the scrollable height; if not defined, this will match the content height (numeric, default undefined)
disabledInputMethods Define any input methods to disable; on some multi-input devices custom behaviour may be desired for some scrollers. No inputs methods are disabled by default. (object, default { mouse: false, touch: false, scroll: false, pointer: false, focus: false })
enableRequestAnimationFrameSupport FTScroller will use requestAnimationFrame on platforms which support it, which is highly recommended; however this can result in the animation being a further half-frame behind the input method, increasing perceived lag slightly. To disable this, set this property to false. (boolean, default true)
flinging Allow a fast scroll to continue with momentum when released (boolean, default true)
hwAccelerationClass FTScroller uses normal translate properties rather than translate3d to position content when scrolling, and triggers hardware acceleration by adding CSS properties (specifically backface-visibility) to this class on platforms that support it. Adjusting this class allows for negotiating complex CSS inheritance to override the default behaviour of FTScroller if you want to change or disable backing layers/3D acceleration. (string, default an internal class which triggers backing layers)
maxFlingDuration Set the maximum time (ms) that a fling can take to complete once the input has ended (numeric, default 1000ms)
scrollbars Whether to display iOS-style scrollbars (which you can style yourself using .ftscroller_scrollbar and .ftscroller_scrollbarx/.ftscroller_scrollbary) while the content is animating (boolean, default true)
scrollBoundary The initial movement required to trigger a full scroll, in pixels; this is the point at which the scroll is exclusive to this particular FTScroller instance and flings become active (integer, default 1)
scrollingClassName The classname to add to the scroller container when it is being actively scrolled. This is disabled by default as it can cause a CSS relayout if enabled, but allows custom styling in response to scrolls (string, default not set)
scrollResponseBoundary The initial movement required to trigger a visual scroll update, in pixels (integer, default 1)
scrollingX Enable scrolling on the X axis if content is available (boolean, default true)
scrollingY Enable scrolling on the Y axis if content is available (boolean, default true)
singlePageScrolls (was paginatedSnap) If snapping is enabled, restricts each scroll movement to one 'page' span. That is, if set to true, it will not be possible to move more than one page in a single movement. (boolean, default false)
snapping Enable snapping of content to defined 'pages' or segments (boolean, default false)
snapSizeX Define the horizontal interval content should snap to, in pixels. If this is not set, snapping will be based on pages corresponding to the container size. (numeric, default undefined)
snapSizeY Define the vertical interval content should snap to, in pixels. If this is not set, snapping will be based on pages corresponding to the container size. (numeric, default undefined)
updateOnChanges Automatically detect changes to the content of the scrollable element and update the scroller dimensions whenever the content changes. This is set to false automatically if contentWidth and contentHeight are specified (boolean, default true)
updateOnWindowResize Automatically catch changes to the window size and update the dimensions of the scroller. It's advisable to set this to true if the scroller has a flexible width or height based on the viewport size. (boolean, default false)
windowScrollingActiveFlag Whether to use a global property of the window object to control whether to allow scrolling to start or not. If the specified window property is set to a truthy value, the scroller will not react to input. If the property is not truthy, the scroller will set it to itself and will scroll. Where multiple scrollers exist on the same page, this ensures that only one can be used at a time, which is particularly useful for nested scrollers (see Multiple vertical scrollers in a horizontally paged scroller). Note that FTScroller automatically allows only one scroller instance to be scrolled at once; use this flag to coordinate input with other parts of your code. (string, default not set)
flingBezier The bezier curve to use for momentum-like flings. (CubicBezier, default CubicBezier(0.103, 0.389, 0.307, 0.966))
bounceDecelerationBezier The bezier curve to use for deceleration when a fling hits the bounds. (CubicBezier, default CubicBezier(0, 0.5, 0.5, 1))
bounceBezier The bezier curve to use for bouncebacks when the scroll exceeds the bounds. (CubicBezier, default CubicBezier(0.7, 0, 0.9, 0.6))
invertScrollWheel If the scroller is constrained to an x axis, convert y scroll to allow single-axis scroll wheels to scroll constrained content. (boolean, default true)

Public interface

Once the scroller has been applied to an element, the return value from the constructor is an object that offers a number of public properties, methods and events.

Properties

scrollHeight Gets the scrollable height of the contained content. Read only
scrollLeft Gets or sets the current left scroll offset of the scroller in pixels. When set, will cause the scroller to jump to that position (without animating)
scrollTop Gets or sets the current top scroll offset of the scroller in pixels. When set, will cause the scroller to jump to that position (without animating)
scrollWidth Gets the scrollable width of the contained content. Read only
segmentCount When snapping is enabled, returns the number of snap segments (which in many use cases can be considered 'pages'). Read only.
currentSegment Returns the index of the current segment, starting from 0. Updated when the scroller comes to rest on a new segment. Applies only when snapping is set to true. Read only.
contentContainerNode Returns the DOM node that contains the scroller contents, for use if you want to amend the contents. Read only.

Methods

addEventListener(eventname, callback) Attaches a specified function to an FTScroller custom event. Available events are listed in the events section below. The function will be called by FTScroller when the event occurs.
destroy(removeElements) Unbinds all event listeners to prevent circular references preventing items from being deallocated, and clean up references to dom elements. Does not remove scroller marku

Ftscroller

Install / Use

README