191 lines
8.3 KiB
Markdown
191 lines
8.3 KiB
Markdown
# 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>
|
|
<!-- CDN is also available, but I suggest you concatenate JS files instead -->
|
|
<!-- Visit https://cdnjs.com/libraries/object-fit-images -->
|
|
```
|
|
|
|
```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)
|