#imgix.js Documentation imgix is the root namespace for all imgix client code.

Members

imgix

##imgix.onready Runs a function when the DOM is ready (similar to jQuery.ready)

Params

ready function - the function to run when the DOM is ready.

##imgix.isImageElement(el) Reports if an element is an image tag

Params

el Element - the element to check

Returns: boolean - true if the element is an img tag
##imgix.setElementImageAfterLoad(el, url, callback) Intelligently sets an image on an element after the image has been cached.

Params

el Element - the element to place the image on
url string - the url of the image to set
callback function - called once image has been preloaded and set

##imgix.setElementImage(el, url) Intelligently sets an image on an element.

Params

el Element - the element to check
url string - the url of the image to set

Returns: boolean - true on success
##imgix.getEmptyImage() An empty 1x1 transparent image

Returns: string - url of an empty image
##imgix.getElementImage(el) Intelligently returns the image on the element

Params

el Element - the element to check

Returns: string - url of the image on the element
##imgix.getBackgroundImage(el) Returns the background image for an element

Params

el Element - the element to check

Returns: string - url of the image on the element
##imgix.getColorBrightness(color) Gives a brightness score for a given color (higher is brighter)

Params

color string - a color in rgb(r, g, b) format

Returns: Number - brightness score for the passed color
##imgix.applyAlphaToRGB(color, alpha) Apply alpha to a RGB color string

Params

color string - a color in rgb(r, g, b) format
alpha number - aplpha amount 1=opaque 0=transparent

Returns: string - color in rgba format rgb(255, 0, 255, 0.5)
##imgix.hexToRGB(color) Converts a hex color to rgb (#ff00ff -> rgb(255, 0, 255)

Params

color string - a color in hex format (#ff00ff)

Returns: string - color in rgb format rgb(255, 0, 255)
##imgix.getElementsWithImages() Gives all elements on the page that have images (or could img). Does NOT support IE8

Returns: NodeList - html elements with images
##imgix.hasImage(el) Does an element have an image attached

Params

el Element - element to check for images

Returns: boolean - true if passed element has an image
##imgix.hasClass(elem, name) Checks if an element has a class applied (via jquery)

Params

elem Element - element to check for class
name string - class name to look for

Returns: boolean - true if element has the class
##imgix.rgbToHex(color) Helper method to turn rgb(255, 255, 255) style colors to hex (ffffff)

Params

color string - in rgb(255, 255, 255) format

Returns: string - passed color converted to hex
##imgix.getFontLookup() Returns a font lookup. Pretty Name => name to use with imgix Example: "American Typewriter Bold" => "American Typewriter,bold",

Returns: object - pretty font name to imgix font param value
##imgix.getFonts() Get a list of all the fonts supported by imgix

Returns: array - An array of strings of the supported font names
##imgix.fluid(config) Enables fluid (responsive) images for any element(s) with the "imgix-fluid" class

#####Option Descriptions

fluidClass string all elements with this class will have responsive images

updateOnResize boolean should it request a new bigger image when container grows

updateOnResizeDown boolean should it request a new smaller image when container shrinks

updateOnPinchZoom boolean should it request a new image when pinching on a mobile device

highDPRAutoScaleQuality boolean should it automatically use a lower quality image on high DPR devices. This is usually nearly undetectable by a human, but offers a significant decrease in file size.

onChangeParamOverride function if defined the following are passed (number h, number w, object params, HTMLElement element). When an object of params is returned they are applied to the image

autoInsertCSSBestPractices boolean should it automatically add backgroundRepeat = 'no-repeat; elem.style.backgroundSize = 'cover' elem.style.backgroundPosition = '50% 50%' to elements with a background image

fitImgTagToContainerWidth boolean should it fit img tag elements to their container's width. Does not apply to background images.

fitImgTagToContainerHeight boolean should it fit img tag elements to their container's height. Does not apply to background images.

pixelStep number image dimensions are rounded to this (e.g. for 10 the value 333 would be rounded to 340)

token string the secure URL token to use to sign an image. when this is set URLs are automatically signed using this token

ignoreDPR boolean when true the dpr param is not set on the image.

debounce number postpones resize/lazy load execution until after this many milliseconds have elapsed since the last time it was invoked.

lazyLoad boolean when true the image is not actually loaded until it is viewable (or within the offset)

lazyLoadOffsetVertical number when lazyLoad is true this allows you to set how far above and below the viewport (in pixels) you want before imgix.js starts to load the images.

lazyLoadOffsetHorizontal number when lazyLoad is true this allows you to set how far to the left and right of the viewport (in pixels) you want before imgix.js starts to load the images.

lazyLoadColor boolean or number or function When defined the image container's background is set to a color in the image. When value is true use first color in the color array, when value is a number use that index from the color array, when value is a function it uses whatever color is returned by the function(HTMLElement' el, Array` colors)

maxWidth number Never set the width parameter higher than this value.

maxHeight number Never set the height parameter higher than this value.

onLoad function Called when an image is loaded. It's passed the HTMLElement that contains the image that was just loaded and the URL of that image (HTMLElement' el, String` imageURL)

Default values (passed config will extend these values)

{
	fluidClass: "imgix-fluid",
	updateOnResize: true,
	updateOnResizeDown : false,
	updateOnPinchZoom: false,
	highDPRAutoScaleQuality: true,
	onChangeParamOverride: null,
	autoInsertCSSBestPractices: false,
	fitImgTagToContainerWidth: true,
	fitImgTagToContainerHeight: false,
	pixelStep: 10,
	token: null,
	debounce: 200,
	ignoreDPR: false,
	lazyLoad: false,
	lazyLoadOffsetVertical: 20,
	lazyLoadOffsetHorizontal: 20,
	maxWidth: 5000,
	maxHeight: 5000,
	onLoad: null
}

Params

config object - options for fluid (this extends the defaults)

##imgix.helpers The helper namespace for lower-level functions

Members

imgix.helpers

##class: imgix.URL Members

class: imgix.URL

###new imgix.URL(url, imgParams, token) Represents an imgix url

Params

url string - An imgix url to start with (optional)
imgParams object - imgix query string params (optional)
token object - secure url token for signing images (optional)

###URL.setSepia(val) Apply the speia imgix param to the image url. Same as doing .setParam('sepia', val);

Params

val - the value to set for sepia

###URL.setCrop(val) Apply the "crop" imgix param to the image url. Same as doing .setParam('crop', val)

Params

val - the value to set for crop

###URL.setFit(val) Apply the "fit" imgix param to the image url. Same as doing .setParam('fit', val)

Params

val - the value to set for fit

###URL.setHeight(val) Apply the "h" imgix param to the image url. Same as doing .setParam('h', val)

Params

val - the value to set for h

###URL.setWidth(val) Apply the "w" imgix param to the image url. Same as doing .setParam('w', val)

Params

val - the value to set for w

###URL.setRotate(val) Apply the "rot" imgix param to the image url. Same as doing .setParam('rot', val)

Params

val - the value to set for rot

###URL.setFlip(val) Apply the "flip" imgix param to the image url. Same as doing .setParam('flip', val)

Params

val - the value to set for flip

###URL.setOrient(val) Apply the "or" imgix param to the image url. Same as doing .setParam('or', val)

Params

val - the value to set for or

###URL.setDPR(val) Apply the "dpr" imgix param to the image url. Same as doing .setParam('dpr', val)

Params

val - the value to set for dpr

###URL.setHue(val) Apply the "hue" imgix param to the image url. Same as doing .setParam('hue', val)

Params

val - the value to set for hue

###URL.setSaturation(val) Apply the "sat" imgix param to the image url. Same as doing .setParam('sat', val)

Params

val - the value to set for sat

###URL.setBrightness(val) Apply the "bri" imgix param to the image url. Same as doing .setParam('bri', val)

Params

val - the value to set for bri

###URL.setContrast(val) Apply the "con" imgix param to the image url. Same as doing .setParam('con', val)

Params

val - the value to set for con

###URL.setExposure(val) Apply the "exp" imgix param to the image url. Same as doing .setParam('exp', val)

Params

val - the value to set for exp

###URL.setHighlight(val) Apply the "high" imgix param to the image url. Same as doing .setParam('high', val)

Params

val - the value to set for high

###URL.setShadow(val) Apply the "shad" imgix param to the image url. Same as doing .setParam('shad', val)

Params

val - the value to set for shad

###URL.setGamma(val) Apply the "gam" imgix param to the image url. Same as doing .setParam('gam', val)

Params

val - the value to set for gam

###URL.setVibrance(val) Apply the "vib" imgix param to the image url. Same as doing .setParam('vib', val)

Params

val - the value to set for vib

###URL.setSharpness(val) Apply the "sharp" imgix param to the image url. Same as doing .setParam('sharp', val)

Params

val - the value to set for sharp

###URL.setSepia(val) Apply the "sepia" imgix param to the image url. Same as doing .setParam('sepia', val)

Params

val - the value to set for sepia

###URL.setHalftone(val) Apply the "htn" imgix param to the image url. Same as doing .setParam('htn', val)

Params

val - the value to set for htn

###URL.setBlur(val) Apply the "blur" imgix param to the image url. Same as doing .setParam('blur', val)

Params

val - the value to set for blur

###URL.setMonochrome(val) Apply the "mono" imgix param to the image url. Same as doing .setParam('mono', val)

Params

val - the value to set for mono

###URL.setPixelate(val) Apply the "px" imgix param to the image url. Same as doing .setParam('px', val)

Params

val - the value to set for px

###URL.setBlend(val) Apply the "blend" imgix param to the image url. Same as doing .setParam('blend', val)

Params

val - the value to set for blend

###URL.setBlendWidth(val) Apply the "bw" imgix param to the image url. Same as doing .setParam('bw', val)

Params

val - the value to set for bw

###URL.setBlendHeight(val) Apply the "bh" imgix param to the image url. Same as doing .setParam('bh', val)

Params

val - the value to set for bh

###URL.setBlendPadding(val) Apply the "bp" imgix param to the image url. Same as doing .setParam('bp', val)

Params

val - the value to set for bp

###URL.setBlendFit(val) Apply the "bf" imgix param to the image url. Same as doing .setParam('bf', val)

Params

val - the value to set for bf

###URL.setBlendAlign(val) Apply the "ba" imgix param to the image url. Same as doing .setParam('ba', val)

Params

val - the value to set for ba

###URL.setBlendAlpha(val) Apply the "balph" imgix param to the image url. Same as doing .setParam('balph', val)

Params

val - the value to set for balph

###URL.setBlendMode(val) Apply the "bm" imgix param to the image url. Same as doing .setParam('bm', val)

Params

val - the value to set for bm

###URL.setBlendCrop(val) Apply the "bc" imgix param to the image url. Same as doing .setParam('bc', val)

Params

val - the value to set for bc

###URL.setBlendSize(val) Apply the "bs" imgix param to the image url. Same as doing .setParam('bs', val)

Params

val - the value to set for bs

###URL.setText(val) Apply the "txt" imgix param to the image url. Same as doing .setParam('txt', val)

Params

val - the value to set for txt

###URL.setTextFont(val) Apply the "txtfont" imgix param to the image url. Same as doing .setParam('txtfont', val)

Params

val - the value to set for txtfont

###URL.setTextSize(val) Apply the "txtsize" imgix param to the image url. Same as doing .setParam('txtsize', val)

Params

val - the value to set for txtsize

###URL.setTextColor(val) Apply the "txtclr" imgix param to the image url. Same as doing .setParam('txtclr', val)

Params

val - the value to set for txtclr

###URL.setTextAlign(val) Apply the "txtalign" imgix param to the image url. Same as doing .setParam('txtalign', val)

Params

val - the value to set for txtalign

###URL.setTextShadow(val) Apply the "txtshad" imgix param to the image url. Same as doing .setParam('txtshad', val)

Params

val - the value to set for txtshad

###URL.setTextPad(val) Apply the "txtpad" imgix param to the image url. Same as doing .setParam('txtpad', val)

Params

val - the value to set for txtpad

###URL.setTextLine(val) Apply the "txtline" imgix param to the image url. Same as doing .setParam('txtline', val)

Params

val - the value to set for txtline

###URL.setTextLineColor(val) Apply the "txtlineclr" imgix param to the image url. Same as doing .setParam('txtlineclr', val)

Params

val - the value to set for txtlineclr

###URL.setTextFit(val) Apply the "txtfit" imgix param to the image url. Same as doing .setParam('txtfit', val)

Params

val - the value to set for txtfit

###URL.setFormat(val) Apply the "fm" imgix param to the image url. Same as doing .setParam('fm', val)

Params

val - the value to set for fm

###URL.setQuality(val) Apply the "q" imgix param to the image url. Same as doing .setParam('q', val)

Params

val - the value to set for q

###URL.setWatermark(val) Apply the "mark" imgix param to the image url. Same as doing .setParam('mark', val)

Params

val - the value to set for mark

###URL.setWatermarkWidth(val) Apply the "markw" imgix param to the image url. Same as doing .setParam('markw', val)

Params

val - the value to set for markw

###URL.setWatermarkHeight(val) Apply the "markh" imgix param to the image url. Same as doing .setParam('markh', val)

Params

val - the value to set for markh

###URL.setWatermarkFit(val) Apply the "markfit" imgix param to the image url. Same as doing .setParam('markfit', val)

Params

val - the value to set for markfit

###URL.setWatermarkScale(val) Apply the "markscale" imgix param to the image url. Same as doing .setParam('markscale', val)

Params

val - the value to set for markscale

###URL.setWatermarkAlign(val) Apply the "markalign" imgix param to the image url. Same as doing .setParam('markalign', val)

Params

val - the value to set for markalign

###URL.setWatermarkAlpha(val) Apply the "markalpha" imgix param to the image url. Same as doing .setParam('markalpha', val)

Params

val - the value to set for markalpha

###URL.setWatermarkPadding(val) Apply the "markpad" imgix param to the image url. Same as doing .setParam('markpad', val)

Params

val - the value to set for markpad

###URL.setPalette(val) Apply the "palette" imgix param to the image url. Same as doing .setParam('palette', val)

Params

val - the value to set for palette

###URL.setPaletteClass(val) Apply the "class" imgix param to the image url. Same as doing .setParam('class', val)

Params

val - the value to set for class

###URL.setPaletteColorNumber(val) Apply the "colors" imgix param to the image url. Same as doing .setParam('colors', val)

Params

val - the value to set for colors

###URL.setAuto(val) Apply the "auto" imgix param to the image url. Same as doing .setParam('auto', val)

Params

val - the value to set for auto

###URL.setMask(val) Apply the "mask" imgix param to the image url. Same as doing .setParam('mask', val)

Params

val - the value to set for mask

###URL.setBackground(val) Apply the "bg" imgix param to the image url. Same as doing .setParam('bg', val)

Params

val - the value to set for bg

###URL.getCrop(val) Apply the "invert" imgix param to the image url. Same as doing .setParam('invert', val)

Params

val - the value to set for invert

###URL.getFit() Get the value of the "fit" imgix param currently on the image url. Same as doing .getParam('fit')

###URL.getHeight() Get the value of the "h" imgix param currently on the image url. Same as doing .getParam('h')

###URL.getWidth() Get the value of the "w" imgix param currently on the image url. Same as doing .getParam('w')

###URL.getRotate() Get the value of the "rot" imgix param currently on the image url. Same as doing .getParam('rot')

###URL.getFlip() Get the value of the "flip" imgix param currently on the image url. Same as doing .getParam('flip')

###URL.getOrient() Get the value of the "or" imgix param currently on the image url. Same as doing .getParam('or')

###URL.getDPR() Get the value of the "dpr" imgix param currently on the image url. Same as doing .getParam('dpr')

###URL.getHue() Get the value of the "hue" imgix param currently on the image url. Same as doing .getParam('hue')

###URL.getSaturation() Get the value of the "sat" imgix param currently on the image url. Same as doing .getParam('sat')

###URL.getBrightness() Get the value of the "bri" imgix param currently on the image url. Same as doing .getParam('bri')

###URL.getContrast() Get the value of the "con" imgix param currently on the image url. Same as doing .getParam('con')

###URL.getExposure() Get the value of the "exp" imgix param currently on the image url. Same as doing .getParam('exp')

###URL.getHighlight() Get the value of the "high" imgix param currently on the image url. Same as doing .getParam('high')

###URL.getShadow() Get the value of the "shad" imgix param currently on the image url. Same as doing .getParam('shad')

###URL.getGamma() Get the value of the "gam" imgix param currently on the image url. Same as doing .getParam('gam')

###URL.getVibrance() Get the value of the "vib" imgix param currently on the image url. Same as doing .getParam('vib')

###URL.getSharpness() Get the value of the "sharp" imgix param currently on the image url. Same as doing .getParam('sharp')

###URL.getSepia() Get the value of the "sepia" imgix param currently on the image url. Same as doing .getParam('sepia')

###URL.getHalftone() Get the value of the "htn" imgix param currently on the image url. Same as doing .getParam('htn')

###URL.getBlur() Get the value of the "blur" imgix param currently on the image url. Same as doing .getParam('blur')

###URL.getMonochrome() Get the value of the "mono" imgix param currently on the image url. Same as doing .getParam('mono')

###URL.getPixelate() Get the value of the "px" imgix param currently on the image url. Same as doing .getParam('px')

###URL.getBlend() Get the value of the "blend" imgix param currently on the image url. Same as doing .getParam('blend')

###URL.getBlendWidth() Get the value of the "bw" imgix param currently on the image url. Same as doing .getParam('bw')

###URL.getBlendHeight() Get the value of the "bh" imgix param currently on the image url. Same as doing .getParam('bh')

###URL.getBlendPadding() Get the value of the "bp" imgix param currently on the image url. Same as doing .getParam('bp')

###URL.getBlendFit() Get the value of the "bf" imgix param currently on the image url. Same as doing .getParam('bf')

###URL.getBlendAlign() Get the value of the "ba" imgix param currently on the image url. Same as doing .getParam('ba')

###URL.getBlendAlpha() Get the value of the "balph" imgix param currently on the image url. Same as doing .getParam('balph')

###URL.getBlendMode() Get the value of the "bm" imgix param currently on the image url. Same as doing .getParam('bm')

###URL.getBlendCrop() Get the value of the "bc" imgix param currently on the image url. Same as doing .getParam('bc')

###URL.getBlendSize() Get the value of the "bs" imgix param currently on the image url. Same as doing .getParam('bs')

###URL.getText() Get the value of the "txt" imgix param currently on the image url. Same as doing .getParam('txt')

###URL.getTextFont() Get the value of the "txtfont" imgix param currently on the image url. Same as doing .getParam('txtfont')

###URL.getTextSize() Get the value of the "txtsize" imgix param currently on the image url. Same as doing .getParam('txtsize')

###URL.getTextColor() Get the value of the "txtclr" imgix param currently on the image url. Same as doing .getParam('txtclr')

###URL.getTextAlign() Get the value of the "txtalign" imgix param currently on the image url. Same as doing .getParam('txtalign')

###URL.getTextShadow() Get the value of the "txtshad" imgix param currently on the image url. Same as doing .getParam('txtshad')

###URL.getTextPad() Get the value of the "txtpad" imgix param currently on the image url. Same as doing .getParam('txtpad')

###URL.getTextLine() Get the value of the "txtline" imgix param currently on the image url. Same as doing .getParam('txtline')

###URL.getTextLineColor() Get the value of the "txtlineclr" imgix param currently on the image url. Same as doing .getParam('txtlineclr')

###URL.getTextFit() Get the value of the "txtfit" imgix param currently on the image url. Same as doing .getParam('txtfit')

###URL.getFormat() Get the value of the "fm" imgix param currently on the image url. Same as doing .getParam('fm')

###URL.getQuality() Get the value of the "q" imgix param currently on the image url. Same as doing .getParam('q')

###URL.getWatermark() Get the value of the "mark" imgix param currently on the image url. Same as doing .getParam('mark')

###URL.getWatermarkWidth() Get the value of the "markw" imgix param currently on the image url. Same as doing .getParam('markw')

###URL.getWatermarkHeight() Get the value of the "markh" imgix param currently on the image url. Same as doing .getParam('markh')

###URL.getWatermarkFit() Get the value of the "markfit" imgix param currently on the image url. Same as doing .getParam('markfit')

###URL.getWatermarkScale() Get the value of the "markscale" imgix param currently on the image url. Same as doing .getParam('markscale')

###URL.getWatermarkAlign() Get the value of the "markalign" imgix param currently on the image url. Same as doing .getParam('markalign')

###URL.getWatermarkAlpha() Get the value of the "markalpha" imgix param currently on the image url. Same as doing .getParam('markalpha')

###URL.getWatermarkPadding() Get the value of the "markpad" imgix param currently on the image url. Same as doing .getParam('markpad')

###URL.getPalette() Get the value of the "palette" imgix param currently on the image url. Same as doing .getParam('palette')

###URL.getPaletteClass() Get the value of the "class" imgix param currently on the image url. Same as doing .getParam('class')

###URL.getPaletteColorNumber() Get the value of the "colors" imgix param currently on the image url. Same as doing .getParam('colors')

###URL.getAuto() Get the value of the "auto" imgix param currently on the image url. Same as doing .getParam('auto')

###URL.getMask() Get the value of the "mask" imgix param currently on the image url. Same as doing .getParam('mask')

###URL.getBackground() Get the value of the "bg" imgix param currently on the image url. Same as doing .getParam('bg')

###URL.getInvert() Get the value of the "invert" imgix param currently on the image url. Same as doing .getParam('invert')

###URL.attachGradientTo(elemOrSel, baseColor) Attach a gradient of colors from the imgix image URL to the passed html element (or selector for that element)

Params

elemOrSel string - html elment or css selector for the element
baseColor string - color in rgb or hex

###URL.attachImageTo(elemOrSel, callback) Attach the image url (.getUrl() value) to the passed html element (or selector for that element)

Params

elemOrSel string - html elment or css selector for the element
callback function - optional callback to be called when image is set on the element

###URL.setToken(token) Set the token for signing images. If a token is set it will always sign the generated urls

Params

token string - secure url token from your imgix source

###URL.getColors(num, callback) Get an array of the colors in the image

Params

num number - Desired number of colors
callback colorsCallback - handles the response of colors

###URL.autoUpdateImg(sel, callback) When/if the url changes it will auto re-set the image on the element of the css selector passed

Params

sel string - css selector for an element on the page
callback autoUpdateElementCallback - fires whenever the img element is updated

###URL.getUrl() The generated imgix image url

Returns: string - the generated url
###URL.removeParam(param) Remove an imgix param

Params

param string - the imgix param to remove (e.g. txtfont)

###URL.clearThenSetParams(params) Remove an imgix param then immediately set new params. This only triggers one update if used with autoUpdateImg.

Params

params object - object of params to set

###URL.clearParams(runUpdate) Clear all imgix params attached to the image

Params

runUpdate boolean - (optional) iff using autoUpdateImg should callback be called (defaults to true)

###URL.setParams(dict, doOverride) Set multiple params using using an object (e.g. {txt: "hello", txtclr: "f00"})

Params

dict object - an object of imgix params and their values
doOverride boolean - should the value(s) be overridden if they already exist (defaults to true)

###URL.setParam(param, value, doOverride, noUpdate) Set a single imgix param value

Params

param string - the imgix param to set (e.g. txtclr)
value string - the value to set for the param
doOverride boolean - (optional) should the value(s) be overridden if they already exist (defaults to true)
noUpdate boolean - (optional) iff using autoUpdateImg should callback be called (defaults to false)

###URL.getParam(param) Get the value of an imgix param in the query string

Params

param string - the imgix param that you want the value of (e.g. txtclr)

Returns: string - the value of the param in the current url
###URL.getParams() Get an object of all the params and their values on the current image

Returns: object - an object of params and their values (e.g. {txt: "hello", txtclr: "f00"})
###URL.getBaseUrl() Get the base url. This is getUrl() without the query string

Returns: string - the base url
###URL.getQueryString() Get the query string only. This is getUrl() with ONLY the query string (e.g. ?txt=hello&txtclr=f00)

Returns: string - the query string for the url
#callback: colorsCallback This callback receives the colors in the image.

Params

colors array - an array of colors

Type: function
#callback: autoUpdateElementCallback Params

obj object - information about element and image

Type: function

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

api.md

api.md

Files

api.md

Latest commit

History

api.md

File metadata and controls