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 main use-case in mind: images. Take a look at the demo.

Main features

• The code is light on the CPU
• No other elements are created to make it work
• 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'

Comparison table with alternative solutions

Support

	object-fit-images	tonipinel/object-fit-polyfill	jonathantneal/fitie
Browsers	"All browsers"	"All browsers"	IE 8-11, Edge
Tags	img	img	img, video
cover/contain	💚	💚	💚
fill	💚	💚	💚
none	💚	💚	💔
scale-down	💛 Mapped to contain	💔	💔
object-position	💚	💔	💔

Performance

	object-fit-images	tonipinel/object-fit-polyfill	jonathantneal/fitie
Size	1.3KB	1.8KB	1.5KB
Update wait	💚 No wait, applied before image load	💚 No wait, applied before image load	💔 Wait until full image load
Additional DOM elements necessary	💚 No	💔 Yes, a wrapping element is added	💔 Yes, a wrapping element is added
Performance overhead	💰💰	💰💰💰	💰💰
Technique description	Transparent src image; Image in <img>'s background	Wrapper element with style copied from <img>; CSS+JS positioning; Original <img> hidden	Wrapper element with style copied from <img>; JS positioning

Ease of use

	object-fit-images	tonipinel/object-fit-polyfill	jonathantneal/fitie
Object-fit definition	💛 In CSS, via font-family property *	💔 Via data attribute in HTML (data-object-fit="cover")	💔 Via class in HTML (class="cover")
Change change on @media query	💚 Yes	💔 No	💔 No
Updates on resize	💚 Unnecessary if media queries don't change object-fit	💛 Unnecessary if media queries don't change object-fit, impossible otherwise.	💔 Yes, manually
Updates on object-fit change	💚 Automatic	💔 Impossible	💔 Impossible
Fix new elements automatically	💚 Optional	💔 Impossible	💛 Manually
<img> src changes	💚 Automatically reflected	💔 Image not updated at all	💔 Fix not updated
Other limitations	💔 Any onload events on <img> will fire again when it fixes	💚 I didn't find any	💔 Some CSS declaration might be broken because partially moved to the wrapper

Runner-up: anselmh/object-fit is deprecated, doesn't support Edge and clocks in at 14KB.

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 be developed to automatically add this font-family property.

JS

Fix all the images on the page, present and future.

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

You can safely disable the resize listener this way:

objectFitImages('img.some-image', {onresize: false});

... if your code DOESN'T contain something like this:

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

Load and enable with plain HTML

<script src="ofi.min.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, OFI will enter the automatic mode (which means that new images in the DOM will automatically be fixed).
opts	Type: object optional Set to {onresize: false} if you don't expect object-fit to vary in a media query.

License

MIT © Federico Brigante