ImageResolver.js does its best to determine the main image on a URL without loading all images.
JavaScript HTML CSS
Latest commit 023ee89 Feb 27, 2017 @mauricesvay committed on GitHub Merge pull request #14 from andrija-hers/master
Handling unzip errors
Failed to load latest commit information.
dist v0.5.4 Oct 9, 2014
example v0.5.4 Oct 9, 2014
src Handling unzip errors Feb 27, 2017
tests/node/spec Fixes Flickr now requiring https Oct 9, 2014
.gitignore Handling unzip errors Feb 27, 2017
Gulpfile.js Update browserify and build May 25, 2014 Reorganize files May 24, 2014 0.5.1 : fixes example May 25, 2014
VERSION v0.5.4 Oct 9, 2014
package.json Handling unzip errors Feb 27, 2017


ImageResolver.js is a library that extracts the main image of a URL while saving resources. Instead of loading all images of a URL, it will try to guess the main image from the URL or the webpage. It's like Readability for images.

Demo :

ImageResolver works in browsers and Node.js.

To detect images, ImageResolver comes with built-in plugins:

  • FileExtension: use file extension in urls
  • ImgurPage: extract image from urls
  • NineGag: extract image from urls
  • Instagram: extract image from urls
  • MimeType: use MIME type to detect images
  • ImgurAlbum: extract image from albums
  • Flickr: extract image from Flickr urls (requires API key)
  • Opengraph: use opengraph meta to extract image
  • Webpage: parse HTML to extract image

Of course, you can create your own plugins.

How to install

In Node.js:

npm install image-resolver

In a browser:

<script src="dist/ImageResolver.js" type="text/javascript"></script>

How to use

var resolver = new ImageResolver();
resolver.register(new ImageResolver.FileExtension());
resolver.register(new ImageResolver.MimeType());
resolver.register(new ImageResolver.Opengraph());
resolver.register(new ImageResolver.Webpage());

resolver.resolve( "", function( result ){
    if ( result ) {
        console.log( result.image );
    } else {
        console.log( "No image found" );


ImageResolver( [options] )

Create a new instance of ImageResolver

ImageResolver.register( plugin )

Register the given plugin for resolving images. You must register at least one plugin. Plugins are executed in the order of their registration.

ImageResolver.resolve( url, callback )

Extract main image from given url. Callback will be called with null when no image is found, or an object when the image is found.

How to write your own plugin

To create a plugin, create an object that has resolve method. The resolve method must have this signature:

function( url, clbk, options, utils ) {
  • url : url to resolve
  • clbk : callback
  • options : ImageResolver options
  • utils : util functions

When your plugin has found an image, you must call clbk with the image as parameter:

clbk( image_url );

If your plugin can not find an image, you must call clbk with null as parameter

clbk( null );

If your plugin needs to make HTTP GET requests, it is recommended to use utils.fetch. This function lets you make GET requests, works in browsers and Node.js, and the result will be cached and shared between plugins.

If you need more control over HTTP requests, you can use utils.request that gives you access to the raw superagent library.

Running tests

ImageResolver comes with a series of tests.

To run those tests:

  • npm install -g jasmine-node
  • npm test

Compiling the browser lib

  • npm install
  • npm install -g gulp
  • gulp to build the browser lib