Overthrow

A framework-independent, overflow: auto polyfill for use in responsive design.

• Filament Group Release Notes: Overthrow: An overflow: auto polyfill for responsive design

License: Open-source MIT license

Copyright 2013: Scott Jehl, Filament Group, Inc.

See the project site for detailed documentation.

Project Goals

The goals of Overthrow are simple: create a reliable way to safely use CSS overflow in responsive designs, polyfilling support in non-native environments where possible, and if not, letting things scroll with the rest of the page).

Features

• Lightweight, decoupled JavaScript
• MIT license: use it wherever you want.
• Designed for responsive design: safe for use in cross-device development
• Framework-independent: use with any JS library, or none at all!
• Native scrollTop and scrollLeft: Rather than simulating scrolling with CSS properties, the native JavaScript scrollTop and scrollLeft properties are used. This means any you can use any standard web conventions for scrolling an overthrow element, such as #fragment anchor links, and so on.

Download

You can grab the latest of the core and extensions on the releases pages, or see how to do a custom build below.

Demos

• Scrolling layout
• 2-Column scrolling layout
• Scrolling fake dialog contents

Basic use

First, download and reference overthrow.js from your document. Anywhere's fine.

<script src="overthrow.js"></script>

Then put a class of overthrow on any elements in which you'd like to apply overflow: auto or scroll CSS.

<div id="foo" class="overthrow">Content goes here!</div>

In browsers that Overthrow deems capable of scrolling overflow content (either natively, or using its touch polyfill), it will add a class of overthrow-enabled to the html element. Add the following CSS to your stylesheet somewhere, enabling overflow on all elements in your document that have an overthrow class.

/* Overthrow CSS:
   Enable overflow: auto on elements with overthrow class when html element has overthrow class too */
.overthrow-enabled .overthrow {
    overflow: auto;
    -webkit-overflow-scrolling: touch;
}

That's it. Design away! Any time you want to set dimensions on an element to use overflow scrolling, just be sure to key off that overthrow class on the HTML element, and overflow: auto will apply.

.overthrow-enabled #foo {
    height: 28em;
}

Properties

Overthrow exposes various properties you can access via the overthrow object:

• overthrow.support: returns a string of "native", "polyfilled", or "none" depending on the type of overflow in play.

Many overthrow settings are exposed and configurable via the overthrow object. If needed, you can redefine these before calling set().

• overthrow.enabledClassName: The class name added to the html element in supported browsers. Default is overthrow-enabled
• overthrow.scrollIndicatorClassName: The class name used to identify scrollable overthrow elements. Default is overthrow

Methods

Overthrow exposes various methods you can use via the overthrow object:

• overthrow.set(): run the overflow detection and add an overthrow-enabled class to the html element in browsers that natively support overflow. If the overthrow-polyfill.js is included, set() will also polyfill overflow behavior in touch-event supporting browsers that do not natively support it, such as iOS4 and Android 2.3. The default overthrow.js built file runs this automatically.
• overthrow.forget(): This removes the overthrow-enabled class from the html element and unbinds touch event handlers in polyfilled browsers.
• overthrow.toss(): This method scrolls to a x,y location in an overflow element. Its first argument is required reference to the element to be scrolled. The second argument is an options object.

For example:

overthrow.toss(
    document.getElementById( "foo" ),
    {
        top: 150,
        left: "+30",
        duration: 80,
        easing: function (t, b, c, d) {
            return c*((t=t/d-1)*t*t + 1) + b;
        };
    }
);

• overthrow.intercept(): Stops any toss currently animating.

Source files

Overthrow's src directory includes several files:

• overthrow-detect.js: a script that defines the overthrow global object and the overthrow.set and overthrow.forget methods. When set is called, it will add a overthrow-enabled class to the html element in browsers that natively support overflow.
• overthrow-polyfill.js: a script that extends the overthrow.set method so that it polyfills overflow behavior in touch-event supporting browsers that do not natively support it.
• overthrow-toss.js: a script that adds the overthrow.toss and overthrow.intercept methods.
• overthrow-init.js: a script that simply calls the overthrow.set method when it loads. This script can safely execute before domready.

