Help Center

  1. StackPath Help
  2. CDN
  3. How-To's
  4. Image Optimization

Image Optimization Reference Guide

Avatar
Joelle Lanke
Updated:

Overview

This document contains all of the functions you can use to optimize your images. These functions are to be placed within your implementation of Resolve.

Options

The fields used by the options object specify the configuration information that Resolve needs to connect to StackPath's image optimization service.

The fields of this object follow the format {field1: value1, field2: value2, ..., fieldn: valuen}.

The table below lists and describes all of the available fields for for the options object.

Field Type Default Use
advancedOptions Object   Provides a way to customize Resolve.
base String   Specifies a prefix to prepend to the string value defined in the data-resolvesrc attribute of the <img> tag if the data-resolvesrc attribute does not start with a valid protocol name, such as "http:" or "file:".
imageFit String 'container'

Defines how the image is scaled to fit within the image container defined in the CSS or <img> tag.

Valid values are:

  • container: Fits the image within the smallest dimension of the container while maintaining the aspect ratio.
  • containerWidth: Scales the image to fit the container width while maintaining the aspect ratio.
  • containerHeight: Scales the image to fit the container height while maintaining the aspect ratio.
  • containerFill: Scales the image to fill the entire size of the container while maintaining the aspect ratio. If the container aspect ratio is different from the image aspect ratio, the image is scaled, centered, and then cropped to fit the container.
  • containerMax: Fits the image within the largest dimension of the container while maintaining the aspect ratio.
  • containerPad: Scales the image to fill the entire size of the container while maintaining the aspect ratio. If the container aspect ratio is different from the image aspect ratio, the image is centered in the container, and the remaining space is padded with the color defined in containerPadFillColor.
  • stretch: Fits the image to the entire size of the container without maintaining the aspect ratio. If the container ratio is different from the image aspect ratio, the image is skewed to fit the container.
lazyLoad Boolean false Enables or disables lazy loading.
preloadImage Boolean true

Indicates whether or not images are preloaded and stored in a buffer before replacing existing images due to a response or an API event.

  • If true, images are preloaded before changing the image source.
  • If false, the image is not preloaded, which may result in image flashing on older browsers.

options.advancedOptions

The advancedOptions fields allow you to customize Resolve.

The fields for this object follow the format {field1: value1, field2: value2, ..., fieldn: valuen}.

The table below lists and describes all of the available fields for the advancedOptions object.

Field Type Default Use
allowImageUpscaling Boolean false

Determines whether or not Resolve will scale images to a size that exceeds the native resolution.

  • If true, Resolve will scale images to a size that exceeds the native resolution
  • If false, Resolve will not scale image to a size that exceeds the native resolution
alwaysUseSSL Boolean false

Forces all connections to use HTTP over SSL (HTTPS).

  • If true, Resolve will convert all requests to HTTPS.
  • If false, Resolve will use the protocol defined in the request.

This field is ignored if neverUseSSL is set to true.
cacheThreshold Integer 100

Specifies the number of pixels used to determine when Resolve updates an image if the browser window is resized and the container width or height changes by this value.

For example, if this value is 100, Resolve updates an image every time its container size changes by at least 100 pixels.

Setting the interval to a large number of pixels increases the likelihood that similar requests will be served from StackPath's CDN cache.
completedClass String 'ResolveComplete' Overrides the default name that identifies the CSS class of image tags that Resolve has processed.
containerPadFillColor Color 'white' Defines the color of the padding when the imageFit options is set to 'containerPad'.
enabledClass String 'Resolve'

Overrides the default name that identifies the CSS class of image tags that Resolve needs to process.

If blank, Resolve will process all image elements.
expires String  

Adds an Expires HTTP header, set to the value specified, to the response. To indicate the current date, enter "now". This field is ignored if using data-resolvechain and an expires argument is already present in the sink command.
ignoreGif Boolean false

Determines how Resolve handles GIF images when used as data-resolvesrc.

When true, if a GIF image is recognized as data-resolvesrc, Resolve skips the image and sets the source to data-resolvesrc.

If using an image chain with data-resolvechain, Resolve processes the GIF image without scaling it.

If false, Resolve does not skip GIF images.
lazyLoadOptions Object  

Defines the settings to use when displaying an image when the viewport is not fully visible.

This object is ignored if options.lazyLoad is set to false.
maxPixelRatio Integer Undefined

Specifies the maximum pixel ratio allowed. The resulting ratio is n:I where n is the value entered here.

When defined, the pixel ratio never exceeds this value, regardless of the advancedOptions.overridePixelRatio or data-resolveoverridePixelRatio settings or the pixelRatio value entered in the output callback.
neverUseSSL Boolean false

Forces all connections to use HTTP.

  • If true, Resolve will convert all requests to HTTP.
  • If false, Resolve will use the protocol defined in the request.

If this is set to true, Resolve will never convert requests to HTTPS, even if alwaysUseSSL is set to true.
overridePixelRatio Integer  

Specifies a pixel ratio that overrides the pixel ratio of the browser. The resulting ratio is n:I where n is the value entered here. This ratio is applied globally.
pageResizeDelay Integer 200

Specifies the time, in ms, to wait before Resolve determines whether or not the window has been resized. This is ignored if runOnPageResizeDown and runOnPageResizeUp are set to false.
responsive Boolean true

Indicates whether or not Resolve will process images after a window resize event occurs.

  • If true, images are processed if the window size changes and the new size requires StackPath's image optimization servers to re-render the image chain to maintain the image quality.
  • If false, Resolve ignores window resize events.
runOnPageLoad Boolean true

Determines whether or not Resolve automatically processes images when the browser page is loaded.

  • If true, Resolve automatically processes images when the page is loaded.
  • If false, Resolve does not process images on a page load.

options.advancedOptions.lazyLoadOptions

The lazyLoadOptions object consists of objects and a callback function that allows you to configure how Resolve processes images before and after they intersect a given viewport.

The settings specified in these options are ignored if the options.lazyLoad field is set to false.

observerOptions

The observerOptions object allows you to configure the Intersection Observer as described here.

The table below contains the three field descriptions and types.

Name Type Default Description
root string null Specifies the target element defined as the viewport. All other properties are then applied to this viewing area. By default, this is the browser window.
rootMargin string '0px 0px 0px 0px' Defines the margins of the viewport. This property accepts a space-separated list, up to four values, representing the top, right, bottom and left margins.
threshold floating point 0 Specifies the percentage of the image that must be intersecting the viewport before it's displayed.

onVisible(entry)

Use

Returns information about the Intersection Observer once Resolve renders the image in the viewport. This callback function returns the field defined in the following table.

Argument Type Description
entry string Contains the information specified here.

JavaScript API Methods

The methods in this section can be used on an instance of the Resolve object in a web page. To call these methods, use the syntax Resolve.method, where "Resolve" is the variable name assigned when creating the Resolve instance and "method" is the method to call.

For example, if the variable name is "resolve" when creating an instance of Resolve, the following will call the blankChain method:

resolve.blankChain(10, 10)

Each of these methods is described in the following sections.

blankChain (targetWidth, targetHeight)

Use

Creates a blank image chain as a string. This is useful for setting a default image source when creating images for Resolve. This method requires the arguments defined in the table below.

Argument Type Description
targetWidth integer Specifies the width (in pixels) of the blank image.
targetHeight integer Specifies the height (in pixels) of the blank image

Returns

Type Description
string The smallest image that matches the aspect ratio.

newImage (attributes)

Use

Creates a new HTML <img> element with the attributes set to the values passed to Resolve. This method requires the arguments defined in the table below.

Argument Type Description
attributes object

