DIY Masonry-Style Image Gallery

source code

I recently gave up on image gallery plugins for WordPress. They come with extra overhead, they do too many things I don’t need, and they don’t do enough of what I want. Furthermore, I dislike how WordPress organizes content. I want control, automation, and a beautiful layout.
Final Product - PIG Gallery on
Take a look at one of my image galleries for a working demo of what I came up with. This post will walk you through how to build image galleries like this one with minimal effort.


  1. 1.

    Basic PIG. Progressive Image Grid (PIG.js) is the JavaScript library that will power our image gallery. We’ll get a simple test page up and running with out-of-the-box PIG.

  2. 2.

    Extending PIG. PIG needs a few tweaks to reach its full potential. We’ll make a few quick adaptations, including adding Swipebox support.

  3. 3.

    Automation. While the PIG library is handy, it doesn’t do the heavy lifting of generating all those image thumbnails and directory structures we need. As with all problems in the universe, the solution is a Perl script to automate things.

  4. 4.

    WordPress Integration. The above steps are sufficient to facilitate the creation of image galleries with minimal effort. You can stop there if you want to, or optionally add some code to WordPress to simplify adding PIG-powered galleries. This step will not require any plugin installation. Instead, we’ll build a lightweight custom plugin from scratch so you have complete visibility and control over what is going on.

Basic PIG

Dan Schlosser’s Progressive Image Grid (PIG.js) is a responsive and lightweight JavaScript library that progressively and elegantly loads images as you scroll. It looks similar to the Google Photos album layout, which is the look I was interested in for my photo galleries. To get started, let’s see a test project using pure standard PIG without any modifications.

Click on the source code link at the top and clone the Github project, or just download the files for example-project-1. You should be able to open index.html locally in your browser and see a simple gallery with four images:

PIG Example 1

Easy, right? But wait …

These images aren’t clickable! PIG doesn’t have support for image modals or linking.

There are a lot of extra images! While there are only four images on the page, each full-size image requires four additional thumbnails in the /img directory — that’s 16 additional images I had to create for this simple page.

├── img
│   ├── 20
│   |   ├── vn.jpg
│   |   ├── vn2.jpg
│   |   ...
│   |
│   ├── 100
│   |   ├── vn.jpg
│   |   ├── vn2.jpg
│   |   ...
│   |
│   ├── 250
│   |   ├── vn.jpg
│   |   ├── vn2.jpg
│   |   ...
│   |
│   └── 500
│       ├── vn.jpg
│       ├── vn2.jpg
│       ...

There is math happening in here! The JavaScript contains an aspect ratio for each image in order for PIG to work its magic. So, on top of creating 16 images, I had to divide height and width to get ratios.

Obviously, Dan has created a great tool for us to get started, but it doesn’t yet do the dishes or double on sax for us, so in the next steps we’ll fix it up and automate like crazy.

Extending PIG

Let’s move on to Example Project 2. Copy the files as before and open index.html.

PIGG Example 2

Well that’s underwheming: it looks exactly the same!

But a few things changed under the hood. First, images are clickable now. How’d we accomplish that? Cheating, of course: our friend Mark Rodgers has modified PIG to support the Swipebox library. Now images are clickable and open in fancy modals — go ahead, click on them!

How did we do that? Let’s take a look at what changed in the index.html source. First, we’ve added the Swipebox libraries, and we’ve modified the source for pig.js:

In this case, we’re using my version of pig.js as the source. It’s identical to Mark’s, except with a minor change to improve compatibility with WordPress (more on that later). This is the version we’ll be using for the remainder of the process. What else changed?

We also have some anchor text directives in the JavaScript.

So this gallery does what we want it to now! Let’s move on to automating things.


Now for the fun part: making a robot do all the math, image resizing, and directory setup so we don’t have to. Let’s even have it output a ready-to-use HTML file. This section assumes a basic understanding of running scripts, and a Mac or Unix/Linux system. This probably won’t work on Windows.

We’ll work with Example Project 3, which right now is just four images. Using, we’ll transform those four images into a gallery without any math or manual file creation. This automation script is the reason you’re here, and the first step in this process featuring any work I’ve actually done myself and not just copied from others. Let’s walk through configuration and setup.

Install Perl dependencies. This assumes you have CPAN setup locally or on the server where you’ll run this script.

If you get an error regarding libpng and/or ligjpeg, you may need to install those explicitly:

Open for configuration.

Decide where to serve pig.js from. It’s fine to serve my version from Github, but safer to upload it to your own server in case I change/break it in the future.

Where will images live on your server?

