Introducing image grids in posts

If you have many images in a Discourse post, you can now have them automatically arranged into a nice grid. All you need to do is wrap them in [grid] ... [/grid] tags, and the images will be neatly arranged. This is a core feature as of this commit, enabled on all Discourse instances.

Here’s an example in action:

This feature is similar to a few theme components (Masonry Image Gallery, Tiles Image Gallery). The main difference is that the arrangement of images in the grid will align at both the top and the bottom of the element. A few additional technical notes:

  • on mobile, the grid defaults to 2 columns, on desktop to 3
  • if there are exactly 4 items in the grid, the images will be arranged into 2 columns
  • non-image elements can also be used (like videos), but the results won’t align perfectly
  • the items in the grid are arranged to ensure the column heights are as close to each other as possible, therefore, the order of the images isn’t always maintained

Enabling or disabling the grid can also be accomplished by clicking a small toggle icon next to the first image in a group of images in the composer preview:

Images used in this post are from


very cool. love this. thank you @pmusaraj :slight_smile:


We’re already using Masonry Image Gallery; is this new feature compatible, or will existing grids disappear?


Good question. This new core feature is not incompatible with the Masonry Image Gallery theme component, i.e. both can work at the same time.

If you want to migrate posts from the Masonry gallery approach to the new core approach, you need to run a script that updates the raw contents of posts from

<div data-masonry-gallery>





And then rebake those posts.


Nice! This is a big step up, making images look even nicer in Posts.

I presume this doesn’t impact what gets chosen as the primary image for thumb-nailing in any way?


Correct, it shouldn’t impact it. I believe the first image found in the post is chosen as the thumbnail (excluding avatars and emojis and such). Also, I can’t see a scenario where the first uploaded image isn’t the first image in the grid (the reordering can only happen for later images in the list).


I’ve got an import where the images are just URLs to a S3 bucket like:





But it just shows [grid] then the images and then [/grid].

I guess it works only after those URLs get downloaded and turned into regular images?


Hmm, yeah, in the composer this currently works with uploads only, too. (I.e. pasting a URL to an image and wrapping it in [grid] tags doesn’t work in the composer either.)


Cool. Good thing I didn’t add that code to the import script just yet. :slight_smile:


This is a great feature, thank you.

Will the grid work with published pages?

1 Like

Unfortunately, no, this doesn’t work with published pages. Similar Javascript-driven post features also don’t work with published pages (lightboxes, polls, table of contents).


Would you be able to provide instructions for this?

1 Like

Hi bart :wave:

This should work. Obviously, do a backup and carefully look for any unwanted results in the previous masonry posts… :slight_smile:

posts = Post.where('raw LIKE ?', '%<div data-masonry-gallery>%')

posts.each do |p|
    p.update!(raw: p.raw.gsub(/<div data-masonry-gallery>(.*?)<\/div>/m, '[grid]\1[/grid]'))

Thank you this is looks great :slightly_smiling_face:

I also use the Masonry Image Gallery component…

Screenshot 2023-06-22 at 10.38.14

With the auto enabled setting… This is not contain the <div data-masonry-gallery> in raw so the script won’t work I think. But in this case it isn’t conflict each other.

Is there any plan to make the grids automatic? If this happens I can simple rebake the posts and keeps the grid layout. Until then I think I can hide the grid button and use the theme component safely.


Does anyone in CDCK have influence with Chrome devs? CSS Masonry support for Grid?

Masonry should be a CSS thing already. It is one of the few layouts which allows you to respect different aspect ratios of collections of images (or indeed any item content) in a nice way.

It is so wasteful and pointless to have this running as javascript everywhere …

(and as you know it’s already possible on Firefox (behind a flag) and is in the Technical Preview for Safari now: "masonry" | Can I use... Support tables for HTML5, CSS3, etc)

btw, everyone, please :star: this issue:

:drum: CSS Masonry support now for Chrome and Edge! :drum:


Not that I know of.

I am excited about Safari supporting masonry, they have a better track record of moving features from draft → experimental → fully supported. Firefox masonry support has been behind a flag for 2+ years now. Safari support is probably going to be the main driver for Chrome to keep up.



Yes, but not without [grid] tags. Automatically converting images into a grid without tags would violate the CommonMark spec, we very much prefer to avoid that. (In my first internal draft of this feature, I did start with an automatic grid.)

Instead, what I have been thinking as the next step here is that we could automatically add the [grid] wrappers to uploads of multiple images, probably 3+ uploads. This would be especially useful for mobile uploads, adding tags manually on mobile is clunky and chances are that if you’re uploading 3+ images at once from your phone, they are photos and reasonable candidates for a grid layout.

We don’t have any plans yet for when we are going to add this, but it’s certainly something we’d like to do.


It should be possible though to generate the static html from the JavaScript and publish the “cooked” DOM to enable a number of useful features such as this grid and the TOC

1 Like

The cooked HTML alone is not enough. The grid, TOC and similar features also need the JS that interacts with the HTML to create that feature. And that JS lives in the Ember app, it can’t be easily extracted for the non-Ember published pages.


I just played around with this yesterday and was recommended to pass my feedback & thoughts here on this thread…

  • I like that it is “automagic” in that it sets a grid itself
  • It might be a nice added feature to order the images without needing to copy/paste images around in the list - maybe just adding in numbers to the beginning of each image?
  • I like that you can easily toggle the grid off in the preview, but to get it to be added back, you need to re-add the code, seems like an area for an improved experience to have the grid icon appear when you have added in more than one image to be able to toggle on/off as needed.
  • One final possible future feature would be the ability to pick a particular image to “highlight” or feature within the grid so that it appears larger than others or stands out in some way.

All in all, though, great new option to add multiple images without images taking over a post :slight_smile: