object-fit-images

# object-fit-images [![gzipped size][badge-gzip]](#no-link) [![build status][badge-travis]][link-travis] [![npm][badge-version]][link-npm] [![CDNJS][badge-cdnjs]][link-cdnjs] [![jsDelivr][badge-jsdelivr]][link-jsdelivr] [badge-gzip]: https://badges.herokuapp.com/size/github/bfred-it/object-fit-images/master/dist/ofi.min.js?gzip=true&label=gzipped%20size [badge-travis]: https://api.travis-ci.org/bfred-it/object-fit-images.svg [badge-version]: https://img.shields.io/npm/v/object-fit-images.svg [badge-cdnjs]: https://img.shields.io/cdnjs/v/object-fit-images.svg [badge-jsdelivr]: https://data.jsdelivr.com/v1/package/npm/object-fit-images/badge?style=rounded [link-travis]: https://travis-ci.org/bfred-it/object-fit-images [link-npm]: https://www.npmjs.com/package/object-fit-images [link-cdnjs]: https://cdnjs.com/libraries/object-fit-images [link-jsdelivr]: https://www.jsdelivr.com/package/npm/object-fit-images > 🗻 Polyfill object-fit/object-position on `<img>`: IE9, IE10, IE11, Edge, Safari, ... - Fast and lightweight ([demo](http://bfred-it.github.io/object-fit-images/demo/)) - No additional elements are created - Setup is done via CSS - Scaling is taken care by the browser (it uses `background-size`) - `srcset` support - `src` and `srcset` properties and attributes keep working: `img.src = 'other-image.jpg'` ## Alternative solutions Comparison | bfred-it<br>/object-fit-images🌟 | [constancecchen<br>/object-fit-polyfill](https://github.com/constancecchen/object-fit-polyfill) | [tonipinel<br>/object-fit-polyfill](https://github.com/tonipinel/object-fit-polyfill) --- | --- | --- | --- Browsers | <sub>IEdge 9-14, Android<5, Safari<10</sub> | <- Same | "All browsers" Tags | `img` | `image` `video` `picture` | `img` `cover/contain` | 💚 | 💚 | 💚 `fill` | 💚 | 💚 | 💚 `none` | 💚 | 💚 | 💚 `scale-down` | 💚 <sub>using [`{watchMQ:true}`](#apply-on-resize)</sub> | 💚 | 💔 `object-position` | 💚 | 💚 | 💔 `srcset` support | 💚 Native or [picturefill](https://github.com/scottjehl/picturefill) <sub>[notes](detailed-support-tables.md)</sub> | 💚 | 💔 Extra elements | 💚 No | 💔 Yes | 💔 Yes Settings | 💚 via CSS | 💔 via HTML | 💔 via HTML ## Usage You will need 3 things 1. one or more `<img>` elements with `src` or `srcset` ```html <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 ```css .your-favorite-image { object-fit: contain; font-family: 'object-fit: contain;'; } ``` or, if you also need `object-position` ```css .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](https://github.com/ronik-design/postcss-object-fit-images) or the [SCSS/SASS/Less mixins.](/preprocessors) If you set the `font-family` via JavaScript (which must be followed by calling `objectFitImages()`), make sure to include the quotes [**in** the property.](https://github.com/bfred-it/object-fit-images/issues/29#issuecomment-227491892) 3. <a name="activation"></a> the activation call before `</body>`, or _on DOM ready_ ```js 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: ```js // pass a selector objectFitImages('img.some-image'); ``` ```js // an array/NodeList var someImages = document.querySelectorAll('img.some-image'); objectFitImages(someImages); ``` ```js // a single element var oneImage = document.querySelector('img.some-image'); objectFitImages(oneImage); ``` ```js // or with jQuery var $someImages = $('img.some-image'); objectFitImages($someImages); ``` You can call `objectFitImages()` on the same elements more than once without issues, for example to manually request an update of the `object-fit` value. ## Apply on `resize` You don't need to re-apply it on `resize`, unless: * You're using `scale-down`, or * <a id="media-query-affects-object-fit-value">your media queries change the value of `object-fit`,</a> like this ```css img { object-fit: cover; } @media (max-width: 500px) { img { object-fit: contain; } } ``` In one of those cases, use the `watchMQ` option: ```js objectFitImages('img.some-image', {watchMQ: true}); // or objectFitImages(null, {watchMQ: true}); // for the auto mode ``` ## Install Pick your favorite: ```html <script src="dist/ofi.min.js"></script>   ``` ```sh npm install --save object-fit-images ``` ```js var objectFitImages = require('object-fit-images'); ``` ```js import objectFitImages from 'object-fit-images'; ``` ## API ### `objectFitImages(images, options)` Both parameters are optional. <table> <tr> <th>parameter</th> <th>description</th> </tr> <tr> <th><code>images</code></th> <td> Type: <code>string</code>, <code>element</code>, <code>array</code>, <code>NodeList</code>, <code>null</code><br> Default: <code>null</code><br><br> 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><br><br> 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> </table> ## License MIT © [Federico Brigante](http://twitter.com/bfred_it)