hectorromo / object-fit-images

πŸ—» Polyfill object-fit and object-position on images on IE9, IE10, IE11, Edge, Safari, ...

Home Page:http://npm.im/object-fit-images

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

object-fit-images

Polyfill object-fit and object-position on images on IE9, IE10, IE11, Edge, Safari, ...

gzipped size Travis build status npm version

This adds support for object-fit and object-position to IEdge 9-13, Android 4.4-, Safari (OSX 9.1-, iOS 9.3-) and skips browsers that already support them.

Take a look at the demo.

Main features

  • CPU-light code
  • No additional elements are created or necessary
  • 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'
  • srcset support

Comparison table with alternative solutions

Support

object-fit-images tonipinel/object-fit-polyfill jonathantneal/fitie
Browsers IEdge 9-14, Android < 5, Safari < 10 "All browsers" IE 8-11
Tags img img img, video
cover/contain πŸ’š πŸ’š πŸ’š
fill πŸ’š πŸ’š πŸ’š
none πŸ’š πŸ’š πŸ’”
scale-down πŸ’š {watchMQ:true} suggested πŸ’” πŸ’”
object-position πŸ’š πŸ’” πŸ’”
srcset support πŸ’š Native or picturefill, but see notes πŸ’” πŸ’”
picture support πŸ’› Exclusively where picturefill acts* πŸ’” πŸ’”

Performance and ease of use considerations in extended-comparison.md

Usage

You will need 3 things

  1. one or more <img> elements with src or srcset

    <img class='your-favorite-image' src='image.jpg'>
  2. CSS defining object-fit and a special font-family property to allow IE to read the correct value

    .your-favorite-image {
    	object-fit: contain;
    	font-family: 'object-fit: contain;'
    }

    or, if you also need object-position

    .your-favorite-image {
    	object-fit: cover;
    	object-position: bottom;
    	font-family: 'object-fit: cover; object-position: bottom;'
    }

    To generate the font-family automatically, you can use the PostCSS plugin or the SCSS/SASS/Less mixins.

  3. the activation call before </body>, on on DOM ready

    objectFitImages();
    // if you use jQuery, the code is: $(function () { objectFitImages() });

    This will fix all the images on the page and also all the images added later (auto mode).

    Alternatively, only fix the images you want, once:

    // pass 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);
    // or with jQuery
    var $someImages = $('img.some-image');
    objectFitImages($someImages);

Apply on resize

You don't need to re-apply it on resize, unless:

In one of those cases, use the watchMQ option:

objectFitImages('img.some-image', {watchMQ: true});
// or objectFitImages(null, {watchMQ: true}); // for the auto mode

Install

npm install --save object-fit-images
var objectFitImages = require('object-fit-images');

If you don't use browserify/webpack, include this instead:

<script src="dist/ofi.browser.js"></script>

API

objectFitImages([images, [options]])

parameter description
images Type: string, element, array, NodeList, null
Default: null

        The images to fix. More info in the <a href="#usage">Usage</a> section 

    </td>
</tr>
<tr>
    <th><code>options</code></th>
    <td>
        
        Type: <code>object</code><br>
        Default: <code>{}</code><br>
        Example: <code>{watchMQ:true}</code><br><br>
        
        <table>
            <tr>
                <th><code>watchMQ</code></th>
                <td>
                    Type: <code>boolean</code><br>
                    Default: <code>false</code>

                    This enables the automatic re-fix of the selected images when the window resizes. You only need it <a href="#apply-on-resize">in some cases</a>
                </td>
            </tr>
        </table>
    </td>
</tr>

Notes and known issues

  • You can run objectFitImages() on the same elements more than once without issues (for example if you decide to change anything on resize)
  • Take a look at possible issues and limitations of object-fit-images.

License

MIT Β© Federico Brigante

About

πŸ—» Polyfill object-fit and object-position on images on IE9, IE10, IE11, Edge, Safari, ...

http://npm.im/object-fit-images

License:MIT License


Languages

Language:JavaScript 47.9%Language:HTML 30.7%Language:CSS 21.4%