This documentation is for imgix.js version 3.0.0 and up. Those using imgix.js 2.x.x can find documentation in that version's readme and API reference.
Note: If you're looking for a Javascript library just to generate imgix URLs, check out imgix-core-js.
imgix.js allows developers to easily generate responsive images using the srcset and sizes attributes, or the picture element. This lets you write a single image URL that is parsed and used to make images look great at any screen size, by using imgix to process and resize your images on the fly.
Responsive images in the browser, simplified. Pure JavaScript with zero dependencies. About 2 KB minified and gzipped.
Before you get started with imgix.js, it's highly recommended that you read Eric Portis' seminal article on srcset and sizes. This article explains the history of responsive images in responsive design, why they're necessary, and how all these technologies work together to save bandwidth and provide a better experience for users. The primary goal of imgix.js is to make these tools easier for developers to implement, so having an understanding of how they work will significantly improve your imgix.js experience.
Below are some other articles that help explain responsive imagery, and how it can work alongside imgix:
- Using imgix with
<picture>. Discusses the differences between art direction and resolution switching, and provides examples of how to accomplish art direction with imgix. - Responsive Images with
srcsetand imgix. A look into how imgix can work withsrcsetandsizesto serve the right image.
There are several ways to install imgix.js. The appropriate method depends on your project.
- npm:
npm install --save imgix.js - Bower:
bower install --save imgix.js - Manual: Download the latest release of imgix.js, and use
dist/imgix.jsordist/imgix.min.js.
After you've included imgix.js on your page, it will automatically run once, after the DOMContentLoaded event fires. This will detect and process all img and source tags on the page that are set up to use imgix.js as described in the Usage section of this README.
imgix.js has a few global options:
host: Your imgix hostname (defaults tonull). This enables the use ofix-pathandix-paramsto define images, instead of having to manually type URLs out inimgix-src. This has several advantages:ix-paramsautomatically URL/Base64-encodes your specified parameters, as appropriate.ix-paramsis a JSON string, which is easier to read than a URL and can be generated by other tools if necessary.- Not having to re-type
https://my-source.imgix.nethelps keep your code DRY.
useHttps: A boolean (defaults totrue), specifying whether to generatehttporhttps-prefixed URLs.
These options can be defined in two ways. The first is to set them manually on the global imgix.config object:
<script src="imgix.js"></script>
<script>
// Specify your imgix host. For these docs, we'll use `assets.imgix.net`.
imgix.config.host = 'assets.imgix.net';
// Optionally disable HTTPS image URL generation (defaults to `true`).
imgix.config.useHttps = false;
</script>The other option for setting global configuration options is to specify them with meta tags in your document's head. If present, these values will be detected just before the initial DOMContentLoaded call to imgix.init():
<head>
<meta property="ix:host" content="assets.imgix.net">
<meta property="ix:useHttps" content="true">
</head>Now that everything's installed and set up, you can start adding responsive images to the page. There are a few ways to do this.
The simplest way to use imgix.js is to create an img tag with the ix-src attribute:
<img
ix-src="https://assets.imgix.net/unsplash/hotairballoon.jpg?w=300&h=500&fit=crop&crop=right"
alt="A hot air balloon on a sunny day"
>This will generate HTML something like the following:
<img
ix-src="https://assets.imgix.net/unsplash/hotairballoon.jpg?w=300&h=500&fit=crop&crop=right"
alt="A hot air balloon on a sunny day"
sizes="100vw"
srcset="
https://assets.imgix.net/unsplash/hotairballoon.jpg?w=100&h=167&fit=crop&crop=right 100w,
https://assets.imgix.net/unsplash/hotairballoon.jpg?w=200&h=333&fit=crop&crop=right 200w,
…
https://assets.imgix.net/unsplash/hotairballoon.jpg?w=2560&h=4267&fit=crop&crop=right 2560w
"
src="https://assets.imgix.net/unsplash/hotairballoon.jpg?w=300&h=500&fit=crop&crop=right"
ix-initialized="ix-initialized"
>Since imgix can generate as many derivative resolutions as needed, imgix.js calculates them programmatically, using the dimensions you specify (note that the w and h params scale appropriately to maintain the correct aspect ratio). All of this information has been placed into the srcset and sizes attributes. Because of this, imgix.js no longer needs to watch or change the img tag, as all responsiveness will be handled automatically by the browser as the page is resized.
Here's how the previous example would be written out using ix-path and ix-params instead of ix-src. Regardless of which method you choose, the end result in-browser will be the same.
Please note: ix-params must be a valid JSON string. This means that keys and string values must be surrounded by double quotes, e.g., "fit": "crop".
<img
ix-path="unsplash/hotairballoon.jpg"
ix-params='{
"w": 300,
"h": 500,
"fit": "crop",
"crop": "right"
}'
alt="A hot air balloon on a sunny day"
>If you need art-directed images, imgix.js plays nicely with the picture tag. This allows you to specify more advanced responsive images, by changing things such as the crop and aspect ratio for different screens. To get started, just construct a picture tag with a source attribute for each art-directed image, and a fallback img tag. If you're new to using the picture tag, you might want to check out our tutorial to learn how it works.
The source tags can be used with ix-src or ix-path and ix-params, just like img tags. The following example will generate HTML that displays Bert and Ernie on small screens, just Bert on medium-sized screens, and just Ernie on large screens.
<picture>
<source
media="(min-width: 880px)"
sizes="430px"
ix-path="imgixjs-demo-page/bertandernie.jpg"
ix-params='{
"w": 300,
"h": 300,
"fit": "crop",
"crop": "left"
}'
>
<source
media="(min-width: 640px)"
sizes="calc(100vw - 20px - 50%)"
ix-path="imgixjs-demo-page/bertandernie.jpg"
ix-params='{
"w": 300,
"h": 300,
"fit": "crop",
"crop": "right"
}'
>
<source
sizes="calc(100vw - 20px)"
ix-path="imgixjs-demo-page/bertandernie.jpg"
ix-params='{
"w": 300,
"h": 100,
"fit": "crop"
}'
>
<img ix-path="imgixjs-demo-page/bertandernie.jpg">
</picture>If you need to process img or source tags added after the initial page load (for example, on an infinite scrolling website or single-page application), you can simply call imgix.init(). By default, this is idempotent: img and source tags that have already been processed by imgix.js will not be re-initialized. If you would like to re-initialize all imgix.js-formatted img and source tags, simply pass the force: true option: imgix.init({force: true}).
If you'd like to lazy load images, we recommend using lazysizes. In order to use imgix.js with lazysizes, you can simply tell it to generate lazysizes-compatible attributes instead of the standard src, srcset, and sizes:
imgix.init({
srcAttribute: 'data-src',
srcsetAttribute: 'data-srcset',
sizesAttribute: 'data-sizes'
})If you need to display images from multiple imgix Sources, the host option can be overridden on any img or source tag by specifying an ix-host attribute in the tag:
<img
ix-host="a-different-source.imgix.net"
ix-path="unsplash/hotairballoon.jpg"
ix-params='{
"w": 300,
"h": 500,
"fit": "crop",
"crop": "right"
}'
alt="A hot air balloon on a sunny day"
>For security and diagnostic purposes, we default to signing all requests with the language and version of library used to generate the URL. This can be disabled by setting imgix.includeLibraryParam = false;, or via a meta tag:
<head>
<meta property="ix:includeLibraryParam" content="false">
</head>- By default, browsers that don't support
srcset,sizes, orpicturewill gracefully fall back to the defaultimgsrcwhen appropriate. If you want to provide a fully-responsive experience for these browsers, imgix.js works great alongside Picturefill! - If you are using Base64 variant params and need IE <= 9 support, we recommend using a polyfill for
atob/btoa, such as Base64.js.
imgix.js was made by imgix. It's licensed under the BSD 2-Clause license (see the license file for more info). Any contribution is absolutely welcome, but please review the contribution guidelines before getting started.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent