Nighttime Possum Meandering

    TypeScript icon, indicating that this package has built-in type declarations

    0.0.39 • Public • Published

    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


    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.


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


    • 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



    $ npm install @polyfiller/object-fit


    $ yarn add @polyfiller/object-fit


    $ 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 {
    	await import("@polyfiller/object-fit/polyfill");

    Alternatively, you can use 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).


    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:
    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 which takes care of this stuff automatically.


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


    Bubbles Christopher Blanchard
    Twitter: @use_bubbles
    Christopher Blanchard


    Patrons on Patreon


    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.


    MIT © Frederik Wessberg (@FredWessberg) (Website)


    npm i @polyfiller/object-fit

    DownloadsWeekly Downloads






    Unpacked Size

    914 kB

    Total Files


    Last publish


    • wessberg