Espy's

Gallery Grid!

This is a resource designed for the indie web to easily display a gallery! It is designed to be both simple to use and fully customizable, with or without javascript knowledge!

Features

How to Install

Select a theme to get started, then hit download!

Theme:
Live Preview

Once downloaded, extract the .zip file.

It should contain two files named gallery-grid.js and gallery-grid.css. Put them anywhere on your site.

At the top of gallery-grid.js, there will be a variable called stylePath. Set that to the path of where gallery-grid.css is on your site.

How to Use

  1. On any page that you want to use the gallery grid, add the following to the bottom of the body, or anywhere that is below where you are going to add the grid. <script src="/gallery-grid.js"></script>

    Note: Make sure to replace the source with the path to where you host the file on your site!

  2. Add <gallery-grid></gallery-grid> where you want the grid to be.

  3. Fill it with images!

    <gallery-grid>
       <img src="/image-1.png" />
      <img src="/image-2.jpg" />
      <img src="/image-3.gif" />
    </gallery-grid>

If all you need is a simple grid, you can stop right here!

Changing grid cell sizes

By default, the grid will have fixed cell sizes of 300x300.
You can adjust the width and height of the cells like the example below:

<gallery-grid cellwidth="400" cellheight="200">
   <img src="/image-1.png" />
  <img src="/image-2.jpg" />
  <img src="/image-3.gif" />
</gallery-grid>
Creating a justified grid

If you'd like to create a justified grid, you'll want to define a 'max row height', like the example below: <gallery-grid maxrowheight="800">
   <img src="/image-1.png" />
  <img src="/image-2.jpg" />
  <img src="/image-3.gif" />
</gallery-grid>

Adding thumbnails <gallery-grid>
   <img thumb="/thumb-1.png" src="/image-1.png" />
  <img thumb="/thumb-2.jpg" src="/image-2.jpg" />
  <img thumb="/thumb-3.gif" src="/image-3.gif" />
</gallery-grid>
Adding titles/descriptions/tags <gallery-grid>
   <img title="My Title" src="/image-1.png" />
  <img desc="This image has a description!" src="/image-2.jpg" />
  <img tags="tag1,tag2,tag3" src="/image-3.gif" />
</gallery-grid>

(Tags should be seperated by commas, with no spaces in between!)

Pagination

By default, there is no limit to the amount of images shown at once. To enable pagination, define a "max per page", like shown in the example below:

<gallery-grid maxperpage="10">
   <img src="/image-1.png" />
  <img src="/image-2.jpg" />
  <img src="/image-3.gif" />
</gallery-grid>
Sorts and filters

To enable sorts in the gallery, add sort="default" or sort="alphabetical" to the gallery grid.

The default sort is based on the order you placed the images in the gallery, while the alphabetical sort is based on the titles of images in the gallery.

To enable filters in the gallery, add filter="tags" to the gallery grid.

The gallery will automatically add filter options based on the tags of the images.

Tags automatically show up in the lightbox also. To hide them, add the hide="tags" attribute to the gallery grid.

Here's an example of filters and sorts used together.

<gallery-grid filters="tags" sort="default">
   <img title="Alien" tags="illustration,2025" src="/image-1.png" />
  <img title="Beetle" tags="photography" src="/image-2.jpg" />
  <img title="Flamingo" tags="animal,bird,photography" src="/image-3.jpg" />
</gallery-grid>

For more advanced usage, check out additional documentation here.

QNA

Can I edit the code?

Absolutely, I encourage it! I intend for the code to work as a base one can build off on. My only ask is that you do not remove the credit in the header comments of the code.

Does this work with static site generators?

If it can generate image elements inside of a gallery grid element, it should work.

Why did you make this?

This is the code I made to use for the gallery on my site. I know that there are at least 2 people out there that were interested in borrowing the code, so I decided to just make a whole resource outta it so they and anyone else can use it.

Most notable to me is the ability to generate justified grids. I've seen it on some modern sites, and I tried my hand at coding my own implementation of it for neocities. It took me a while to get the formula down. ^^;

I hope it can serve you well!

Do I need to give credit?

There is already credit built into the code. As long as that isn't removed, I don't need any other credit.

If you would like to support me in another way, you can link my button. Don't feel obligated, it's totally optional!


Troubleshooting & Contact

The console should provide error messages, which should help with debugging issues.
You can also look at the documentation for help.

For additional help/questions/comments: Email, comment on my blog post, or DM me anywhere.
For bugs: GitHub

Please note that I cannot guarantee a response or bug fixes in a timely manner, if at all, as these projects are primarily a hobby of mine. Regardless, I intend for all of the resources and tools I create to remain free forever.

Update Log

v1.1.1 (02-22-2026)

  • Fix page navigation not working properly when sources change
  • Fix using addAll grid function not refreshing grid automatically for justified grids

v1.1.0 (02-20-2026)

  • Replace hidetags attribute with a general hide attribute which can be used to hide tags, titles, and descriptions in the lightbox
  • Add some styling to the lightbox loading element for the themes
  • Rename GalleryHandler to Gallery
  • Unload previous image in lightbox when viewing next image
  • Fix sorting for certain browsers (eg. Edge, Brave)
  • Fix ascending sort not sorting properly
  • Fix gaps between image and border in lightbox (visible with larger border widths)

v1.0.0 (02-15-2026)

  • Initial release!