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 keysx
andy
. 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
(waspaginatedSnap
) 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 ifcontentWidth
andcontentHeight
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 onlyscrollLeft
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 onlysegmentCount
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 whensnapping
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 markup from the DOM unless the optionalremoveElements
argument is set to a truthy value.removeEventListener(eventname, callback)
Removes a previously bound function from an event. The function specified in the mathod must be the same object reference passed in theaddEventListener
call (not a redefinition of the same function code)scrollBy(horizontal, vertical[, duration])
Similar toscrollTo
but allows scrolling relative to the current position rather than to an absolute offset.scrollTo(left, top[, duration])
Scroll to a specified left and top offet over a specified duration. If duration is zero, no animation will occur. If duration istrue
FTScroller will itself choose a duration based on the distance to be scrolled. The left and top inputs will be constrained by the size of the content and the snap points. If false is supplied for either left or top, that axis will not be scrolled and will retain its current offset.setSnapSize(width, height)
Configures the snapping boundaries within the scrolling element if snapping is active. If this is never called, segment size defaults to the width and height of the scroller, ie. page-at-a-time.updateDimensions(width, height[, nosnap])
Sets the dimensions of the scrollable content. If snapping is enabled, and you wish to disable updates of the snapping grid and prevent the current position from being updated, setnosnap
to true; it defaults to false if not supplied.setDisabledInputMethods(disabledInputMethods)
Set the input methods to disable. No inputs methods are disabled by default.(object, default { mouse: false, touch: false, scroll: false, pointer: false, focus: false })
Prototype methods
getPrependedHTML([excludeXAxis, excludeYAxis, hwAccelerationClass])
- Provides half of the HTML that is used to construct the scroller DOM, for use to save a DOM manipulation on Scroller initialisation (see Tips and tricks below). Optionally the x and y axes can be excluded, or a custom layer backing triggering class can be supplied (see thehwAccelerationClass
option for the constructor).getAppendedHTML([excludeXAxis, excludeYAxis, hwAccelerationClass, scrollbars])
- Provides the second half of the HTML that is used to construct the scroller DOM, for use to save a DOM manipulation on Scroller initialisation (see Tips and tricks below). Optionally the x and y axes can be excluded, or a custom layer backing triggering class can be supplied (see thehwAccelerationClass
option for the constructor). Pass a truthy value in for thescrollbars
parameter if you are enabling scrolling. Any parameters should match those passed in togetPrependedHTML
.
Events
Events can be bound with the addEventListener
method. Events are fired syncronously. Regardless of the event, the listener function will receive a single argument.
scroll
Fired whenever the scroll position changes, continuously if an input type is modifying the position. Passes an object containingscrollLeft
andscrollTop
properties matching the new scroll position, eg{scrollLeft:10, scrollTop:45}
scrollstart
Fired when a scroll movement starts. Passes an object with the same characteristics asscroll
.scrollend
Fired when a scroll movement ends. Passes an object with the same characteristics asscroll
.segmentdidchange
Fires on completion of a scroll movement, if the scroller is on a different segment to the one it was on at the start of the movement. Passes an object withsegmentX
andsegmentY
properties.segmentwillchange
Fires as soon as the scroll position crosses a segment boundary, during a scroll movement. Passes an object withsegmentX
andsegmentY
properties.reachedstart
Fires when the scroll position reaches the top or left of a scroller. Passes an object with anaxis
property indicating whether thex
ory
axis reached its start position.reachedend
Fires when the scroll position reaches the bottom or right of a scroller. Passes an object with anaxis
property indicating whether thex
ory
axis reached its end position.
Compatibility
FTScroller supports input via mouse or touch on the following browsers:
- Apple Mobile Safari (iOS 3.2+ confirmed, best after 4.0+)
- Google Android Browser (Android 2.2+ confirmed)
- Microsoft Internet Explorer 10 (Windows 8 RTM confirmed)
- RIM BlackBerry PlayBook (2.0 confirmed, 1.0 should be fine)
- Most modern desktop browsers (IE 9+, FF 4+, Safari 3+, Chrome 1+, Opera 11.5+ - ECMAScript 5 getters and setters are currently used)
Tips and tricks
- If you are putting together the DOM in JavaScript using HTML or a template, it's advantageous to use the prototype methods for
getPrependedHTML
andgetAppendedHTML
to add the FTScroller HTML at the same time. If the elements are added to the very start and very end of the content within the element passed in to the constructor (ignoring whitespace), the Scroller instantiation will detect this and skip the DOM manipulation step, leading to faster instantiation without an additional layout. - If scrolling is going to only occur along one axis, setting
scrollingX
orscrollingY
tofalse
as part of the construction options skips creating of the corresponding DOM element, saving memory (particularly when using hardware acceleration). - Depending on your CSS, you may find that you can't scroll quite to the bottom of your content. This is typically a collapsing margin issue — the contents are measured, then wrapped in additional elements, but the margins spilling out of the contents can't be measured. If you see this, an easy fix is typically to put
overflow: hidden
either your scrollable element or its contents; that will act as a boundary for margins so everything can be measured, and typically has no effect on appearance when applied to the content as the scrollable content won't have dimensional limits.
Credits and collaboration
The lead developer of FTScroller is Rowan Beentje at FT Labs. All open source code released by FT Labs is licenced under the MIT licence. We welcome comments, feedback and suggestions. Please feel free to raise an issue or pull request. Enjoy.