object-fit-images

object-fit-images

Adds support to object-fit to images on IE9, IE10, IE11, Edge and other old browsers.

This script was made with the most common use-case in mind: images. 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 4.4.4-, possibly others	"All browsers"	IE 8-11, Edge
Tags	img	img	img, video
cover/contain	💚	💚	💚
fill	💚	💚	💚
none	💚	💚	💔
scale-down	💛 Mapped to contain	💔	💔
object-position	💚	💔	💔
srcset support	💚 Native or picturefill, but no Edge 12	💔	💔

Performance and ease of use considerations in detailed-support-tables.md

Usage

Because it's nearly impossible to read unsupported property, object-fit-images reads the value of object-fit and object-position from the font-family property on img.

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

This has no effect on the rendering because it's ignored by the browser.

A PostCSS plugin could also be developed to automatically add this font-family property.

There are some SCSS/SASS/Less mixins in the preprocessor folder to create that font-family automatically, like this:

@import "object-fit-images/preprocessors/mixin.scss";
img { @include object-fit(cover, top); }

JS

Fix all the images on the page, present and future (auto mode)

objectFitImages();

Alternatively, just fix them once. The first parameter can be:

// 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);

Media query affects object-fit value

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

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

... then you need to enable the media queries support like this:

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

Load and enable with plain HTML

<script src="dist/ofi.browser.js"></script>
<script>objectFitImages();</script>

Load with with browserify

npm install --save object-fit-images

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

API

objectFitImages([images, [opts]])

parameter	description
images	Type: string (as a selector) or array-like optional The images to apply the fix on. If it's not supplied (or false), OFI will enter the automatic mode (which means that new images in the DOM will automatically be fixed).
opts	Type: object optional Set to {watchMQ: true} if you expect object-fit to vary in a media query.

License

MIT © Federico Brigante