A tiny, no-frills, framework-independent, targeted overflow: auto polyfill for use in responsive design.
What is this all about?
You want to use CSS overflow in your designs, but overflow doesn't work properly in many browsers, particularly mobile ones. Many popular mobile browsers treat overflow: auto the same as overflow: hidden, cropping overflow content from view, and leaving users no way to access it.
But wait - many browsers actually support overflow very well! In particular, desktop browsers tend to support it without a hitch, and many of the latest versions of most mobile platforms do too. The trouble is, it's hard – perhaps impossible – to test for overflow support, and even if we could use it safely where supported, many popular browsers lack that support and would be left with a degraded experience.
What is Overthrow?
Overthrow is a conservative attempt at filling the gaps in overflow support, with an emphasis on letting native implementations do their thing, and in touch-supporting browsers, providing a very minimal polyfill in browsers where native support is not available. Out of necessity, Overthrow examines the user agent string to whitelist the current and future versions of mobile platforms that are known to have native overflow support, but not before checking through more reliable and agnostic means: namely, iOS5's (and now Chrome Android's too!) touch scrolling CSS property, and a broad desktop browser inference test (no touch event support with a screen greater than 1200px wide).
First and foremost, Overthrow is designed to simply enable native CSS overflow in browsers it deems to have native support, but it includes a touch-scrolling polyfill too! In platforms that don't appear to support overflow natively, but do support touch events, Overthrow will polyfill the feature, allowing momentum-based scrolling in browsers that might otherwise be left with an innaccessible experience.
Perhaps most importantly, Overthrow enables overflow support as a qualified, progressive enhancement, meaning your content starts out uncropped and accessible, and properties like width and height are assigned only in browsers where overflow content can reliably be scrolled (either natively or with the polyfill). In browsers that don't support overflow natively, and also don't support touch events, the content will not receive dimensions at all, leaving users with a degraded but accessible experience.
A few example pages
The examples directory has some sample responsive layouts that use overthrow. If you're in a browser that supports overthrow, you'll find a link in the header to toggle it on and off, demonstrating the fallback experience for non-overflow browsers.
Features
- Lightweight JavaScript: 1.6kb after min/gzip
- Dual MIT / BSD 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: Rather than simulating scrolling with CSS properties, the native JavaScript
scrollTopandscrollLeftproperties are used. This means any you can use any standard web conventions for scrolling an overthrow element, such as#fragmentanchor links, and so on. - Safe for form elements: Overthrow doesn't interfere with form controls
- Nestable (partial support): just like standard CSS overflow, overthrow elements can nest inside one another.
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:
| User Agent | Result |
|---|---|
| Chrome (desktop) | native |
| Firefox (desktop) | native |
| Internet Explorer (desktop) | native |
| Opera (desktop) | native |
| Safari (desktop) | native |
| Any browser on screen > 1200px wide w/ no touch support | native |
| Mobile Safari on iOS5: iPhone, iPod, iPad | native |
| Chrome on Android | native |
| Webkit on Android 3.0+ | native |
| Nokia N8 WebKit | native |
| BlackBerry 7 WebKit | native |
| BlackBerry PlayBook Webkit | native |
| Firefox Mobile (Fennec) 4+ | native |
| Mobile Safari on iOS4 and older: iPhone, iPod, iPad | polyfilled |
| Android 2.3 and under, WebKit | polyfilled |
| Nokia N9, WebKit | polyfilled |
| BlackBerry 6, WebKit | polyfilled |
| Opera Mini | none |
| Opera Mobile | none |
| Windows Phone 7 and 7.5 | none |
| BlackBerry 5 and under | none |
| Nokia Devices without touch event support | none |
| Any non-touch supporting device | none |
How do I use it?
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 scrolling.
<div id="foo" class="overthrow">Content goes here!</div>
In browsers that Overthrow.js deems capable of scrolling overflowed content (either natively, or using its polyfill), it will add a class of overthrow-enabled to the HTML element. Add this 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;
}
Lastly, design away! Any time you want to set dimensions on an element to trigger overflow scrolling, just be sure to key off that overthrow-enabled class on the html element.
.overthrow-enabled #foo {
height: 280px;
}
API
Overflow adds one variable to the global namespace: overthrow. It has the following methods and properties:
- overthrow.set: function to initialize overthrow behavior and style in the page. Adds "overthrow-enabled" class to
htmlelement, and touch listener for polyfilled browsers - overthrow.forget: function to remove overthrow behavior and style in the page. Removes "overthrow-enabled" class from HTML element, and touch event listener in polyfilled browsers, and restores default easing.
- overthrow.easing: an overrideable property that stores the default easing function (using any of Robert Penner's easing equations.)
- overthrow.toss: function to programatically scroll an overthrow element.
To call, pass a required first argument referencing the overthrow element to scroll, and a hash of optional configuration properties.
overthrow.toss( element, { top: 500 } );Options
- left: the desired horizontal scroll. Default is "+0". For relative distances, pass a string with "+" or "-" in front.
- top: the desired vertical scroll. Default is "+0". For relative distances, pass a string with "+" or "-" in front.
- duration: is the number of milliseconds the throw will take. Default is 100.
- easing: an optional custom easing function. Default is the included ease-out cubic equation. Overrides must follow the easing function signature of Robert Penner easing equations, which have 4 arguments: t = current iteration, b = initial value, c = end value, d = total iterations.
- overthrow.intercept: stop a toss that is currently iterating
- overthrow.support: string representing the browser's overthrow support type: "native", "polyfilled", or "none"
Issues
For known issues with Overthrow, or to file a new one, please visit the issue tracker.
That's about it.
Here's some extra demo content to scroll through...
Example Embedded Overthrow Block
Note: this may be a little clunky at the moment, as nesting isn't quite finished. Check out the nesting branch for progress.
Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui. Donec non enim in turpis pulvinar facilisis. Ut felis.