Contains key:value pairs specifying the <img> attributes for Resolve to use when creating the image element.

If an image does not contain a width and height, Resolve will not immediately process the image.

Once the image is placed in the Document Object Model, Resolve will process the image when the updateImage (element) or updateImages (imgArray) method is called.

Returns

Type Description
HTML Image Element An HTML image element <img>.

updateImage (element, force)

Use

Instructs Resolve to process the specified HTML element. This method requires the arguments defined in the table below.

Argument Type Description
element HTML Image Element Identifies the HTML element for Resolve to process.
force boolean

Instructs Resolve to treat the image element as new and re-render the image.

  • If set to true, Resolve treats the image as new and re-renders the image.
  • If set to false, Resolve only updates images with a resolution inadequate to fit the container.

updateImages (force)

Use

Instructs Resolve to analyze the page and update all images with the Resolve class. This method requires the arguments defined in the table below.

Argument Type Description
force boolean

Instructs Resolve to treat each element as new and update all images.

  • When set to true, Resolve re-renders all images.
  • If set to false, Resolve only updates images with a resolution inadequate to fit the container.

updateImages (imgArray, force)

Use

Instructs Resolve to process all of the elements in the array. This method requires the arguments defined in the table below.

Argument Type Description
imgArray array Contains a comma-separated list of the HTML image elements for Resolve to process. Because this is an array, the list must be enclosed in square brackets.
force boolean

Instructs Resolve to treat each element as new and update all images.

  • When set to true, Resolve re-renders all images.
  • If set to false, Resolve only updates images with a resolution inadequate to fit the container.

JavaScript API Callback Functions

JavaScript API callback functions return information about the Resolve instance or the image and browser. These functions are to be added to the options object when creating an instance of Resolve.

When adding a callback function, the syntax <callback_name>: function(arg1, arg2) should be used, followed by code that handles the returned data.

In the example below, the code uses the handleEvent callback function to display an alert if Resolve returns an error. The handleEvent callback function provides information about the status of the Resolve instance.

