1515- [ API] ( #api )
1616 - [ Callback] ( #callback )
1717 - [ Function signature] ( #function-signature )
18- - [ Canceling event handling ] ( #canceling-event-handling )
18+ - [ Cancel image loading ] ( #cancel-image-loading )
1919 - [ Callback arguments] ( #callback-arguments )
2020 - [ Error handling] ( #error-handling )
2121 - [ Promise] ( #promise )
@@ -123,7 +123,8 @@ Or alternatively, choose which components you want to include:
123123
124124### Image loading
125125
126- In your application code, use the ` loadImage() ` function like this:
126+ In your application code, use the ` loadImage() ` function with
127+ [ callback] ( #callback ) style:
127128
128129``` js
129130document .getElementById (' file-input' ).onchange = function () {
@@ -137,9 +138,8 @@ document.getElementById('file-input').onchange = function () {
137138}
138139```
139140
140- Or use the
141- [ Promise] ( https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise )
142- based API like this ([ requires] ( #requirements ) a polyfill for older browsers):
141+ Or use the [ Promise] ( #promise ) based API like this ([ requires] ( #requirements ) a
142+ polyfill for older browsers):
143143
144144``` js
145145document .getElementById (' file-input' ).onchange = function () {
@@ -274,12 +274,20 @@ var loadingImage = loadImage(
274274)
275275```
276276
277- #### Canceling event handling
277+ #### Cancel image loading
278278
279- The ` img ` element or
280- [ FileReader] ( https://developer.mozilla.org/en-US/docs/Web/API/FileReader ) object
281- returned by the ` loadImage() ` function allows to cancel event handling by
282- setting the ` onload ` and ` onerror ` event handlers to null:
279+ Some browsers (e.g. Chrome) will cancel the image loading process if the ` src `
280+ property of an ` img ` element is changed.
281+ To avoid unnecessary requests, we can use the
282+ [ data URL] ( https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs )
283+ of a 1x1 pixel transparent GIF image as ` src ` target to cancel the original
284+ image download.
285+
286+ To disable callback handling, we can also unset the image event handlers and for
287+ maximum browser compatibility, cancel the file reading process if the returned
288+ object is a
289+ [ FileReader] ( https://developer.mozilla.org/en-US/docs/Web/API/FileReader )
290+ instance:
283291
284292``` js
285293var loadingImage = loadImage (
@@ -290,10 +298,29 @@ var loadingImage = loadImage(
290298 { maxWidth: 600 }
291299)
292300
293- // Cancel event handling:
294- loadingImage .onload = loadingImage .onerror = null
301+ if (loadingImage) {
302+ // Unset event handling for the loading image:
303+ loadingImage .onload = loadingImage .onerror = null
304+
305+ // Cancel image loading process:
306+ if (loadingImage .abort ) {
307+ // FileReader instance, stop the file reading process:
308+ loadingImage .abort ()
309+ } else {
310+ // HTMLImageElement element, cancel the original image request by changing
311+ // the target source to the data URL of a 1x1 pixel transparent image GIF:
312+ loadingImage .src =
313+ ' data:image/gif;base64,' +
314+ ' R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7'
315+ }
316+ }
295317```
296318
319+ ** Please note:**
320+ The ` img ` element (or ` FileReader ` instance) for the loading image is only
321+ returned when using the callback style API and not available with the
322+ [ Promise] ( #promise ) based API.
323+
297324#### Callback arguments
298325
299326For the callback style API, the second argument to ` loadImage() ` must be a
0 commit comments