Nighttime Possum Meandering

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

    Install

    npm i @polyfiller/object-fit

    DownloadsWeekly Downloads

    6

    Version

    0.0.39

    License

    MIT

    Unpacked Size

    914 kB

    Total Files

    18

    Last publish

    Collaborators

    • wessberg