Libraries
@imgix/js-core build
- Installing
- Usage
- Configuration
- API
- What is the
Ixlib
Param on Every Request? - Support for Management API
- Testing
- License
Installing
@imgix/js-core can be installed via npm:
Usage
Depending on your module system, using @imgix/js-core is done a few different ways. The most common entry point will be the ImgixClient
class. Whenever you provide data to ImgixClient
, make sure it is not already URL-encoded, as the library handles proper encoding internally.
CommonJS
ES6 Modules
In-browser
Configuration
The following options can be used when creating an instance of ImgixClient
:
domain
: String, required. The imgix domain that will be used when constructing URLs. Defaults tonull
.useHTTPS
: Boolean. Specifies whether constructed URLs should use the HTTPS protocol. Defaults totrue
.includeLibraryParam
: Boolean. Specifies whether the constructed URLs will include anixlib
parameter. Defaults totrue
.secureURLToken
: String. When specified, this token will be used to sign images. Read more about securing images on the imgix Docs site. Defaults tonull
.- :warning: The
secureURLToken
option should only be used in server-side applications to prevent exposing your secure token. :warning:
- :warning: The
API
ImgixClient.buildURL(path, params, options)
path
: String, required. A full, unencoded path to the image. This includes any additional directory information required to locate the image within a source.params
: Object. Any number of imgix rendering API parameters.options
: Object. Any number of modifiers, described below:disablePathEncoding
: Boolean. Disables encoding logic applied to the image path.encoder
: Function. Applies custom logic to encode the image path and query parameters.
Construct a single image URL by passing in the image path
and any rendering API parameters.
Returns: an image URL as a string.
ImgixClient.buildSrcSet(path, params, options)
path
: String, required. A full, unencoded path to the image. This includes any additional directory information required to locate the image within a source.params
: Object. Any number of imgix rendering API parameters.options
: Object. Any number of srcset modifiers, described below:
The @imgix/js-core 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.
Returns: A srcset
attribute value as a string.
Fixed Image Rendering
Specifying either a w
or a h
parameter to buildSrcSet()
will create a DPR-based srcset. This DPR-based srcset allows for the fixed-sized image to be served at different resolutions (i.e. at different pixel densities).
Will produce the following attribute value:
By default, this library generates a srcset
with pixel density values of 1
through 5
. These target ratios can be controlled by using the devicePixelRatios
parameters.
Will result in a smaller srcset.
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:
Will generate the following srcset
of width pairs:
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:
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:
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:
Will result in a smaller, more tailored srcset.
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.
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:
Will generate a srcset with the following q
to dpr
mapping:
Quality parameters is overridable for each dpr
by passing variableQualities
parameters.
Will generate the following custom q
to dpr
mapping:
Disable Path Encoding
This library will encode by default all paths passed to both buildURL
and buildSrcSet
methods. To disable path encoding, pass { disablePathEncoding: true }
to the third argument options
of buildURL()
or buildSrcSet()
.
Normally this would output a src of https://testing.imgix.net/file%2Bwith%2520some%2Bcrazy%3Fthings.jpg
, but since path encoding is disabled, it will output a src of https://testing.imgix.net/file+with%20some+crazy?things.jpg
.
Custom URL encoding
This library will encode by default using encodeURI()
, encodeURIComponent()
, or a combination of the two depending on the image path and parameters. You can define a custom encoding function in buildURL's
options` object if you wish to override this behavior. Note that encoding your own URL can result in a URL that is not recognized by the imgix rendering API.
The custom encoder also accepts a second optional parameter key
which allows users to modify how query parameters are encoded. This parameter does not affect the custom encoding logic of the image path.
Web Proxy Sources
If you are using a Web Proxy Source, all you need to do is pass the full image URL you would like to proxy to @imgix/js-core
as the path, and include a secureURLToken
when creating the client. @imgix/js-core
will then encode this full URL into a format that imgix will understand, thus creating a proxy URL for you.
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
:
Support for Management API
Users looking for client library support for the imgix management API should use the imgix-management-js library. These two projects may be merged at a future date.
Testing
@imgix/js-core uses mocha for testing. Here’s how to run those tests:
License
More Core Libraries
- imgix-csharpbuildA C# client library for generating image URLs with imgixC# 14 a year ago
- imgix-gobuildA Go client library for generating image URLs with imgixGo 12 a year ago
- imgix-javabuildA Java client library for generating URLs with imgixJava 19 a year ago
- imgix-phpbuildA PHP client library for generating URLs with imgixPHP 111 a year ago
- imgix-pythonbuildA Python client library for generating URLs with imgixPython 36 a year ago
- imgix-rbbuildA Ruby gem for generating image URLs with imgixRuby 76 a year ago
- imgix-swiftbuildA Swift client library for generating URLs with imgixSwift 25 9 months ago