JavaScript Load Image

A JavaScript library to load and transform image files.

Contents

• Demo
• Description
• Setup
• Usage
• Image loading
• Image scaling
• Requirements
• Browser support
• API
• Callback
  • Function signature
  • Cancel image loading
  • Callback arguments
  • Error handling
• Promise
• Options
• maxWidth
• maxHeight
• minWidth
• minHeight
• sourceWidth
• sourceHeight
• top
• right
• bottom
• left
• contain
• cover
• aspectRatio
• pixelRatio
• downsamplingRatio
• imageSmoothingEnabled
• imageSmoothingQuality
• crop
• orientation
• meta
• canvas
• crossOrigin
• noRevoke
• Metadata parsing
• Image head
• Exif parser
  • Exif Thumbnail
  • Exif IFD
  • GPSInfo IFD
  • Interoperability IFD
  • Exif parser options
• Exif writer
• IPTC parser
  • IPTC parser options
• License
• Credits

Description

JavaScript Load Image is a library to load images provided as File or Blob objects or via URL. It returns an optionally scaled, cropped or rotated HTML img or canvas element.

It also provides methods to parse image metadata to extract IPTC and Exif tags as well as embedded thumbnail images, to overwrite the Exif Orientation value and to restore the complete image header after resizing.

Setup

Install via NPM:

npm install blueimp-load-image

This will install the JavaScript files inside ./node_modules/blueimp-load-image/js/ relative to your current directory, from where you can copy them into a folder that is served by your web server.

Next include the combined and minified JavaScript Load Image script in your HTML markup:

<script src="https://github.com/blueimp/JavaScript-Load-Image/raw/v5.16.0/js/load-image.all.min.js"></script>

Or alternatively, choose which components you want to include:

<script src="https://github.com/blueimp/JavaScript-Load-Image/raw/v5.16.0/js/load-image.js"></script>


<script src="https://github.com/blueimp/JavaScript-Load-Image/raw/v5.16.0/js/load-image-scale.js"></script>


<script src="https://github.com/blueimp/JavaScript-Load-Image/raw/v5.16.0/js/load-image-meta.js"></script>


<script src="https://github.com/blueimp/JavaScript-Load-Image/raw/v5.16.0/js/load-image-fetch.js"></script>


<script src="https://github.com/blueimp/JavaScript-Load-Image/raw/v5.16.0/js/load-image-orientation.js"></script>


<script src="https://github.com/blueimp/JavaScript-Load-Image/raw/v5.16.0/js/load-image-exif.js"></script>


<script src="https://github.com/blueimp/JavaScript-Load-Image/raw/v5.16.0/js/load-image-exif-map.js"></script>


<script src="https://github.com/blueimp/JavaScript-Load-Image/raw/v5.16.0/js/load-image-iptc.js"></script>


<script src="https://github.com/blueimp/JavaScript-Load-Image/raw/v5.16.0/js/load-image-iptc-map.js"></script>

Usage

Image loading

In your application code, use the loadImage() function with callback style:

document.getElementById('file-input').onchange = function () {
  loadImage(
    this.files[0],
    function (img) {
      document.body.appendChild(img)
    },
    { maxWidth: 600 } // Options
  )
}

Or use the Promise based API like this (requires a polyfill for older browsers):

document.getElementById('file-input').onchange = function () {
  loadImage(this.files[0], { maxWidth: 600 }).then(function (data) {
    document.body.appendChild(data.image)
  })
}

With async/await (requires a modern browser or a code transpiler like Babel or TypeScript):

document.getElementById('file-input').onchange = async function () {
  let data = await loadImage(this.files[0], { maxWidth: 600 })
  document.body.appendChild(data.image)
}

Image scaling

It is also possible to use the image scaling functionality directly with an existing image:

var scaledImage = loadImage.scale(
  img, // img or canvas element
  { maxWidth: 600 }
)

Requirements

The JavaScript Load Image library has zero dependencies, but benefits from the following two polyfills:

• blueimp-canvas-to-blob for browsers without native HTMLCanvasElement.toBlob support, to create Blob objects out of canvas elements.
• promise-polyfill to be able to use the Promise based loadImage API in Browsers without native Promise support.

Browser support

Browsers which implement the following APIs support all options:

• Loading images from File and Blob objects:
• URL.createObjectURL or FileReader.readAsDataURL
• Parsing meta data:
• FileReader.readAsArrayBuffer
• Blob.slice
• DataView (no BigInt support required)
• Parsing meta data from images loaded via URL:
• fetch Response.blob or XMLHttpRequest.responseType blob
• Promise based API:
• Promise

This includes (but is not limited to) the following browsers:

• Chrome 32+
• Firefox 29+
• Safari 8+
• Mobile Chrome 42+ (Android)
• Mobile Firefox 50+ (Android)
• Mobile Safari 8+ (iOS)
• Edge 74+
• Edge Legacy 12+
• Internet Explorer 10+ *

* Internet Explorer requires a polyfill for the Promise based API.

Loading an image from a URL and applying transformations (scaling, cropping and rotating - except orientation:true, which requires reading meta data) is supported by all browsers which implement the HTMLCanvasElement interface.

Loading an image from a URL and scaling it in size is supported by all browsers which implement the img element and has been tested successfully with browser engines as old as Internet Explorer 5 (via IE11's emulation mode).

The loadImage() function applies options using progressive enhancement and falls back to a configuration that is supported by the browser, e.g. if the canvas element is not supported, an equivalent img element is returned.

API

Callback

Function signature

The loadImage() function accepts a File or Blob object or an image URL as first argument.

If a File or Blob is passed as parameter, it returns an HTML img element if the browser supports the URL API, alternatively a FileReader object if the FileReader API is supported, or false.

It always returns an HTML img element when passing an image URL:

var loadingImage = loadImage(
  'https://example.org/image.png',
  function (img) {
    document.body.appendChild(img)
  },
  { maxWidth: 600 }
)

Cancel image loading

Some browsers (e.g. Chrome) will cancel the image loading process if the src property of an img element is changed.
To avoid unnecessary requests, we can use the data URL of a 1x1 pixel transparent GIF image as src target to cancel the original image download.

To disable callback handling, we can also unset the image event handlers and for maximum browser compatibility, cancel the file reading process if the returned object is a FileReader instance:

var loadingImage = loadImage(
  'https://example.org/image.png',
  function (img) {
    document.body.appendChild(img)
  },
  { maxWidth: 600 }
)

if (loadingImage) {
  // Unset event handling for the loading image:
  loadingImage.onload = loadingImage.onerror = null

  // Cancel image loading process:
  if (loadingImage.abort) {
    // FileReader instance, stop the file reading process:
    loadingImage.abort()
  } else {
    // HTMLImageElement element, cancel the original image request by changing
    // the target source to the data URL of a 1x1 pixel transparent image GIF:
    loadingImage.src =
      'data:image/gif;base64,' +
      'R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7'
  }
}

Please note:
The img element (or FileReader instance) for the loading image is only returned when using the callback style API and not available with the Promise based API.

Callback arguments

For the callback style API, the second argument to loadImage() must be a callback function, which is called when the image has been loaded or an error occurred while loading the image.

The callback function is passed two arguments:

1. An HTML img element or canvas element, or an Event object of type error.
2. An object with the original image dimensions as properties and potentially additional metadata.

loadImage(
  fileOrBlobOrUrl,
  function (img, data) {
    document.body.appendChild(img)
    console.log('Original image width: ', data.originalWidth)
    console.log('Original image height: ', data.originalHeight)
  },
  { maxWidth: 600, meta: true }
)

Please note:
The original image dimensions reflect the natural width and height of the loaded image before applying any transformation.
For consistent values across browsers, metadata parsing has to be enabled via meta:true, so loadImage can detect automatic image orientation and normalize the dimensions.

Error handling

Example code implementing error handling:

loadImage(
  fileOrBlobOrUrl,
  function (img, data) {
    if (img.type === 'error') {
      console.error('Error loading image file')
    } else {
      document.body.appendChild(img)
    }
  },
  { maxWidth: 600 }
)

Promise

If the loadImage() function is called without a callback function as second argument and the Promise API is available, it returns a Promise object:

loadImage(fileOrBlobOrUrl, { maxWidth: 600, meta: true })
  .then(function (data) {
    document.body.appendChild(data.image)
    console.log('Original image width: ', data.originalWidth)
    console.log('Original image height: ', data.originalHeight)
  })
  .catch(function (err) {
    // Handling image loading errors
    console.log(err)
  })

The Promise resolves with an object with the following properties:

• image: An HTML img or canvas element.
• originalWidth: The original width of the image.
• originalHeight: The original height of the image.

Please also read the note about original image dimensions normalization in the callback arguments section.

If metadata has been parsed, additional properties might be present on the object.

If image loading fails, the Promise rejects with an Event object of type error.

Options

The optional options argument to loadImage() allows to configure the image loading.

It can be used the following way with the callback style:

```js loadImage( fileOrBlobOrUrl, function (img) { document.body.appendChild(img) }, { maxWidth: 600, maxHeight: 300,