awlka / viewport-units-buggyfill

Making viewport units (vh|vw|vmin|vmax) work properly in Mobile Safari.

Viewport Units Buggyfill™

Making viewport units (vh|vw|vmin|vmax) work properly in Mobile Safari.

This is a buggyfill (fixing bad behavior), not a polyfill (adding missing behavior). If the browser doesn't know how to deal with the viewport units - vw, vh, vmin and vmax - it won't gain the capability through this script, because this buggyfill uses the CSSOM to access the defined styles.

The buggyfill iterates through all defined styles the document knows and extracts those that uses a viewport unit. After resolving the relative units against the viewport's dimensions, CSS is put back together and injected into the document in a <style> element. Listening to the orientationchange event allows the buggyfill to update the calculated dimensions accordingly.

Note: This buggyfill only works on stylesheets! viewport units used in style attributes are not resolved.

Using viewport-units-buggyfill

After loading the buggyfill from npm (npm install viewport-units-buggyfill) or bower (bower install viewport-units-buggyfill), it has to be required and initialized:

require('viewport-units-buggyfill').init();

If you're - for whatever reason - not using a package manager, include the script as follows:

<script src="viewport-units-buggyfill.js"></script>
<script>window.viewportUnitsBuggyfill.init();</script>

API

viewport-units-buggyfill exposes the following API:

var viewportUnitsBuggyfill = require('viewport-units-buggyfill');

// find viewport-unit declarations,
// convert them to pixels,
// inject style-element into document,
// register orientationchange event to repeat when necessary
// will only engage for Mobile Safari on iOS
viewportUnitsBuggyfill.init();
// ignore user agent force initialization
viewportUnitsBuggyfill.init(true);

// update internal declarations cache and recalculate pixel styles
// this is handy when you add styles after .init() was run
viewportUnitsBuggyfill.refresh();

// you can do things manually (without the style-element injection):
// identify all declarations using viewport units
viewportUnitsBuggyfill.findProperties();
var cssText = viewportUnitsBuggyfill.getCss();

Cross Origin Stylesheets

Warning: Including stylesheets from third party services, like Google WebFonts, requires those resources to be served with appropriate CORS headers.

Changelog

0.3.1 (April 16th 2014)

• fixing browser detection to include UIWebView - Issue #7, tylerstalder

0.3.0 (April 9th 2014)

• fixing cross origin resource problem with CSSOM - Issue #6

0.2.3 (March 10th 2014)

• fixing multiple competing media-attribute-switched stylesheets - Issue #5
• fixing double initialization and call of reresh() without being initialized - Issue #3
• fixing <br>s caused by innerText by using textContent instead

0.2.2 (January 31st 2014)

• fixing unhandled empty <style> elements - Issue #2

0.2.1 (January 25th 2014)

• adding force option to init()
• fixing the handling of non-iterable CSSRules - Issue #1

0.2.0 (January 24th 2014)

• optimizing generated CSS (by grouping selectors)
• adding browser sniffing

0.1.0 (January 23rd 2014)

• Initial Version

License

viewport-unit-buggyfill is published under the MIT License.