Skip to content

Commit 2ca9ff8

Browse files
committed
Docs: Add info on how to cancel image loading.
1 parent da05026 commit 2ca9ff8

File tree

1 file changed

+39
-12
lines changed

1 file changed

+39
-12
lines changed

README.md

Lines changed: 39 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
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
129130
document.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
145145
document.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
285293
var 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

299326
For the callback style API, the second argument to `loadImage()` must be a

0 commit comments

Comments
 (0)