object-fit-images

object-fit-images

Polyfill object-fit and object-position on images on IE9, IE10, IE11, Edge, Safari, ...

This adds support for object-fit and object-position to IEdge 9-13, Android 4.4-, Safari (OSX 9.1-, iOS 9.3-) and skips browsers that already support them.

Take a look at the demo.

Main features

• CPU-light code
• No additional elements are created or necessary
• Once set, position is taken care by the browser
• You can normally get and set the <img>'s src attribute: img.src = 'other-image.jpg'
• srcset support

Comparison table with alternative solutions

Support

	object-fit-images	tonipinel/object-fit-polyfill	jonathantneal/fitie
Browsers	IEdge 9-14, Android < 5, Safari < 10	"All browsers"	IE 8-11
Tags	img	img	img, video
cover/contain	💚	💚	💚
fill	💚	💚	💚
none	💚	💚	💔
scale-down	💚 {watchMQ:true} suggested	💔	💔
object-position	💚	💔	💔
srcset support	💚 Native or picturefill, but see notes	💔	💔
picture support	💛 Exclusively where picturefill acts*	💔	💔

Performance and ease of use considerations in extended-comparison.md

Usage

You will need 3 things

1. one or more <img> elements with src or srcset

   <img class='your-favorite-image' src='image.jpg'>
   

2. CSS defining object-fit and a special font-family property to allow IE to read the correct value

   .your-favorite-image {
   	object-fit: contain;
   	font-family: 'object-fit: contain;'
   }
   

   or, if you also need object-position

   .your-favorite-image {
   	object-fit: cover;
   	object-position: bottom;
   	font-family: 'object-fit: cover; object-position: bottom;'
   }
   

   To generate the font-family automatically, you can use the PostCSS plugin or the SCSS/SASS/Less mixins.

3. the activation call before </body>, on on DOM ready

   objectFitImages();
   // if you use jQuery, the code is: $(function () { objectFitImages() });
   

   This will fix all the images on the page and also all the images added later (auto mode).

   Alternatively, only fix the images you want, once:

   // pass a selector
   objectFitImages('img.some-image');
   

   // an array/NodeList
   var someImages = document.querySelectorAll('img.some-image');
   objectFitImages(someImages);
   

   // a single element
   var oneImage = document.querySelector('img.some-image');
   objectFitImages(oneImage);
   

   // or with jQuery
   var $someImages = $('img.some-image');
   objectFitImages($someImages);
   

Apply on resize

You don't need to re-apply it on resize, unless:

• You're using scale-down, or

• your media queries change the value of object-fit, like this

                              img { object-fit: cover }
  @media (max-width: 500px) { img { object-fit: contain } }
  

In one of those cases, use the watchMQ option:

objectFitImages('img.some-image', {watchMQ: true});
// or objectFitImages(null, {watchMQ: true}); // for the auto mode

Install

npm install --save object-fit-images

var objectFitImages = require('object-fit-images');

If you don't use browserify/webpack, include this instead:

<script src="dist/ofi.browser.js"></script>

API

objectFitImages([images, [options]])

parameter

description

images

Type: string, element, array, NodeList, null Default: null The images to fix. More info in the <a href="#usage">Usage</a> section </td> </tr> <tr> <th><code>options</code></th> <td> Type: <code>object</code><br> Default: <code>{}</code><br> Example: <code>{watchMQ:true}</code><br><br> <table> <tr> <th><code>watchMQ</code></th> <td> Type: <code>boolean</code><br> Default: <code>false</code> This enables the automatic re-fix of the selected images when the window resizes. You only need it <a href="#apply-on-resize">in some cases</a> </td> </tr> </table> </td> </tr>

Notes and known issues

• You can run objectFitImages() on the same elements more than once without issues (for example if you decide to change anything on resize)
• Take a look at possible issues and limitations of object-fit-images.

License

MIT © Federico Brigante