Do you want to automatically generate an index.html file when you create a gallery? Start with ‘yes’ for this tutorial. If you decide to use this script with WordPress, you’ll want to turn this off.

Save and test drive it. Be sure to use the full path to where you’ve saved Example Project 3.

You should see output like this:

-=> Checking source directory ...                           [ OK ]
-=> Setting up new gallery structure ...                    [ OK ]
-=> Generating new images ...
    ✔ 20/vn.jpg
    ✔ 100/vn.jpg
    ✔ 250/vn.jpg
    ✔ 500/vn.jpg
    ✔ 20/vn4.jpg
    ✔ 100/vn4.jpg
    ✔ 250/vn4.jpg
    ✔ 500/vn4.jpg
    ✔ 20/vn3.jpg
    ✔ 100/vn3.jpg
    ✔ 250/vn3.jpg
    ✔ 500/vn3.jpg
    ✔ 20/vn2.jpg
    ✔ 100/vn2.jpg
    ✔ 250/vn2.jpg
    ✔ 500/vn2.jpg
                                                            [ OK ]
-=> Creating image manifest ...                             [ OK ]
-=> Writing index.html file ...                             [ OK ]


Upload example-project-3 to

You now have a full gallery project ready to use. If you upload it to, you can browse to to view your new gallery!


You don’t want to upload a plain HTML file to serve your gallery on WordPress, so let’s turn now to pigg.php, a WordPress plugin file.

First, a note about image storage. I don’t like how WordPress organizes image uploads, so I’m storing my gallery data directly on my server. Instead of this garbage that has a bunch of extra files I’ll never use:

├── /uploads/
   ├── 2018/
     ├── 04/
     ├── image1-1024x912.jpg
     ├── image1-300x267.jpg-
     ├── image1-768x684.jpg
     ├── image1-150x150.jpg
     ├── image1-600x450.jpg
     ├── image1.jpg
     ├── . . .

How about this instead?

├── /galleries/
   ├── china-2014/
     ├── image1.jpg
     ├── image2.jpg
     ├── . . .

Better, right? OK, now let’s configure a WordPress plugin that will be compatible with this straightforward image hierarchy.

Shortcode summary. The plugin — which we’re going to add manually because it’s fun and gives you full control over everything that’s happening — will let you create a gallery with this simple shortcode:

[pig gallery="gallery-name" images="image1.jpg/1.33,image2.jpg/1.24 . . ."]

Configure pigg.php. Once again, we need to tell the robot where pig.js is, and where images will live on the server:

Save the file. You’re ready to install it on your server now.

Manual plugin installation. Locate your WordPress plugins folder on your web server or using your FTP client. It should be in wp-content:

[jm@remote-webserver wp-content]$ ls
index.php  plugins  themes  upgrade  uploads

Create a new directory inside plugins called pigg:

Place pigg.php in the new directory. Use FTP or, if you’re logged in to your server:

Verify the plugin is installed by navigating to your WordPress dashboard > Plugins:

Update configuration. Back on your local machine, let’s change some config values in the Perl script to tell it we’re using WordPress now.

Delete everything inside the example-project-3 folder except for the four images.

Re-run with the new configuration. Same command as before:

Now examine the bottom of the command output. We generated our image tree again, but now instead of an HTML file, we have a WordPress shortcode:

. . .

Upload example-project-3 to

WordPress shortcode for this gallery:

[pig gallery="example-project-3" images="vn.jpg/1.3300,vn4.jpg/1.3300,vn2.jpg/1.6300,vn3.jpg/1.3300"]

Upload your files and use the shortcode in a post. Place the whole directory, example-project-3, on your server where designated. Then, create a new WordPress post and include the shortcode provided. That’s it! You should now have a fully-functional gallery on WordPress.

1 Comment » for DIY Masonry-Style Image Gallery
  1. brando says:

    Hi, sorry for emailing about such an old project of yours but I don’t know what I’m doing and I was hoping you’d be able to help. I recently bought a NAS and want to use your pigg gallery to create a sort of “mood board” that I’ll host internally. The gallery folder has a few subfolders and thousands of images in it. Following all your steps I keep getting hung up at the automation layer. Mainly because I’m not familiar with cpan/perl. The NAS has a perl package I installed but I’m not seeing anything for cpan, and I’m not familiar with the relationship between the two.

    Do you have any suggestions how to proceed, or possibly a better way of presenting all my pics?

Leave a Reply

Your email address will not be published. Required fields are marked *


This site uses Akismet to reduce spam. Learn how your comment data is processed.