Need private packages and team management tools?Check out npm Teams »


2.3.1 • Public • Published

imgix logo

imgix-core-js is a JavaScript library for generating image URLs with imgix that can be used in browser or server-side settings.

NPM Version Build Status Monthly Downloads Minified Size License


imgix-core-js can be installed as either via npm or via bower:

npm install --save imgix-core-js


bower install --save imgix-core-js


Depending on your module system, using imgix-core-js is done a few different ways. The most common entry point will be the ImgixClient class. Whenever you provide data to imgix-core-js, make sure it is not already URL-encoded, as the library handles proper encoding internally.


var ImgixClient = require('imgix-core-js');
var client = new ImgixClient({
  domain: "",
  secureURLToken: "<SECURE TOKEN>"
var url = client.buildURL("/path/to/image.png", {
  w: 400,
  h: 300
console.log(url); // => "…"

ES6 Modules

import ImgixClient from 'imgix-core-js'
let client = new ImgixClient({
  domain: '',
  secureURLToken: '<SECURE TOKEN>'
let url = client.buildURL('/path/to/image.png', { w: 400, h: 300 });
console.log(url); // => '…'


var client = new ImgixClient({
  domain: ''
  // Do not use signed URLs with `secureURLToken` on the client side,
  // as this would leak your token to the world. Signed URLs should
  // be generated on the server.
var url = client.buildURL('/path/to/image.png', { w: 400, h: 300 });
console.log(url); // => ""

Srcset Generation

The imgix-core-js module allows for generation of custom srcset attributes, which can be invoked through buildSrcSet(). By default, the srcset generated will allow for responsive size switching by building a list of image-width mappings.

var client = new ImgixClient({domain:'', secureURLToken:'my-token', includeLibraryParam:false});
var srcset = client.buildSrcSet('image.jpg');

Will produce the following attribute value, which can then be served to the client: 100w, 116w, 134w,
                                            ... 7400w, 8192w

Fixed image rendering

In cases where enough information is provided about an image's dimensions, buildSrcSet() will instead build a srcset that will allow for an image to be served at different resolutions. The parameters taken into consideration when determining if an image is fixed-width are w, h, and ar. By invoking buildSrcSet() with either a width or the height and aspect ratio (along with fit=crop, typically) provided, a different srcset will be generated for a fixed-size image instead.

var client = new ImgixClient({domain:'', secureURLToken:'my-token', includeLibraryParam:false});
var srcset = client.buildSrcSet('image.jpg', {h:800, ar:'3:2',fit:'crop'});

Will produce the following attribute value: 1x, 2x, 3x, 4x, 5x

For more information to better understand srcset, we highly recommend Eric Portis' "Srcset and sizes" article which goes into depth about the subject.

Custom Widths

In situations where specific widths are desired when generating srcset pairs, a user can specify them by passing an array of positive integers as widths to the third options object:

var client = new ImgixClient({
  includeLibraryParam: false
var srcset = client.buildSrcSet('image.jpg', {}, {widths: [100, 500, 1000, 1800]})

Will generate the following srcset of width pairs: 100w, 500w, 1000w, 1800w

Please note that in situations where a srcset is being rendered as a fixed image, any custom widths passed in will be ignored. Additionally, if both widths and a widthTolerance are passed to the buildSrcSet method, the custom widths list will take precedence.

Width Tolerance

The srcset width tolerance dictates the maximum tolerated size difference between an image's downloaded size and its rendered size. For example: setting this value to 0.1 means that an image will not render more than 10% larger or smaller than its native size. In practice, the image URLs generated for a width-based srcset attribute will grow by twice this rate. A lower tolerance means images will render closer to their native size (thereby increasing perceived image quality), but a large srcset list will be generated and consequently users may experience lower rates of cache-hit for pre-rendered images on your site.

By default this rate is set to 8 percent, which we consider to be the ideal rate for maximizing cache hits without sacrificing visual quality. Users can specify their own width tolerance by providing a positive scalar value as widthTolerance to the third options object:

var client = new ImgixClient({
  includeLibraryParam: false
var srcset = client.buildSrcSet('image.jpg', {}, {widthTolerance: 0.20})

In this case, the width_tolerance is set to 20 percent, which will be reflected in the difference between subsequent widths in a srcset pair: 100w, 140w, 196w,
                            ... 8192w

Minimum and Maximum Width Ranges

In certain circumstances, you may want to limit the minimum or maximum value of the non-fixed srcset generated by the buildSrcSet() method. To do this, you can pass in an options object as a third argument, providing positive integers as minWidth and/or maxWidth attributes:

var client = new ImgixClient({
  includeLibraryParam: false
var srcset = client.buildSrcSet('image.jpg', {}, {minWidth:500, maxWidth: 2000})

Will result in a smaller, more tailored srcset. 500w, 580w, 672w, 780w, 906w, 1050w, 1218w, 1414w, 1640w, 1902w, 2000w

Remember that browsers will apply a device pixel ratio as a multiplier when selecting which image to download from a srcset. For example, even if you know your image will render no larger than 1000px, specifying options: { max_srcset: 1000 } will give your users with DPR higher than 1 no choice but to download and render a low-resolution version of the image. Therefore, it is vital to factor in any potential differences when choosing a minimum or maximum range.

Also please note that according to the imgix API, the maximum renderable image width is 8192 pixels.

Variable Qualities

This library will automatically append a variable q parameter mapped to each dpr parameter when generating a fixed-image srcset. This technique is commonly used to compensate for the increased filesize of high-DPR images. Since high-DPR images are displayed at a higher pixel density on devices, image quality can be lowered to reduce overall filesize without sacrificing perceived visual quality. For more information and examples of this technique in action, see this blog post.

This behavior will respect any overriding q value passed in as a parameter. Additionally, it can be disabled altogether by passing { disableVariableQuality: true } to the third argument of buildSrcSet().

This behavior specifically occurs when a fixed-size image is rendered, for example:

var srcset = new ImgixClient({
          domain: '',
          includeLibraryParam: false
        }).buildSrcSet('image.jpg', {w:100});

will generate a srcset with the following q to dpr mapping: 1x, 2x, 3x, 4x, 5x

What is the ixlib param on every request?

For security and diagnostic purposes, we sign all requests with the language and version of library used to generate the URL.

This can be disabled by passing a falsy value for the includeLibraryParam option to new ImgixClient:

new ImgixClient({
  domain: '',
  includeLibraryParam: false


imgix-core-js uses mocha for testing. Here’s how to run those tests:

npm test




npm i imgix-core-js

DownloadsWeekly Downloads






Unpacked Size

396 kB

Total Files


Last publish


  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar