- Overview / Resources
- Advanced Usage
- Browser Support
Overview / Resources
imgix.js allows developers to easily generate responsive images using the
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.
Note: imgix.js is designed to run in the browser, manipulating existing
Before getting started with imgix.js, it is highly recommended that you read Eric Portis' seminal article on
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
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 with
sizesto serve the right image.
There are several ways to install
imgix.js. The appropriate method depends on your project.
npm install --save imgix.js
bower install --save imgix.js
- Manual: Download the latest release of imgix.js, and use
If your build process will re-run
dist/imgix.min.js through Browserify, you'll need to add
noParse: [require.resolve('imgix.js')] to your Browserify config. If you skip this, Browserify will attempt to re-require imgix.js' dependencies, which have already been inlined.
imgix.js has been included on the page, it will automatically run once, after the
DOMContentLoaded event fires. This will detect and process all
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 two important global options:
host: A string corresponding to the desired imgix hostname (defaults to
null). This enables the use of
ix-paramsto define images, instead of having to manually provide URLs out in
ix-src. See the
ix-paramssection below for details.
useHttps: A boolean (defaults to
true), specifying whether to generate
These configuration options (as well as other options described in the "Advanced Usage" section) can be defined in two ways. The easiest way is to specify them with
meta tags in your document's
The other way is to manually set these options on the
imgix.config object. Note that these options should be set after loading
imgix.js, but before the
DOMContentLoaded event is fired on the page:
After installation and set up are complete, one can begin adding responsive images to the page through one of few ways:
img tag with the
100vw is an appropriate
sizes value for a full-bleed image. If your image is not full-bleed, you should use a different value for
sizes. Eric Portis' "Srcset and sizes" article goes into depth on how to use the
This will generate HTML something like the following:
Since imgix can generate as many derivative resolutions as needed,
imgix.js calculates them programmatically, using the dimensions you specify (note that the
h params scale appropriately to maintain the correct aspect ratio). All of this information has been placed into the
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.
If configured with a global
imgix.js can use the
ix-params attributes instead of
ix-path attribute is used to specify the path to an image, and the
ix-params attribute is used to define the imgix URL API parameters to be applied to the image. Using these two attributes instead of
ix-src has several advantages:
ix-paramsautomatically URL/Base64-encodes 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 code DRY.
Here's how the previous example would be written out using
ix-params instead of
ix-src. Regardless of the method choosen, the end result in-browser will be the same.
ix-params must be a valid JSON string. This means that keys and string values must be surrounded by double quotes, e.g.,
If an art-directed image is desired,
imgix.js plays nicely with the
picture tag. This allows for specifying more advanced responsive images, by changing properties such as the crop and aspect ratio for different screens. To get started, construct a
picture tag with a
source attribute for each art-directed image, and a fallback
img tag. If new to using the
picture tag, consider reading our tutorial to learn more about how it works.
source tags can be used with
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.
When displaying images between multiple imgix Sources, the
host option can be overridden on any
source tag by specifying an
ix-host attribute in the tag:
imgix.js will automatically run as soon as the
DOMContentLoaded event fires, immediately processing all
source tags on the page that are set up to use
imgix.js. This auto-initialization behavior can be disabled by including the following
meta tag in the document's
Manually initializing imgix.js
If auto-initialization is disabled as described above,
imgix.js will need to be run manually in order to process the
source tags on the page. This can be done by invoking
imgix.init(), a map of options can be passed in to override the global configuration settings. For example:
imgix.init() is run automatically when the
DOMContentLoaded event fires or manually initialized, it will always be idempotent. This means that
source tags that have already been processed by imgix.js will not be re-processed by subsequent calls.
However, if you would like to re-process all imgix.js-ready
source tags, you can override the function's idempotency by calling
imgix.init() again and passing in the
force: true option:
Lazy Loading With lazysizes
If lazy loading images is desired, we recommend using lazysizes. In order to use
imgix.js with lazysizes, generate images using lazysizes-compatible attributes instead of the standard
sizes by changing some configuration settings:
Custom Input Attributes
imgix.js defaults to pulling its data from the
ix-host attributes. If custom input attributes are desired, they can be specified by changing some configuration settings. This can be useful if, say, there is a concern about W3C compliance.
Null Output Attributes
In rare cases, it may be undesirable to have
imgix.js modify the
sizes attributes of the
<img> elements it's targeting. In such cases, the default behavior can be overriden by setting some configuration values to
Base-64 encoded parameters
All of imgix's API parameters can be provided as Base64 variants. This is especially useful when providing text for the
txt parameter, or URLs for parameters such as
When providing parameters via the
ix-params attribute, note that the values for any Base64 variant parameters will be automatically base64-encoded by
imgix.js, and can therefore be provided unencoded.
When providing a URL with parameters via the
ix-src attribute, note that the values for any Base64 variant parameters will not be automatically base64-encoded by
If a default set of parameters are desired, they can be extracted out into a global config using
imgix.defaultParameters. These settings will become the default paramters for each imgix tag globally, before any specific parameters are loaded from
What is the
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 the
includeLibraryParam configuration option to
- By default, browsers that don't support
picturewill gracefully fall back to the default
srcwhen appropriate. If you want to provide a fully-responsive experience for these browsers,
imgix.jsworks great alongside Picturefill!
- If using Base64 variant params and require IE <= 9 support, we recommend using a polyfill for
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.
More Framework Libraries
- django-imgixbuildAn app for integrating imgix into Django sitesPython 1 21 days ago
- imgix-railsbuildA gem for integrating imgix into Rails projectsRuby 89 a month ago
- jekyll-imgixbuildA plugin for integrating imgix into Jekyll sitesRuby 46 16 days ago