Topic List Previews

GitHub-Mark-32px Repository: get the code here

sandbox Examples: check out the list further down.

:heart: Donate: support it here

:man_technologist: Maintainers: @merefield and @angus


Topic List Previews allows you to:

  • Add images, excerpts, buttons and topic stats to topic list items; and

  • Change the layout and style of topic list items

  • Add ‘Featured’ topics above topic lists and topics.

These settings can be applied to all or selected topic lists on a site-wide or category-specific basis.

This flexible feature-set allows you create a variety of different topic list styles, including

Basic Style

Relevant settings
  • topic list thumbnail
  • topic list excerpt
  • topic list action

Pinterest (Masonry) Style aka 'tiles’

Relevant settings
  • topic list tiles
  • topic list thumbnail
  • topic list excerpt
  • topic list action
  • topic list thumbnail width
  • topic list thumbnail height

Featured Topics

Relevant settings
  • topic list featured images tag
  • topic list featured images count
  • topic list featured width
  • topic list featured height
  • topic list featured title
  • topic list featured excerpt
  • topic list featured order

The main and Discovery settings are in Settings -> Plugins. The Category equivalent are in each Category’s Settings.

Examples in the Wild :seedling:

How to use

Install the plugin in the usual way by adding its URL to app.yml.

As usual, all settings are in Admin -> Settings -> Plugins.

The most critical settings are the following. They work in a slightly unintuitive way in that you add the view you want the feature to appear in, to the feature, like so:

So, if you want, for example, thumbnails to appear on Latest, you add ‘latest’ to the thumbnail setting, etc.

Make sure, when changing the population of the multi-select you click the tick icon to commit the change or it won’t save!

You can choose to have Tiles layout, or just a normal line-by-line view by adding or removing views to the tiles option.

Add excerpts, thumbnails etc. to your taste.

You can have featured images at top and you can size them.

You can set the thumbnail size for non-tiles views and for tiles you can add a featured tag to a topic and it will be shown very very big.

You can choose to have Discourse use lower resolution thumbnails or force the client browsers to fetch the full images for each of the previews (lots of bandwidth but prettier).

Support :heart:

You can donate to support the development of this plugin. Select “Topic list Previews” as the “Cause”. If you have an account on my sandbox, you will appear as a project “Backer” in the Topic List Previews category description on my sandbox. All donations are split equally between current maintainers.

Contributors :raised_hands:

Many folks have contributed to the development of this plugin through both feedback and direct development work. In particular:

How to safely update when using our plugins:

Pavilion’s update schedule

Topic List Previews is one of the Pavilion family of open source plugins.

Going forward, Pavilion will focus on ensuring compatibility of a core set of its plugins with Discourse Core tests-passed branch during the first 5 days of every month only.

Any bugs which arise because of an incompatibility will be addressed asap during this ‘supported period’, preferably by the 7th day. Low severity or Beta feature bugs may not be addressed by this date, but obvious things which are ‘breaking’ a forum should be resolved.

This new policy will come into effect 1st May 2020

Why we are introducing this policy

We have no control over changes in Discourse Core. That is how it should be. However, as our plugins have grown and become more sophisticated, it is getting more and more burdensome to guarantee they are working with every update of Discourse Core. It’s becoming untenable to ensure immediate compatibility is maintained.

To give our developers breathing room so they can attend to other priorities in addition to plugin support we will no longer be guaranteeing compatibility with Discourse core every day of the month.

This policy should also help you achieve more stability and give you more certainty over when you can more safely update.

How to perform your update

Aim to update your Production Discourse instance in the first 5 days of every month. Notify us on the relevant Plugin Topic on Meta of any issues you encounter. You will get more focussed support from the Pavilion team on any issues with their plugins during this period.

You update your Production server outside of the first 5 days of the month at your own risk. If you do so and something breaks related to one of our plugins, we urge you to report it and in addition, and if appropriate, uninstall our plugin until it is resolved. Unfortunately we may not get around to fixing it until the next supported period at the beginning of the following month.

For even greater safety

Consider testing your update on your own staging server built from a back-up of your production site. You can switch this server off for the rest of the month so you don’t get charged for up-time. Use this opportunity to test out all basic functionality to identify any issues with plugins. Report all critical and high issues asap on the relevant plugin topic.

This is especially important if your site is large, popular and/or part of a business.

Using a staging site may allow you to have more discretion over when you update, but be aware of the relative lack of support in the latter part of the month.

Thanks for your understanding!

(we will be shortly adding this policy note to all our core plugins).

What plugins do you recommend?
Topic list custom view support
Display images with topics list
2018: The Year in Review
Discourse as Homepage/Main
Move tag to a column
News Plugin :newspaper:
Incomplete topic titles beginning with a number can have odd behavior
Sam's personal "minimal" topic list design
Category-specific message or pinned topic
Our solution for blurring NSFW content
How do you add the Category column?
Profile, Feature and Explorer grid galleries and friend option
Facebook-like Feed?
Changing sidekiq job urgency
Latest view broken on tablet
Is there a media library for looking at all uploaded Images and their URL?
Forum with Pins/thumbnails instead along with topic title
Set the image used for social network sharing?
Set the image used for social network sharing?
Events Plugin :calendar:
Broken images move to tombstone
Need Help imitating a Theme
Creating a "Featured Categories" homepage banner
In-post links to topics - no longer update to the initial posts title
Discourse Setup for KDE
Retort - a reaction-style plugin for Discourse
Migrating from FB Groups to Discourse - help with features/functions
Auto-quoting early posts and why its so needed for big communities
How to make a discourse forum look like
How do I show a topic description in category view?
How to move the category into a column in 'Latest'
Category descriptions display hyperlinks, but About category topic previews do not
The topic list doesn't need a category column
[PAID] Discourse developer/designer to redesign homepage (tight deadline!)
How can I save a topic for offline access/archive purpose?
Replacing Slack by Discourse
CMS for Discourse
Topic content previews
Image miniatures
Sam's personal "minimal" topic list design
How would I able to list topics as boxes
Discourse as a simple personal blog engine
2019: The Year in Review
How to how topic description on top page
Alter placement of currently selected Top Menu item
Unable to replace topic-list-item.raw.hbs / topic-list-item.hbr on mobile
Problems with thumbnails from Soundcloud and YouTube oneboxes
Possible to create a news site with pics and videos
Visual Video Forum
Topic List Thumbnails Theme Component
MD Topic List component
Deals type website UX
Featured Tiles Theme Component

Finally (phew!), big PR merge this morning! (a nice round ‘#50’ … how appropriate!):

Tiles Improvements:

  • Makes standard a 3/2/1 column arrangement which responds to width

  • New settings for gutter @lmy and transition time @bartv (set transition time to zero for no animation, this is forced on mobile)

  • AND … support for mobile!

Known issues

  • This version forces a 3/2/1 column appearance depending on view width. It may clash with your custom CSS. Suggest removing those elements in your local theme which change column number behaviour. This was done to avoid less experienced users having to mess with the CSS to get a more responsive view and to fix the logged out view. btw, Chrome doesn’t seem to allow the browser width to get small enough to dive into 1 column mode (Firefox is fine).

  • I’m not happy with the new post badges positions at the moment and intend to refine that at some stage.

  • On mobile: currently as the new tiles are rendered before being put into place by Masonry, the view can appear to momentarily ‘glitch’. This is most likely down to how much ‘grunt’ a mobile browser has versus desktop and how much processing power it is given to maximise battery life … i’m going to take a look at potential for some tricks to hide this.

  • On mobile: individual Categories are not yet supported.

  • Tiles view is always best with hot-linking on, however this setting temporarily prevents featured images being updated. If you have a new featured image, briefly switch this off, rebuild the HTML of the affected post and once complete, reactivate hot-linking.

Let me know if you find any more.

And there’s more …

Box shadows, highlighting with hover and ‘button click’ behaviour of a tile are not standard but left to the Theme designer. For your interest, here’s my local CSS to enhance the look of the tiles:

.grid-item {
    box-shadow: 3px 3px 3px 3px #888888;

.grid-item:hover {
    background-color: darken($secondary, 3%);
    lighten: ($primary, 70%);

.grid-item:active {
    -webkit-transform: translateY(+2px);
    -ms-transform: translateY(+2px);
    transform: translateY(+2px);
    -webkit-transform: translateX(+2px);
    -ms-transform: translateX(+2px);
    transform: translateX(+2px);
    box-shadow: 1px 1px 1px 1px #888888;

.topic-details .topic-excerpt {
    max-height: 300px;

NB Social view and Tiles view will be merged!

My next job is to simplify the plugin slightly. Now we have a mobile version of Tiles that can support a single column view, the next step is to simplify things by removing ‘social’ view in place of ‘tiles’. I anticipate this may take a couple of weeks. Feel free to let me know if you have any concerns.


Please note there’s been a PR merge and a new version of TLP is available.

This is mainly a maintenance release which does a three main things:

  • Removes ‘Social’ view. Now there’s a responsive ‘Tiles’ view which can be reduced to one column by simply reducing the available width and which also leverages the same meta-data. ‘Tiles’ also now works on mobile. There was not much point maintaining both.
  • Removes a load of jQuery hacking that was used to switch the Social to Tiles format, so the code is now ‘cleaner’ and slightly easier to maintain.
  • Updates the CSS to avoid collision with core naming but temporarily this may break your theme, apologies:
    • grid becomes tiles-grid
    • grid-item now becomes tiles-grid-item
    • grid-sizer now becomes tiles-grid-sizer
    • gutter-sizer now becomes tiles-gutter-sizer
    • I think you get the idea :wink:

The PR also sneaked in a tweak to post badges moving them next to the title so look much better and more logical

Thanks to @angus for his time spent checking the PR

Next up, a feature PR!


Yay, new feature: “Featured Tiles”!

Pleased to announce a new feature for tiles view which takes advantage of the existing ‘featured’ system (and masonry).

If you enable this setting, all tiles tagged with the selected featured tags will appear up to four times as big taking up two columns, instead of one. It is enabled by default, so if you don’t like it, feel free to turn it off or simply remove your chosen featured tags from the tiles you wish to keep a normal size.


Remember, that it will take the specific tags from this setting:


You can list more than one tag in this setting and it will feature the tile if the Topic has at least one of these tags. Simples!

Remember you need to have enabled ‘tiles’ for that discovery list:


Please be aware that masonry does its best to lay things out, but sometimes small gaps will be necessary. The feature is currently only enabled on desktop/tablet.


Donations for the ongoing support of this plugin are very much appreciated (Select Topic List Previews). If you have an account on Angus’ site you automatically get displayed as a backer. Thanks for your consideration.

Known issues and enhancement requests are up-to-date on the repo.

@robotnjik, @shiva, @angus


A new tiles ‘renderer’

Guys, I’ve not been 100% happy with the use of masonry for the tiling system in tiles view. There’s various glitches, challenges with media queries, an inability to theme how many columns you want (but see this post) and A LOT of javascript involved, so whilst I was looking for a way of accommodating sidebars out-of-the-box, I decided to try out a technique I read about in a blog post a while back:

I’ve now coded this into an experimental version of this plugin. I have it running on two sites at the moment and it seems fairly stable.

If you’d like to try out the new renderer and let me know what you think, change your app.yml and replace the existing TLP clone command with this:

git clone -b "replace_masonry_with_CSS_grid"

Admin control over number of columns

This was always a challenge with Masonry and I never quite cracked it so you could Theme customisations locally in a way that allowed a default behaviour out-of-the-box for novices, that more expert admins could override.

This version will render three columns out of the box, reduced to 2 columns if you have a reasonably sized side-bar.

But this version gives you more control:

If you add this CSS in your Theme, it will render only one with a sidebar:

.tiles-grid-item {
   grid-column-end: span 2;

If you have no sidebar and want only one column you can experiment with increasing that span to 3.


Yay, new feature: Thumbnails that retain aspect ratio!

Pleased to announce a new feature (intended mainly for tiles view) which optionally allows you to render thumbnails that retain their original aspect ratio.

Who’s it for?

The feature is mainly intended for those running TLP tiles on image heavy sites, especially those sites who’s users tend to upload large images to Topics, rather than one-box. Using thumbnails speeds up time-to-interactive and can considerably reduce network load. I’ve halved the time it takes to load one of my sites with this.


Up until today you had to hotlink all images to retain aspect ratio in TLP. This new feature will allow you to render and store un-cropped, undistorted thumbnails locally and avoid hotlinking to the originals and may provide a significant performance benefit. It should be particularly useful for image heavy sites. It should make Tiles view more viable for more sites now.

How to use it

With the update you will now have the option to pick just the thumbnail width resolution and height will be calculated for you if you set it to zero, thereby maintaining the aspect ratio. If you set both Width and Height to non-zero numbers, nothing changes to prior behaviour.

Like so:

This will create two thumbnails, one with width 200 for standard res displays and one with width 400 for retina displays. The height will depend on this and the original image’s width/height ratio.

Be sure to switch this off:

(Finally! :slight_smile: :sweat_smile:)

Now for the rebake

For the change to take effect for existing posts you need to ‘rebake’ them. You can rebake posts individually by selecting “Rebuild HTML” from the admin wrench control menu below the first post:


OR: you can rebake all or a subset of your posts using the console.

Thanks to @davidkingham for testing this. He’ll forgive me if I quote him:

“I’ve been playing around with different thumbnail widths and think 400 will be the sweet spot, 200 looks terrible on a phone. 600 would cover all screen sizes but the file size is still quite large.”. Given David’s (rather beautiful) photography forum is very image heavy indeed, this is pertinent advice.


NB This will work on non-tiles views but I’m not sure the layout effect is desirable.

Donations for the ongoing support of this plugin are very much appreciated (Select Topic List Previews). If you have an account on Angus’ site you automatically get displayed as a backer. Thanks for your consideration.

Known issues and enhancement requests are up-to-date on the repo.

@angus @thwright


Is it possible for the generated thumbnails to use the s3_cdn_url setting if enabled?

1 Like


Thanks for good work

Can I set so that only users from a given group or above trust 2 lvl can use this function?
maybe just one line in the code is enough?

1 Like

No you can’t differentiate between TLs of users and no such distinction is planned or afaia been requested before.

However you can enable it on specific Category routes that could be restricted by TL.

Is there any chance we could get support for the ‘unseen’ view? Simple Unread List Plugin (discourse-simple-unread)

1 Like

@merefield the single_tiles_column branch isn’t working anymore - is there a possible workaround to have a single column tile view?

1 Like

Hi David, that’s possible but requires an enhancement.

For now I’ve raised an enhancement request.

It’s a perfectly reasonable feature request that might be pushed up in priority by sponsorship.


As discussed offline, it doesn’t look like TLP is a source of the issue and it’s likely to be another plugin

That said, I’ve updated that branch (single_tiles_column) with the latest changes in master and checked that it runs briefly. Enjoy.

1 Like

Looks like this commit in core upset the formatting for tiles in TLP:

Specifically, this property was removed (together with the wiring to make it control the header visibility):

skipHeader: function() { return; }.property(),

@maja is there any way to restore this property and wiring as it was otherwise I may have to start overriding an additional .hbs file (which is always risky!), specifically:

  • assets/javascripts/discourse/templates/components/topic-list.hbs

and this change kind of removes some general plugin flexibility to control the header visibility in any case?

In the meantime, please do not upgrade if you use ‘tiles’ and tests-passed

Fix deployed


That should make it:


oh thanks a lot Joffrey! I didn’t want to impose on the core agenda, but this is very helpful, thank you!

with that change I’ve removed the added template, restoring things back to how they were:


Hi @merefield,

great plugin, thanks for your work! How complicated would it be to bring the featured images to mobile? Is this already implemented, but just not styled yet? Or is it a more complex issue?



Its an existing enhancement request


Ah, cheers, perfect, then I would second that! :wink:

1 Like

Mobile gets some love today.

Fixes for:

  • Suggested list & Message list - cleaned up clash of timestamp and poster
  • Excerpts no longer appear on Message List in inbox.