Stimulus Image Grid
A Stimulus controller for beautiful image grids
Tiny at <100 LOC
- Simple: with only three optional parameters, this is a drop-in, code-free solution
- Unstyled: Completely free of CSS opinions
- Responsive: Scales to whatever bounding container you give it
- Backend Agnostic: 100% client-side
- Performant AF: uses the ResizeObserver so there's zero screen flicker
- Turbolinks: compatible with Turbolinks by design
- MIT Licensed: free for personal and commercial use
Built for StimulusJS
This Stimulus controller allows you to make any configurations for the image grid directly with data attributes in your HTML. Once registered in your Stimulus application, you can use it anywhere you like.
Here is a simple example:
Yes, that's really it.
Credit where credit is due
I don't know who wrote the original image-grid.js library. It shipped with a bunch of premium Bootstrap themes, but it relied on jQuery. While stimulus-image-grid is an improvement on the original in several significant ways, the actual meat and potatoes of the algorithm is 100% adapted from the code of a stranger. If you know who wrote image-grid.js, please let me know!
Note: stimulus-image-grid requires StimulusJS v2.0+
If you are reading this in the past (Stimulus 2 isn't out yet) you can change your
stimulus package in
package.json to point to this commit.
Add image-grid to your main JS entry point or Stimulus controllers root folder:
const application = Applicationstartconst context = requireapplication// Manually register ImageGrid as a Stimulus controllerapplication
For the image grid to work properly, it needs the raw image dimensions. If you know the dimensions at render time, set the
data-height attributes. Otherwise, the library will calculate the size when it loads. This is slower and could cause a flicker, but it will only happen once - even across Turbolinks visits.
The library tries really hard to not be opinionated about HTML structure. The basic idea is that every child of the container element that has the image-grid controller declared upon it will have [zero or one] image(s), somewhere in its DOM hierarchy. So for example, you could have a scenario where images are wrapped in DIV tags and it will find [zero or one] image(s) in the hierarchy:
This library is fully responsive in that it will automatically re-flow the images to the ideal layout in real-time as the container it lives in changes size. If you're using a CSS library such as Bootstrap, this is usually managed with the responsive breakpoint classes.
There are only three configurable properties, all of which are set on the DOM element using data attributes:
Padding is applied to the bottom of each image as well as the right edge of each image that isn't the right-most image of its row. Target height is applied to the row and you can tweak this value to suit the look of your application.
Obtaining a reference to the Stimulus controller instance
When you place an image-grid controller on a DOM element, it hangs a variable on the element called
imageGrid which allows you to access the internal state of the controller.
The only method you should ever call directly is
processImages(), which shouldn't be necessary but I'm not a fucking oracle so I've got your back. Here's an example of forcing a grid re-flow on an element with the id
Bug reports and pull requests are welcome.
This package is available as open source under the terms of the MIT License.