JavaScript Load Image

A JavaScript library to load and transform image files.

• 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

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.

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="js/load-image.all.min.js"></script>

Or alternatively, choose which components you want to include:

<!-- required for all operations -->
<script src="js/load-image.js"></script>

<!-- required for scaling, cropping and as dependency for rotation -->
<script src="js/load-image-scale.js"></script>

<!-- required to parse meta data and to restore the complete image head -->
<script src="js/load-image-meta.js"></script>

<!-- required to parse meta data from images loaded via URL -->
<script src="js/load-image-fetch.js"></script>

<!-- required for rotation and cross-browser image orientation -->
<script src="js/load-image-orientation.js"></script>

<!-- required to parse Exif tags and cross-browser image orientation -->
<script src="js/load-image-exif.js"></script>

<!-- required to display text mappings for Exif tags -->
<script src="js/load-image-exif-map.js"></script>

<!-- required to parse IPTC tags -->
<script src="js/load-image-iptc.js"></script>

<!-- required to display text mappings for IPTC tags -->
<script src="js/load-image-iptc-map.js"></script>

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)
}

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 }
)

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.

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