Justified.js

jQuery Plugin to create Justified Image Gallery

See it in Action

Play around with the demo

About Justified.js

jQuery Plugin to Create Justified Images Grid

Justified.js is a jQuery plugin that creates a justified image grid of supplied images. Fill all the spaces! This ineffect creates a elegant image gallery with various sizes of images, where all the images of a row to have the same height.

Ideally, Justified.js tries to show images without modifying its aspect ratio and without cropping them. But want a disposition of the images without cropping them. But, when limited by the maximum row size it sometimes crop images to fill the grid.

How to Use

Lets see some code

To get started you'll have to include jquery.justified.images.js and jquery.justified.images.css files in your html file.

<link rel="stylesheet" href="jquery.justified.images.css">
<script src="jquery.justified.images.js"></script>

After this you'll have to intialize this plugin for and container. Sample initialization code is here.

$('.image-container').empty().justifiedImages({
    images : photos,
    rowHeight: 200,
    maxRowHeight: 400,
    thumbnailPath: function(photo, width, height){
        var purl = photo.url_s;
        if( photo.url_n && (width > photo.width_s * 1.2 || height > photo.height_s * 1.2) ) purl = photo.url_n;
        if( photo.url_m && (width > photo.width_n * 1.2 || height > photo.height_n * 1.2) ) purl = photo.url_m;
        if( photo.url_z && (width > photo.width_m * 1.2 || height > photo.height_m * 1.2) ) purl = photo.url_z;
        if( photo.url_l && (width > photo.width_z * 1.2 || height > photo.height_z * 1.2) ) purl = photo.url_l;
        return purl;
    },
    getSize: function(photo){
        return {width: photo.width_s, height: photo.height_s};
    },
    margin: 1
});

Options

See configuration options

Options can also be set programatically, by passing an options hash to the justifiedImages method. The idea behind this plugin is to keep it very flexible, so that it can be used for anytype of images source data. To keep that in mind you must set images, thumbnailPath and getSize during initialization. Details about the same is given below.

Option Override Type Details
images Mandatory Array This is the array which contains your images. Each image object in array could contain any data. Justified.js doesn't actually read properties of these objects, it call below mentioned functions to get what it needs. This way we keep it very flexible and customizable.
getSize Mandatory Function getSize(photo)

Returns : {width: width, height: height}

This plugin calls getSize function to get dimension of a particular image. It should returns an object containing width and height of the image. This dimension is used just to determine aspect ratio of the images, so you can return any size as long as it is maintaining aspect ratio of the request image.
thumbnailPath Mandatory Function thumbnailPath(photo, width, height)

Returns : String path to the thumbnail

This function is called to determine url for the thumbnail best bit for given width and height of the image.

Every photo website keeps different sizes of thumbnail, so that it can load smallest version of photo when required. You would have to override this function to return thumbnail path of the photo for given width and height.

rowHeight Optional Default : 150 Integer Justified.js grid making algorithm uses this as the base size of the thumbnails and tries to fit as much thumbnail it can fit in a rows. This is just starting point for the algorithm, resulting rows height could also be slightly lesser than rowHeight.
maxRowHeight Optional Default : 350 Integer As the name suggest it is the maximum height which would be allowed. If algorithm couldn't find a way to fit any image within limit, it will crop it and place it vertically in center.
template Optional Function template(photo)
  • Returns : html string for a thumbnail
  • photo : this photo object will have all the properties of the object provided in photos array. Along with them it will also have following properties:
    • displayHeight : Height of the resulting image
    • displayWidth : Width of the resulting image
    • src : Path of the thumbnail
    • marginRight : Right margin for container div. Last thumbnail will have margin-right as 0px.

For each thumbnail Justified.js wraps it under a div. You can override this function to create your own dom structure. This function should return the html string.

imageContainer Optional Default : 'photo-container' String It is the classname of the div which contains resulting thumbnail img. You must provide this classname if template function is overridden.
imageSelector Optional Default : 'image-thumb' String It is the classname of the resulting thumbnail img. You must provide this classname if template function is overridden.
margin Optional Default : 1 Integer Spacing between two thumbnails, vertically and horizontally.
appendBlocks Optional Function

Override this function if you want to append some block of html in any row. e.g. you might want to append "Add Photo" button in last row.

This function doesn't gets any argument, it sould just return an array of objects with following data format:

{
    rowNum : 1, // in which row should this block go, -1 indicates last row
    width : 150, // width of the desired block
    html : 'Add Photo' // html inside this block
}