SkillAgentSearch skills...

Imgix.js

Responsive images in the browser, simplified

GenerateConvertImprove

Install / Use

/learn @imgix/Imgix.js
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

<!-- ix-docs-ignore --> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://assets.imgix.net/sdk-imgix-logo-new-dark.svg"> <img src="https://assets.imgix.net/sdk-imgix-logo-new.svg"> </picture>

imgix.js is a dependency-free JavaScript library for the browser that allows for easy integration of imgix into websites.

NPM Version Build Status Monthly Downloads Minified Size License styled with prettier FOSSA Status

<!-- /ix-docs-ignore -->

Overview / Resources

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.

Note: imgix.js is designed to run in the browser, manipulating existing <img> elements on an HTML page. If you're looking for a JavaScript library that can programmatically generate imgix URLs, consider using imgix-core-js instead.

Before getting started with imgix.js, it is 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:

Installation

There are several ways to install imgix.js. The appropriate method depends on your project.

  1. npm: npm install --save imgix.js
  2. Bower: bower install --save imgix.js
  3. Manual: Download the latest release of imgix.js, and use dist/imgix.js or dist/imgix.min.js.

If your build process will re-run dist/imgix.js or 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.

Once imgix.js has been included on the page, it will automatically run once, after the DOMContentLoaded event fires. This will detect and process all img, picture, and source tags on the page that are set up to use imgix.js as described in the Usage section of this README.

Configuration

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-path and ix-params to define images, instead of having to manually provide URLs out in ix-src. See the ix-path and ix-params section below for details.
  • useHttps: A boolean (defaults to true), specifying whether to generate http or https-prefixed URLs.

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 <head>:

<head>
  <meta property="ix:host" content="assets.imgix.net">
  <meta property="ix:useHttps" content="true">
</head>

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:

<script src="imgix.js"></script>
<script>
  imgix.config.host = 'assets.imgix.net';
  imgix.config.useHttps = false;
</script>

Usage

After installation and set up are complete, one can begin adding responsive images to the page through one of few ways:

ix-src

Creates 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"
  sizes="100vw"
>

Please note: 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 sizes attribute.

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.

ix-path and ix-params

If configured with a global host option, imgix.js can use the ix-path and ix-params attributes instead of ix-src. The 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:

  1. ix-params automatically URL/Base64-encodes specified parameters, as appropriate.
  2. ix-params is a JSON string, which is easier to read than a URL and can be generated by other tools if necessary.
  3. Not having to re-type https://my-source.imgix.net helps keep code DRY.

Here's how the previous example would be written out using ix-path and ix-params instead of ix-src. Regardless of the method chosen, the end result in-browser will be the same.

<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"
>

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".

ix-sizes attribute

When set to auto, automatically updates an img tag's sizes attribute to match the image's display size.

<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"
  ix-sizes="auto"
>

Please note: the image width has to be calculable before the image has loaded, otherwise sizes will not match the width of the displayed image. In most cases, using the CSS rule img[ix-sizes="auto"] { display: block; width: 100%; } will ensure the image's width is calculable before it has loaded.

Generates HTML similar to the following

``

imgix

View profile

View on GitHub
GitHub Stars965
CategoryDevelopment
Updated3d ago
Forks63
imgix/imgix.js

Languages

JavaScript

Security Score

100/100

Audited on Apr 3, 2026

No findings