# image-promise

> Load one or more images, return a promise. Only 0.4KB, for the browser, no dependencies.

Latest version **8.0.0** (published 2024-06-11) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install image-promise
pnpm add image-promise
yarn add image-promise
bun add image-promise
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 8.0.0 |
| Published | 2024-06-11 |
| First published | 2016-04-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 6.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 147 |
| Author | Federico Brigante |
| Maintainers | fregante |
| Keywords | browser, cache, image, imagesloaded, img, lazyload, load, onload, preload, promise, then, vanilla |

## Links

- npm: https://www.npmjs.com/package/image-promise
- Repository: https://github.com/fregante/image-promise
- Homepage: https://github.com/fregante/image-promise#readme
- Issues: https://github.com/fregante/image-promise/issues
- npm.io page: https://npm.io/package/image-promise

## Alternatives

- [memory-cache](https://npm.io/package/memory-cache.md) — 795.0K weekly downloads
- [@httptoolkit/proxy-agent](https://npm.io/package/@httptoolkit/proxy-agent.md) — 11.2K weekly downloads
- [express-cache-controller](https://npm.io/package/express-cache-controller.md) — 5.3K weekly downloads
- [http-cache-middleware](https://npm.io/package/http-cache-middleware.md) — 4.5K weekly downloads
- [cache2](https://npm.io/package/cache2.md) — 1.5K weekly downloads

## Recent versions

- 8.0.0 (latest) — 2024-06-11
- 5.0.0-2 (next) — 2017-03-02
- 7.0.1 — 2020-05-01
- 7.0.0 — 2019-12-09
- 6.1.1 — 2019-12-09
- 6.1.0 — 2019-11-05
- 6.0.2 — 2019-03-19
- 6.0.0 — 2019-01-05
- 5.0.1 — 2017-04-29
- 5.0.0 — 2017-03-04
- 5.0.0-1 — 2017-02-28
- 5.0.0-0 — 2017-02-28
- 4.0.1 — 2016-10-19
- 4.0.0 — 2016-10-03
- 3.0.1 — 2016-10-03
- … 7 more at https://npm.io/package/image-promise/versions

## README

# Deprecated

See https://github.com/fregante/image-promise/issues/27, use the native `img.decode()` instead.

#  image-promise [![][badge-gzip]](#link-npm)

  [badge-gzip]: https://img.shields.io/bundlephobia/minzip/image-promise.svg?label=gzipped
  [link-npm]: https://www.npmjs.com/package/image-promise

<img align="right" width="400" src="https://user-images.githubusercontent.com/1402241/81458802-b7a21580-919c-11ea-9599-377d7aee1670.gif">

> Load one or more images, return a promise. Only 0.5KB, for the browser, no dependencies.

It can be used in two ways:

- pass a URL: it will generate an `<img>` and wait for it to load:

	```js
	loadImage('img.jpg').then(/* It's loaded! */)
	```

- pass an `<img>`: it will wait for it to load:

	```js
	const img = document.querySelector('img.my-image');
	loadImage(img).then(/* It's loaded! */)
	```

- pass an array of URLs and/or `<img>`s, wait for them to load:

	```js
	const img = document.querySelector('img.my-image');
	loadImage([img, 'loading.gif']).then(/* Both are loaded! */)
	```

## Install

You can download the [standalone bundle](https://bundle.fregante.com/?pkg=image-promise&global=loadImage)

Or use `npm`:

```sh
npm install image-promise
```

```js
// This module is only offered as a ES Module
import loadImage from 'image-promise';
```

## Usage

### One image

`loadImage(image)` will return a Promise that resolves when the image load, or fails when the image

```js
const image = 'cat.jpg';
// const image = $('img')[0]; // it can also be an <img> element

loadImage(image)
.then(function (img) {
	ctx.drawImage(img, 0, 0, 10, 10);
})
.catch(function () {
	console.error('Image failed to load :(');
});
```

### Multiple images

`image-promise` can load multiple images at a time

```js
const images = ['cat.jpg', 'dog.jpg'];
// const images = $('img'); // it can also be a jQuery object
// const images = document.querySelectorAll('img'); // or a NodeList

loadImage(images)
.then(function (allImgs) {
	console.log(allImgs.length, 'images loaded!', allImgs);
})
.catch(function (err) {
	console.error('One or more images have failed to load :(');
	console.error(err.errored);
	console.info('But these loaded fine:');
	console.info(err.loaded);
});
```

### Set custom attributes

`loadImage(image, attributes)` lets you pass as the second argument an object of attributes you want to assign to the image element before it starts loading.

This is useful for example when you need [CORS enabled image](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image), where you need to set the attribute `crossorigin="anonymous"` before the image starts downloading.

```js
const image = 'https://catpics.com/cat.jpg';

loadImage(image, { crossorigin: 'anonymous' })
.then(function (img) {
	ctx.drawImage(img, 0, 0, 10, 10);

	// now you can do this
	canvas.toDataURL('image/png')
})
.catch(function () {
	console.error('Image failed to load :(');
});
```

## Dependencies

None! But you need to polyfill `window.Promise` in IE11 and lower.

## License

MIT © [Federico Brigante](https://bfred.it)

---
_Source: https://npm.io/package/image-promise · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._