@polyfiller/object-fit

A robust polyfill for the 'object-fit' and 'object-position' CSS-properties

Description

This is a robust, feature complete polyfill for the object-fit and object-position CSS properties. It differs from other similar solutions primarily in three areas: feature completeness, modern API support, and the ability to react to changes.

Demo

To check out the polyfill in action, A demo can be found here.

Features

Supports not only images, but also videos, the picture element, as well as the srcset attribute.
Supports Shadow DOM.
Reacts to changes, and updates calculated positions automatically.
Leverages the browser's own scaling algorithms where possible.
Works seamlessly and automatically.
Works with the postcss-object-fit-images plugin.

Description
Demo
- Features
Table of Contents
Install
- npm
- Yarn
- pnpm
Applying the polyfill
Usage
Dependencies & Browser support
Maintainers
Backers
- Patreon
FAQ
- What is the performance and reaction times of this polyfill?
License

Install

npm

$ npm install @polyfiller/object-fit

Yarn

$ yarn add @polyfiller/object-fit

pnpm

$ pnpm add @polyfiller/object-fit

Applying the polyfill

The polyfill will check if the browser already supports object-fit and object-position and will only be applied if the runtime doesn't already support it.

To include it, add this somewhere:

import "@polyfiller/object-fit/polyfill";

However, it is generally a good idea that you only include the polyfill for runtimes that don't already support object-fit and object-position. One way to do so is with an async import:

if (!("objectFit" in document.documentElement.style)) {
	await import("@polyfiller/object-fit/polyfill");
}

Alternatively, you can use Polyfill.app which uses this polyfill and takes care of only loading the polyfill if needed as well as adding the language features that the polyfill depends on (See dependencies).

Usage

You can provide object-fit and/or object-position values in one of more ways:

As part of the style attribute for an image:

<img src="..." style="object-fit: contain" />

As part of a special object-fit, object-position, data-object-fit, or data-object-position attribute:

<img src="..." object-fit="contain" />
<!-- or -->
<img src="..." data-object-fit="contain" />

<img src="..." object-position="50% 50%" />
<!-- or -->
<img src="..." data-object-position="50% 50%" />

Directly from CSS, using the object-fit and/or object-position properties, and a special font-family property that is used by browsers that doesn't natively support these features:

img,
video {
	object-fit: cover;
	object-position: bottom;
	font-family: "object-fit: cover; object-position: bottom";
}

To generate the font-family automatically based on your CSS, you can use this PostCSS plugin.

Dependencies & Browser support

This polyfill is distributed in ES5-compatible syntax, but is using some additional APIs and language features beyond ES5 which must be available in the runtime:

MutationObserver
requestAnimationFrame
Set
WeakMap
Symbol.iterator
Symbol.toStringTag

Generally, I would highly recommend using something like Polyfill.app which takes care of this stuff automatically.

Maintainers


Frederik Wessberg Twitter: @FredWessberg Github: @wessberg Lead Developer

Backers


Bubbles Twitter: @use_bubbles	Christopher Blanchard

Patreon

FAQ

What is the performance and reaction times of this polyfill?

This polyfill observes various attributes on <img> and <video> elements such as src, srcset, style, and class, as well as the special object-fit, data-object-fit, object-position, and data-object-position attributes by leveraging MutationObserver. As such, this is quite performant. Changing any of these attributes will immediately trigger repositioning of the fitted element(s). However, this polyfill also lazily recalculates the computed styles for fitted elements to see if their styles changed through cascaded styles. Getting the computed styles for an element is somewhat expensive, and so this is done once every two seconds per fitted element. This means that an image/video may take up to two seconds to react to changes to styling. If you want it to react immediately, one way to force immediate repositioning is to provide a new value to the style attribute.