search

rodneyrehm / viewport-units-buggyfill

Making viewport units (vh|vw|vmin|vmax) work properly in Mobile Safari.
MIT License
1.59k stars 151 forks source link

readme

Viewport Units Buggyfill™

This is a buggyfill (fixing bad behavior), not a polyfill (adding missing behavior). That said, it provides hacks for you to get viewport units working in old IE and Android Stock Browser as well. If the browser doesn't know how to deal with the viewport units - vw, vh, vmin and vmax - this library will not improve the situation unless you're using the hacks detailed below. The buggyfill uses the CSSOM to access the defined styles rather than ship its own CSS parser, that'S why the hacks abuse the CSS property content to get the values across.

Amongst other things, the buggyfill helps with the following problems:

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.

The hacks use the content property to transport viewport-unit styles that need to be calculated by script, this is done because unsupporting browsers do not expose original declarations such as height: calc(100vh - 10px):

content: 'viewport-units-buggyfill; width: 50vmin; height: 50vmax; top: calc(50vh - 100px); left: calc(50vw - 100px);';

Note: The content hack may not work well on <img> and other replaced elements, even though it should compute to content: normal; on regular elements. If you find yourself in such a situation, this may be a way out:

img {
  content: normal !important;
}

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

Note: The buggyfill can easily trip over files host on different origins (requiring CORS) and relative URLs to images/fonts/… within stylesheets. #11

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="https://github.com/rodneyrehm/viewport-units-buggyfill/raw/master/viewport-units-buggyfill.js"></script>
<script>window.viewportUnitsBuggyfill.init();</script>

To engage the buggyfill with hacks, pass them in at initialization:

var hacks = require('viewport-units-buggyfill/viewport-units-buggyfill.hacks');
require('viewport-units-buggyfill').init({
  hacks: hacks
});

To exempt certain stylesheets from being processed, the attribute data-viewport-units-buggyfill="ignore":

<link rel="stylesheet" href="https://github.com/rodneyrehm/viewport-units-buggyfill/blob/master/file-to-ignore.css" data-viewport-units-buggyfill="ignore">
<link rel="stylesheet" href="https://github.com/rodneyrehm/viewport-units-buggyfill/blob/master/file-to-process.css">

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 (and resize events in IE9+) to repeat when necessary
// will only engage for Mobile Safari on iOS and IE9+
viewportUnitsBuggyfill.init();

// ignore user agent force initialization
viewportUnitsBuggyfill.init({force: true});

// reduces the amount of times the buggyfill is reinitialized on window resize in IE
// for performance reasons.
viewportUnitsBuggyfill.init({refreshDebounceWait: 250});

// This enables abusing the CSS property 'content' to allow transporting
// viewport unit values for browsers with spotty support:
//   * vmin in IE9
//   * vmax in IE9, iOS <= 6
//   * calc(vh/vmin) in iOS < 8 and Android Stock Browser <= 4.4
//   * all of viewport units in Android Stock Browser <= 4.3
//
// To engage these hacks, you need to load the hacks file as well:
//
//   <script src="https://github.com/rodneyrehm/viewport-units-buggyfill/raw/master/path/to/viewport-units-buggyfill.hacks.js"></script>
//
viewportUnitsBuggyfill.init({hacks: window.viewportUnitsBuggyfillHacks});

// append the patched stylesheet to body instead of head
viewportUnitsBuggyfill.init({appendToBody: 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();

In CSS you can declare fallbacks to be used by the buggyfill's hacks:

.my-viewport-units-using-thingie {
  width: 50vmin;
  height: 50vmax;
  top: calc(50vh - 100px);
  left: calc(50vw - 100px);

  /* hack to engage viewport-units-buggyfill */
  content: 'viewport-units-buggyfill; width: 50vmin; height: 50vmax; top: calc(50vh - 100px); left: calc(50vw - 100px);';
}

The buggyfill emits the event viewport-unit-buggyfill-init before initializing and viewport-unit-buggyfill-style after applying the fixed styles to the document. The events are dispatched on window and may be used as follows:

window.addEventListener('viewport-unit-buggyfill-init', function() {
  console.log('getting lost in CSSOM');
});
window.addEventListener('viewport-unit-buggyfill-style', function() {
  console.log('updated rules using viewport unit');
});

Cross Origin Stylesheets

Warning: Including stylesheets from third party services, like Google WebFonts, requires those resources to be served with appropriate CORS headers. You may also need to be aware of the fact that relative URLs within those stylesheets are NOT resolved, possibly leading to missing fonts and images.

Changelog

0.6.2 (July 21st 2017)

0.6.1 (March 16th 2017)

0.6.0 (March 19th 2016)

0.5.5 (August 21st 2015)

0.5.4 (July 15th 2015)

0.5.3 (April 21st 2015)

0.5.2 (April 5th 2015)

0.5.1 (March 10th 2015)

0.5.0 (December 23rd 2014)

WARNING: Breaking Changes (and a Merry Christmas to you, too :)

0.4.1 (September 8th 2014)

0.4.0 (September 8th 2014)

.myLargeBlock {
  /* Non-IE browsers */
  width: 50vmin;
  height: 50vmax;

  /* IE9 and 10 */
  behavior: 'use_css_behavior_hack: true; width: 50vmin; height: 50vmax;';
  /* WARNING: this syntax has been changed in v0.5.0 */
}
.box {
  top: calc(50vh - 100px);
  left: calc(50vw - 100px);

  /*
   * Here is the code for WebKit browsers that will allow
   * viewport-units-buggyfill.js to perform calc on viewport
   * units.
   */
   content: 'use_css_content_hack: true; top: calc(50vh -  100px); left: calc(50vw -  100px);';
  /* WARNING: this syntax has been changed in v0.5.0 */
}

0.3.1 (April 16th 2014)

0.3.0 (April 9th 2014)

0.2.3 (March 10th 2014)

0.2.2 (January 31st 2014)

0.2.1 (January 25th 2014)

0.2.0 (January 24th 2014)

0.1.0 (January 23rd 2014)

License

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