A simple jQuery plugin to arrange images into a flexible grid, based on Tumblr's photoset feature. Originally the plugin was created for our Style Hatch Tumblr themes as a way to use the photoset grid in responsive layouts, but we have since expanded it for use outside of the themes.

Demos & Usage

Basic Photoset Grid

Simply call photosetGrid(); on a div with the data-layout specified and a number of images inside.

<div class="photoset-grid-basic" data-layout="12">
  <img src="img/demo/nyc1-500px.jpg" width="1280" height="960" data-highres="img/demo/nyc1-highres.jpg">
  <img src="img/demo/nyc2-500px.jpg" width="500" height="375" data-highres="img/demo/nyc2-highres.jpg">
  <img src="img/demo/nyc3-500px.jpg" width="500" height="667" data-highres="img/demo/nyc3-highres.jpg">

Custom Options

Beyond the basic usage, you can set a number of optional arguments including callback functions that are useful for adding a lightbox for high resolution images. Additionally the images in this example do not specify height and width, so the plugin waits for all the images to load before laying out the grid.

<div class="photoset-grid-custom" style="visibility: hidden;">
  <img src="img/demo/print1-500px.jpg" data-highres="img/demo/print1-highres.jpg">
  <img src="img/demo/print2-500px.jpg" data-highres="img/demo/print2-highres.jpg">
  <img src="img/demo/print3-500px.jpg" data-highres="img/demo/print3-highres.jpg">
  // Set the gutter between columns and rows
  gutter: '5px',
  // Manually set the grid layout
  layout: '21',
  // Wrap the images in links
  highresLinks: true,
  // Asign a common rel attribute
  rel: 'print-gallery',

  onInit: function(){},
  onComplete: function(){
    // Show the grid after it renders
    $('.photoset-grid-custom').attr('style', '');

Adding A Lightbox

This demonstration of the photoset grid uses the onComplete event to assign a lightbox plugin to view the high resolution images. The code below is specific to jquery.colorbox.js, but it should work virtually the same for other plugins.

<div class="photoset-grid-lightbox" data-layout="131" style="visibility: hidden;">
  <img src="img/demo/withhearts1-500px.jpg" width="1280" height="1707" data-highres="img/demo/withhearts1-highres.jpg">
  <img src="img/demo/withhearts2-500px.jpg" width="500" height="663" data-highres="img/demo/withhearts2-highres.jpg">
  <img src="img/demo/withhearts3-500px.jpg" width="500" height="500" data-highres="img/demo/withhearts3-highres.jpg">
  <img src="img/demo/withhearts4-500px.jpg" width="500" height="500" data-highres="img/demo/withhearts4-highres.jpg">
  <img src="img/demo/withhearts5-500px.jpg" width="1280" height="1280" data-highres="img/demo/withhearts5-highres.jpg">
  highresLinks: true,
  rel: 'withhearts-gallery',
  gutter: '2px',

  onComplete: function(){
    $('.photoset-grid-lightbox').attr('style', '');
    $('.photoset-grid-lightbox a').colorbox({
      photo: true,
      scalePhotos: true,

Adding Photoset Grid to Tumblr Themes

  <div class="photoset-grid" data-layout="{PhotosetLayout}" data-id="photoset{PostID}">
      <img src="{PhotoURL-500}"
        width="{PhotoWidth-500}" height="{PhotoHeight-500}"
        {block:Caption}alt="{Caption}"{/block:caption} />

  highresLinks: true,
  rel: $('.photoset-grid').attr('data-id'),
  gutter: '5px',

  onComplete: function(){});


Apply the photo set grid layout to a selected div containing images for the grid.

The only markup requirement is a data-layout attribute on the selected div. data-layout should contain a string of numbers representing the number of columns for each row.

As an option you can set the height and width attributes on all the images to instantly layout the grid, otherwise the plugin will wait for all images to load.

Understanding data-layout:



Bower package manager

You can easily install photoset-grid as a Bower package by running:

$ bower install photoset-grid