The ClusterGallery is a photo gallery for web browsers using the HTML5 Canvas element. The canvas element is a HTML5 tag that supports dynamic scriptable rendering of bitmap images. This could in the future (partly or completely) replace the Adobe Flash player.

The program is written in Javascript without using external Javascript libraries to keep the code compact. Except for Internet Explorer 6, 7 and 8 that don't support these technologies. Here I use the ExCanvas library from the Google code projects. This library emulates the Canvas element on these web browsers using their VML implementation.


If you want to see the ClusterGallery in action, check these pages:

Expressive photography

Border clustering

With this gallery I use a technique that I call 'Border clustering'. With it you can automatically add an unlimited number of borders on the inside and the outside of the image using some simple parameters. The program name is derived from this idea.

The syntax for outside borders:
 outerBorders: [borderwidth1, color1, borderwidth2, color2, ...]
An example of outside borders:
 outerBorders: [.01,"black",.03,"#93856b"]

The syntax for inside border:
 innerBorders: [borderwidth1, color1, transparency1, borderwidth2, color2, transparency2, ...]
An example of inside border:
 innerBorders: [.04,null,0.5, .006,"#3d393b",0.31]

Inside and outside borders can be combined:
 outerBorders: [0.007,"#a74ac7"],
 innerBorders: [.03,"#a74ac7",0.31]

You can define a color by using

  • color name : ex. yellow, white, black
  • RGB values : ex. rgb(0,0,0), rgb(255,255,255)
  • hexadecimal notation #rgb or #rrggbb : ex. #eee, #d1d1d1
  • ...

Border clustering examples

These examples in a gallery: link


border example outerBorders: [.01,"black", .015,"#eee"]


border example outerBorders: [0.03,"#eee"]


border example outerBorders: [0.01,"#465485",0.01,"black", 0.03,"#465485"]


border example outerBorders: [0.005,"#f6e6cc", 0.01,"#354065", 0.03,"#465485", 0.045,"black", 0.0045,"#465485"]


border example innerBorders: [.04,null,0.5, .006,"white", 0.5]


border example outerBorders: [.02,"#b59402"],
innerBorders: [.02,null,0.5, .01,"#ffd103",0.31]


border example outerBorders: [0.003,"#ccc", .02,"#404813", 0.01,"black", 0.004,"#937b4a"]


border example outerBorders: [0.008,"black", 0.004,"#465485", 0.02,"black", 0.02,"#465485", 0.01,"black", 0.004,"#465485"]


border example outerBorders: [0.005,"black", 0.01,"#562b94", 0.02,"#6740b5"],
innerBorders: [.01,null,0.5, .01,"#6740b5",0.7]


border exampleouterBorders: [0.008,"black", 0.004,"white", 0.02,"black", 0.03,"#949372"]


border exampleouterBorders: [0.007,"#a74ac7"],
innerBorders: [.03,"#a74ac7",0.31]


border example outerBorders: [0.004,"#c3cd71", 0.02,"#6a8200"]


border example outerBorders: [0.015,"black", 0.008,"#465485", 0.05,"black", 0.02,"#465485"]


Browser compatibility

The gallery has been tested with these Web browsers:

  • Internet Explorer 6, 7, 8, 9, 10
  • Firefox 2, 3.6, 4, 20
  • Opera 9, 10
  • Google Chrome 8, 9, 10, 11, 25
  • Safari 5

Using the ClusterGallery on a web page

Download this file:
Inside you can find a full working version.

This is what you need to add it to a web page:

Add this code in the < head > section of your page:

Add this code in the < body > section where the gallery will be located.

You can change the dimension and style parameters as you like. Alternatively add the style parameters in your own CSS files.

ClusterGallery with thumbnails:

ClusterGallery without thumbnails:

Copy the ClusterGallery files in your web site and adapt the links if needed in the < head > section.

The file ClusterGalleryData.js contains all the data you can change. Here you can add the folder and the images of the gallery. You can adjust the layout of the ClusterGallery with the parameters at the end of this file. For the parameters remove the comments (//) before the lines you want to change.

The folder where the images are located:
var f1 = "gallery/";

For each image this are the possible parameters:

  •  image : the image location + name
  •  thumb : the thumbnail image location and name (optional)
  •  title : a free text field (optional)
  •  descr : a free text field (optional)
  •  outerBorders : [borderwidth1, color1, borderwidth2, color2, ...] (optional)
  •  innerBorders : [borderwidth1, color1, transparency1, borderwidth2, color2, transparency2, ...] (optional)
  •  crop : [left crop, top crop, right crop, bottom crop] (optional)

Global parameters

At the end of the file ClusterGalleryData.js global parameters can be defined. To use them, remove // before the line and change the value. After each line a short description is given. Some examples:

  • defaultTitle = "Type the title here"; : the default title if no image title is given
  • defaultDescription = "Type the description here"; : the default description if no image description is given
  • outerBorders = [0.01,"white"]; : the default border around the images if no image border is defined.
  • showSlideshowIcon = false; : can the viewer start/stop the slideshow?
  • autoSlideshow = true; : Start the slideshow automatically
  • showFullScreenIcon = false; : Can the viewer go to full screen mode?
  • nextImageSpeed = 3000; : in milliseconds
  • useImagesAsThumbs = true; : if no thumb is defined for an image, use the full image
  • thumbSize = "50px"; : used if useImagesAsThumbs is true
  • ...

Source code:

The source code can be found here: ClusterGallery.src.js

Possible future versions

Because I use the canvas element there are many options for developing special effects.

I would like to add transition effects like fade, slide, swarm, ...

Because the ExCanvas library used for older Internet Explorer browsers is much slower, these effects will only be seen on the HTML5 compatible web browsers. This way the ClusterGallery will be usable on all the web browsers used today.

Version history

1.0 : 14/05/2011 : initial version

1.1 : 09/04/2013 : added crop parameter in ClusterGalleryData.js