@polyfiller/object-fit
TypeScript icon, indicating that this package has built-in type declarations

0.0.39 • Public • Published
Logo

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

Downloads per month NPM version Dependencies Contributors code style: prettier License: MIT Support on Patreon

Powered by Polyfiller

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.

Table of Contents

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:

  1. As part of the style attribute for an image:
<img src="..." style="object-fit: contain" />
  1. 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%" />
  1. 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
Frederik Wessberg
Twitter: @FredWessberg
Github: @wessberg
Lead Developer

Backers

Bubbles Christopher Blanchard
Bubbles
Twitter: @use_bubbles
Christopher Blanchard

Patreon

Patrons on 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.

License

MIT © Frederik Wessberg (@FredWessberg) (Website)

Dependents (0)

Package Sidebar

Install

npm i @polyfiller/object-fit

Weekly Downloads

0

Version

0.0.39

License

MIT

Unpacked Size

914 kB

Total Files

18

Last publish

Collaborators

  • wessberg