imgix.js: responsive imgix images from declarative HTML attributes

What imgix.js actually rewrites on the page

imgix.js is a dependency-free JavaScript library for the browser that integrates imgix into a website. The mechanism is DOM manipulation, not server-side rendering. Once the library is on the page, it detects img, picture and source tags that are marked for its use and rewrites them so the browser requests correctly sized variants of an image.

The output the project is aiming at is the standard responsive image markup: srcset and sizes attributes, or a picture element. As the overview puts it, you write a single image URL that is parsed and used to make images look great at any screen size, with imgix processing and resizing the images on the fly.

Who this is for is a front end team that already has an imgix source for its assets and wants responsive images without hand maintaining a list of width candidates. The library description in the package manifest is more explicit about the audience and the requirement: imgix.js makes images on your site or app responsive to device size and pixel density, and it requires an imgix account to use your own images.

One boundary is worth stating early. The project is designed to run in the browser, manipulating existing img elements on an HTML page. It is not a general imgix URL generator.

ix-src for one-off images, ix-path and ix-params for the rest

There are several ways to bring an image into the system, and the choice affects how much you repeat.

The simplest is the ix-src attribute on an img tag, where the full imgix URL with its parameters lives in the markup.

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

The usage section notes that 100vw is an appropriate sizes value for a full-bleed image, and that a different value is needed if the image is not full bleed.

The ix-path and ix-params pair is the alternative, and it only makes sense once the host option is set. The host option is a string corresponding to the desired imgix hostname, and it defaults to null. Setting it lets you define images through ix-path and ix-params instead of writing full URLs into ix-src by hand.

There is also an ix-sizes attribute, and separate support for picture tags. Each of these attributes maps onto a specific part of the generated responsive markup, so the practical decision is how much of the URL you want to write by hand. A site with hundreds of images from the same source will look very different once ix-path and ix-params carry the host for you.

Configuration comes from meta tags or from imgix.config before DOMContentLoaded

There are two global options, and both have to be in place before the library acts on the page. host defaults to null and names the imgix hostname. useHttps is a boolean that defaults to true and decides whether generated URLs are http or https prefixed.

The easier route is meta tags in the head of the document.

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

The other route sets the same options directly on the imgix.config object.

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

The ordering requirement is the part that bites. The documentation states that these options should be set after loading imgix.js, but before the DOMContentLoaded event is fired on the page. Set them too late and the library has already run with the defaults, which means host is still null and the ix-path and ix-params attributes have nothing to resolve against.

That is the whole configuration surface for the common case. The advanced options in the README's advanced usage section, covering overriding ix-host, custom input attributes, null output attributes, base-64 encoded parameters and default parameters, all sit on top of the same object.

Three installation paths, and one Browserify trap

The project offers npm, Bower and a manual copy, and the choice depends on the project.

npm install --save imgix.js

The Bower route is the same shape with a different tool.

bower install --save imgix.js

For the manual route, the instructions point at the latest release of imgix.js and say to use dist/imgix.js or dist/imgix.min.js.

The trap is Browserify. If your build process re-runs dist/imgix.js or dist/imgix.min.js through Browserify, you need to add noParse to your Browserify config.

noParse: [require.resolve('imgix.js')]

Skip that and Browserify will attempt to re-require imgix.js dependencies, which have already been inlined. The failure looks like a bundling error rather than an imgix problem, so it is worth knowing before the first build fails.

Once imgix.js is included on the page, it runs automatically once, after the DOMContentLoaded event fires, detecting and processing the img, picture and source tags that are set up as described in the usage section.

Taking the initialization away from the library

Automatic initialization is convenient, but the advanced usage section documents how to turn it off and how to call init yourself, and it also documents the idempotency of imgix.init(). That is the detail to understand: calling init more than once does not mean the page gets processed twice.

This matters for single page applications and for pages that inject markup after load. A framework that renders image components into an empty container after DOMContentLoaded is exactly the case where the automatic run has already happened and found nothing. Disabling auto-initialization and calling imgix.init() when your content is in place makes the timing explicit rather than accidental.

The lazy loading story follows the same logic. The README documents two routes: native lazy loading, and lazy loading with lazysizes. Native lazy loading is the browser's own loading attribute, which the library then has to read correctly when it rewrites the image. The lazysizes route is for projects that already rely on that third party library and need the two to cooperate.

The repository also carries an ixlib parameter, and the project explains what it is. Read that section before rolling the library out.

imgix-core-js is the right tool when the URL is built outside the browser

The README draws the boundary explicitly and points at a sibling project for the other half of the work. If you are looking for a JavaScript library that can programmatically generate imgix URLs, consider using imgix-core-js instead.

The difference in approach is where the code runs and what it produces. imgix.js runs in the browser, finds markup that already exists and expands it into responsive source sets with many candidate URLs. imgix-core-js is the library for generating imgix URLs programmatically.

The practical consequence is that you should not pick one and expect it to cover the other case. Server side rendering of imgix URLs and client side expansion of markup are separate jobs, and imgix.js does not attempt the first. What imgix.js does add on top of a plain imgix URL is the set of imgix features the manifest lists, including text formatting, color palette extraction, color adjustments, effects and watermarking, which become available through the generated URLs.

One caveat about that: those features only work on assets you serve through your own imgix source, and the manifest is direct about it, since using your own images requires an imgix account.

Cypress specs and a release line that stopped at v4.0.1

The build and test setup is visible in package.json. The build script bundles src/imgix.js with Browserify into dist/imgix.js and then minifies that file with uglify-js into dist/imgix.min.js.

mkdir -p dist && ./node_modules/browserify/bin/cmd.js ./src/imgix.js > ./dist/imgix.js && ./node_modules/uglify-js/bin/uglifyjs ./dist/imgix.js --mangle > ./dist/imgix.min.js

Testing runs a build, then the Jasmine unit specs and the Cypress end to end suite.

npm run build && ./node_modules/jasmine/bin/jasmine.js & npm run cy:runOnly

There is also a Cypress entry point on its own, and the repository has cypress/, spec/ and cypress.config.js at the top level. The prepare and prepublishOnly scripts both run the build, so the dist files in the repository are produced by the same pipeline a consumer installs.

On maintenance, the repository is not archived and the last push was on 2026-09-04. The release history is older than that date: v4.0.1 on 2023-01-10, v4.0.0 on 2022-10-03 and v3.6.1 on 2022-09-01. Recent work has therefore not produced new tagged versions, which means an upgrade path from v4.0.1 comes from the main branch rather than from a new release tag.

The licence is BSD-2-Clause, stated in the package manifest and stored in LICENSE.md at the repository root.

Editorial conclusion

imgix.js fits front end teams that already serve assets through an imgix source and want responsive markup without hand writing srcset candidates. It does not fit server side pipelines, since the project points those at imgix-core-js instead. Verify first that your imgix source hostname matches the ix:host meta tag you plan to use, then check the ixlib parameter the library attaches, because that value is what the imgix account needs to read for usage reporting.

Frequently asked questions

Official sources

1. imgix/imgix.js on GitHub
2. License: BSD-2-Clause
3. Project website
4. README
5. Releases