All above files depend upon overthrow-detect.js but are otherwise independent of one another and can be used that way.

Creating a custom build

You can grab any of the above files manually from this repo, but to create a custom build of any of the above files, you'll need grunt.js. Once installed, you can check out this project's gruntfile.js file to see various pre-configured build options that are available when you run grunt.

Extension files

Overthrow's extensions directory incudes several behavioral extensions you might find useful.

• anchorscroll.overthrow.js: a script that will cause any links with a class of throw that point to in-page content (href starting with a #) to scroll with easing, via the toss method. Just include it in the page and it'll work.
• overthrow-sidescroller.js: a script that adds carousel-like behavior such as arrows and keyboard handling to a horizontally-scrolling overthrow area.

These both depend on overthrow-detect.js, overthrow-toss.js, and overthrow-init.js.

Sidescroller

Simple sidescroller with momentum scrolling

The sidescroller extension (not included by default) makes a horizontal carousel-like component of an overflow area. This provides you with carousel-like functionality, built on a system of tiered fallbacks. The Sidescroller area’s child elements can be fixed-width

Sidescroller README

See the README.

We’ve produced a number of self-contained extensions that add to or alter the basic Sidescroller functionality:

By default, the Sidescroller controls will do nothing at the start/end of navigation. There are two methods for changing this behavior:

A more extensive list of demos is available in the Sidescroller README.

Functional tests

Browser Support

Overthrow's goal is to create an accessible experience in every browser, and if possible, an enhanced experience in modern browsers. As such, Overthrow has 3 potential support situations: native, polyfilled, or none (which simply means the content is left uncropped and tall/wide). Here's where some popular browsers land on that spectrum:

    <tr><td>Mobile Safari on iOS5: iPhone, iPod, iPad</td><td><span class="native">native</span></td></tr>
    <tr><td>Chrome on Android</td><td><span class="native">native</span></td></tr>
    <tr><td>Webkit on Android 3.0+</td><td><span class="native">native</span></td></tr>
    <tr><td>Nokia N8 WebKit</td><td><span class="native">native</span></td></tr>
    <tr><td>BlackBerry 7 WebKit</td><td><span class="native">native</span></td></tr>
    <tr><td>BlackBerry PlayBook Webkit</td><td><span class="native">native</span></td></tr>
    <tr><td>Firefox Mobile (Fennec) 4+</td><td><span class="native">native</span></td></tr>

    <tr><td>Mobile Safari on iOS4 and older: iPhone, iPod, iPad</td><td><span class="polyfilled">polyfilled</span></td></tr>
    <tr><td>Android 2.3 and under, WebKit</td><td><span class="polyfilled">polyfilled</span></td></tr>
    <tr><td>Amazon Kindle Fire</td><td><span class="polyfilled">polyfilled</span></td></tr>
    <tr><td>Nokia N9, WebKit</td><td><span class="polyfilled">polyfilled</span></td></tr>
    <tr><td>BlackBerry 6, WebKit</td><td><span class="polyfilled">polyfilled</span></td></tr>

    <tr><td>Opera Mini</td><td><span class="none">none</span></td></tr>
    <tr><td>Opera Mobile</td><td><span class="none">none</span></td></tr>
    <tr><td>Windows Phone 7 and 7.5</td><td><span class="none">none</span></td></tr>
    <tr><td>BlackBerry 5 and under</td><td><span class="none">none</span></td></tr>
    <tr><td>Nokia Devices without touch event support</td><td><span class="none">none</span></td></tr>
    <tr><td>Any non-touch supporting device</td><td><span class="none">none</span></td></tr>
</tbody>

Issues

For known issues with Overthrow, or to file a new one, please visit the issue tracker

Tests

Unit tests use QUnit and can be run from the /test/ directory.