handleEvent: function(response, data) { if (response == 'error') {
alert(response + ': ' + data.message; 
}
}

The callback functions and returned information are described in the sections below.

handleEvent (eventName, data)

Use

Provides information about the status of the Resolve instance and associated information. This callback function requires the arguments defined in the table below.

Argument Type Description
eventName string Contains the name or type of event for which Resolve is executing the callback.
data object Contains a set of data describing the behavior of Resolve at the time of an event.

eventName

The table below shows the possible events that handleEvent can return in the eventName argument.

Event Name When it's fired
started The Resolve instance has completed initilization.
ready

The Resolve instance is ready to accept API commands.
processing The Resolve instance has initiated the optimization of an image.
processed The Resolve instance has optimized the resolution for a single image.
queued The Resolve instance receives a command while the instance is still processing a previous command.
complete The Resolve instance has optimized the resolution for all images that required processing.
skipped

The Resolve instance skips an image.
error An error occurs.

data

The data object contains a set of data describing the behavior of Resolve at the time of the event. The table below shows the contents of the data object fields for each event. Some events do not return an information about the data object.

Event(s) Object Contains
started, ready, processing, and complete No information.
skipped Element number, ID string, and reason why the event was skipped.
processed The command image chain string, element number, and ID string.
queued The string, "Resolve already running. Placed in queue."
error A string describing the error if Resolve recognizes the error.

output (browser, image)

Use

Provides information about the target device and the image that Resolve is about to process. This function also returns an object containing metadata for the image. This callback function requires the arguments defined in the table below.

Argument Type Description
browser object Contains several properties associated with the target device.
image object Includes the metadata of the image.

Returns

Type Description
Object Key:value pairs used to update the metadata for the image.

browser

The browser object contains several objects that define the properties of the target device, such as the browser and operating system. The table below shows the names and contents of these objects.

Name Type Contains
browser object The name and version of the browser the target device is using.
engine object The name of the browser engine used.
os object The name and version of the Operating System of the target device.
platform object The platform type and vendor.
window object The pixel ratio, width, and height of the viewport on the target device.

The table below contains a list of all other browser objects.

Object Name Type Description
browser.browser name string Indicates the name of the browser on the target device.
version string Specifies the version of the browser on the target device.
browser.engine name string Indicates the name of the engine running on the browser.
browser.os name string Specifies the name of the operating system on the target device.
version string Identifies the version of the operating system running on the target device.
browser.platform type string Indicates the type, such as desktop, of the target device platform.
vendor string Provides the name of the vendor that developed the platform.
browser.window devicePixelRatio floating point Specifies the pixel ratio of the viewing container.
width integer Indicates the width (in pixels) of the viewing container
height integer Indicates the height (in pixels) of the viewing container.

image

The image object contains data about the image Resolve is currently processing. The table below contains descriptions of the key:value pairs for this object.

Name Type Description
format string

Specifies the image type(s) used in the sink command. This field also accepts an array of strings.
quality string, integer, or object

Defines the quality argument set for the sink command for the given format.

This object can contain key:value pairs that specify the argument set for the different formats.

You can also include a default level for formats that are not included in the list.
source string Identifies the source of the image. This is the complete path of the image.

object

The object returned as part of the output callback function includes the metadata fields described in the table below.

Name Type Description Metadata Name
format string or array Provides the type(s) of formats available for rendering the image. global.resolve.format
quality string, integer or object Indicates the quality level of the image. global.resolve.quality
expires string Specifies the expiry time of the image. global.resolve.expires
pixelRatio integer Identifies the pixel ratio of the image. This is the value of n in n:I. global.resolve.pixelRatio

HTML Tag Attributes

Resolve supports several attributes used in any <img> tag or HTML tag that supports the background-image CSS property. The sections below contain descriptions of these attributes.

Attribute Type Default Use
class String - Required   Identifies the CSS class of image tags. To have Resolve process the image, include the strings specified in the enabledClass field of the options.advancedOptions object.
data-resolvechain String - Required if data-resolvesrc is not used   Specifies an ampersand-delimited image chain string representing the master image.
data-resolveheight Integer Value returned from StackPath

Specifies the height (in pixels) of the image.

If this attributed is omitted, Resolve queries StackPath's image optimization servers for the height of the original image.

This attribute is ignored if the height is specified in the <img> tag.

We recommend omitting this attribute as the query to StackPath's image optimization servers is typically fast.
data-resolveimagefit String 'container'

Defines how the image is scaled to fit within the image container defined in the CSS or <img> tag.

Valid values are:

  • container
  • containerwidth
  • containerheight
  • containerfill
  • stretch
  • containerpad

The value specified here overrides the value set in the imageFit field of the options JavaScript object.
data-resolvesrc String - Required if data-resolvechain is not used   Specifies the path name of the original image. If a relative path is specified, Resolve prepends the path specified with the base field of the options object.
data-resolvewidth Integer Value returned from StackPath

Specifies the width (in pixels) of the image.

If this attribute is omitted, Resolve queries StackPath's image optimization servers for the width of the original image.

This attribute is ignored if the width is specified in the <img> tag.

We recommend omitting this attribute as the query to StackPath's image optimization servers is typically fast.
data-updateonpageresize Boolean true

Determines if Resolve will process images in response to window resizing.

  • If false, Resolve will not process images in response to window resizing.
  • If true, Resolve will process image whenever the window is resized.
data-resolveoverridepixelratio Integer  

Specifies a pixel ratio that overrides the pixel ratio of the browser. The resulting ratio is n:I where n is the value entered here.

This ratio is applied only to the image or image chain specified in the HTML tag.
Was this article helpful?

Related articles

Not finding what you need?

95% of questions can be answered using the search tool. This is the quickest way to get a response.

Contact Us