Masonry Image Gallery

This theme component adds a responsive masonry-style image gallery with customizable ordering.

Desktop view:

Mobile view:

When clicking on an image it will open with the default lightbox viewer.

You add the gallery by clicking on the grid icon and then adding your images. It also works by first selecting the uploaded images and then clicking the icon.

:thinking: → So what do you mean with customizable ordering?

The images can be ordered horizontally (from left-to-right) or vertically. The horizontal order is ideally for images from magazines, comic books or similar. Also, when you press next in the lightbox view the correct image will show.

The images below illustrates the difference. The one to the right has horizontal ordering.


The default order is horizontal, but can be changed in the settings. It’s also possible to change the order of a specific gallery by adding vertical/horizontal (v/h works as well) to the attribute in the composer like this <div data-masonry-gallery="vertical">.

:face_with_monocle: → This component looks a lot like Joe’s Tiles image gallery. Is this a clone or what?

I’ve been using Tiles for a while and like it a lot. So yeah, you could definitely say that it’s heavily influenced by that one :wink: . But a lot of stuff differ, so decided to share it. Below is a list of some of the things that are different.

  • No dependencies.
  • No jquery.
  • Horizontal ordering.
  • Small images won’t break the layout.
  • Correct preview when editing.
  • Possible to select multiple rows with line breaks when adding a gallery.
  • Using the API function decorateCookedElement instead of decorateCooked.

Suggestions and improvements are welcome!

:information_source: Small images will show up in the gallery, but a lightbox view will not be created. That’s the default Discourse behavior. It’s however possible to change what’s considered a small image by modifying the settings max image width and max image height. The default values are 690 px and 500 px, respectively.

:information_source: This component uses the API version 0.8.42. If you haven’t updated since May 2020, you need to do update in order to use it.


Awesome component. I have been looking for a tiles image gallery replacement for a while!

What are your thoughts on adding an auto-gallery option to apply it to all images? Basically, whenever there are 3 or more without any other elements between each other, the masonry gallery view is enabled automatically. (Tiles Image Gallery tried something there in their auto-tiles branch)



Yeah, I saw that branch. That’s a really interesting feature. Don’t know if the way it’s implemented in Tiles works on this component, or if some other code is needed. But will definitely look into it!


If you have Tiles installed on your site and want to switch to Masonry, you need to change the attribute of the gallery divs to data-masonry-gallery on all of your old gallery posts. That’s if you want your old gallery posts to still render correctly, but don’t want to have both components installed.

Thought I share how you could do that, since I made the switch on my own site. Maybe it can be of some help to someone.

The most obvious way would be to edit the posts manually. That works as long as you don’t have too many posts you need to change, though it could still be a pain to find every posts. But don’t worry, data explorer to the rescue! Run the following SQL and you’ll get exactly what you need.

SELECT user_id, topic_id, post_number
FROM posts p
WHERE raw ~~ '%data-theme-tiles%'

If there’s too many to edit manually, you could use rake to replace every string. To do that, you need to SSH into your sever and run:

cd /var/discourse
./launcher enter app
rake posts:remap["data-theme-tiles","data-masonry-gallery"]

You can read more about that solution on this post. Please note the warning from that post about the rake posts:remap command:

There are most likely also other ways to do it. For example, if you like to you could modify the components code so that it looks for both attributes.


Excellent work. Thank you.


This would be brilliant and much more user friendly! Are there any plans for this?


That feature is kind of finished. Have modified the code from Tiles, just need to do some more tests (with different scenarios/site modifications). Will try to find the time to do it soon, but should be added within a week. If I only had more time :slight_smile: .


Fantastic, thanks! We’re looking forward to it :slight_smile:


Thank you very much for creating a great TC. :smiling_face_with_three_hearts:

Now I can replace the problematic “Tiles Image Gallery” TC completely. :tada: :confetti_ball: :confetti_ball: :confetti_ball:

Just curious, do you have plan to create a similar TC to replace " Slick Image Gallery" as well ? :kissing_heart:

The “Slick Image Gallery” have all the problems similar to “Tiles Image Gallery”, such as small image break the layout and preview can’t slow gallery correctly, etc.


I don’t have any plans to do that at this time. Maybe later if I have the time… If it’s a small fix, I could maybe do a pull request.

1 Like

Hey, I was wondering if you had time to work on the ‘automatic mode’?

I just updated the component with the auto gallery feature. After you update, you can enable it in the settings.

It’s possible to specify categories and also set the minimum number of images required (without any other element or empty line between them) for a gallery to be automatically created.


Amazing, I’ll go try that out!

1 Like

Let me know if you find anything strange!

Works like a charm! :+1:

1 Like

Just wanted to say this works perfectly out of the box, I’ve been having trouble with the other two components mentioned so this is fantastic. :partying_face:


That’s great to hear!

I also added the div attribute grid (or g) for a grid type of style (despite the name of the component :grinning_face_with_smiling_eyes:) that sets every row to a fixed height (as the rows highest image). Could be nice if you have images with almost the same height.


We are currently testing 2.8 stable. The auto enabled categories feature doesn’t trigger when a specific category is defined. We tried to add category slug and category ID. When auto enabled categories is left empty, it works.

Hmm that’s strange. It works on my 2.9.0.beta1 and that’s pretty much the same as 2.8 stable. It’s the category name that should be added. But I will see if I can find anything.

Thanks for the info!


Never mind, forgot to set checkbox :man_facepalming: