Topic List Thumbnails

[Discourse]

	Summary	Topic List Thumbnails allows you to show topic thumbnails in topic list views.
	Preview	Preview on Discourse Theme Creator (blog style) Preview on Discourse Theme Creator (grid) Preview on Discourse Theme Creator (list) Preview on Discourse Theme Creator (masonry) Preview on Discourse Theme Creator (minimal grid)
	Repository Link	https://github.com/discourse/discourse-topic-thumbnails
	New to Discourse Themes?	Beginner’s guide to using Discourse Themes

Install this theme component

As this is an official theme component maintained by the Discourse team, Support, Contribute > Bug, Contribute > UX, and Contribute > Feature requests can be made in the respective categories here on Meta, and tagged with the appropriate theme component tag. Click on a link below to get one started.

 Support  Bug  UX  Feature

Features

Optimized images are generated for the lists, and different resolutions are made available for high-dpi displays. Images are lazy-loaded as you scroll (where native browser support is available).

By default, Discourse will use the first image in the OP of the topic. If you would like to select a different image from the OP, add |thumbnail to the markdown. For example

![alttext|100x100](upload://aaa)
![alttext|100x100|thumbnail](upload://bbb) << this one will be the thumbnail

There are five modes, configurable per category or tag using the theme settings.

For example:

Grid mode:

Masonry mode:

And list mode:

Tips and Tricks

If you want Oneboxes in your posts to generate thumbnails, you will need to turn on this site setting: download_remote_images_to_local. You’ll also need to rebake the relevant posts.

Settings

Name	Description
default_thumbnail_mode	Which thumbnail display mode should be used by default
docs_thumbnail_mode	If the docs plugin is enabled, which thumbnail display mode should be used for docs topics
blog_style_categories	The blog-style view will be used in these categories. This style makes use of topic-excerpts if enabled via theme or theme component
minimal_grid_categories	The minimal grid view will be used in these categories
grid_categories	The grid view will be used in these categories
masonry_categories	The masonry view will be used in these categories
list_categories	The list view will be used in these categories
blog_style_tags
minimal_grid_tags	The minimal grid view will be used for these tags
grid_tags	The grid view will be used for these tags
masonry_tags	The masonry view will be used for these tags
list_tags	The list view will be used for these tags
suggested_topics_mode	Which thumbnail display mode should be used for suggested topics? If blank, will follow the ‘enable outside topic lists’ setting.
enable_outside_topic_lists	Enable thumbnails on non-topic-list pages (e.g. user activity, personal messages, suggested topics)
placeholder_icon	Icon to display on topics without thumbnail images
mobile_thumbnails	Enable thumbnails on mobile devices
list_thumbnail_size	Base size for thumbnails in the ‘list’ view

Hosted by us? Theme components are available to use on our Pro, Business, and Enterprise plans.

Last edited by @Moin 2026-05-19T07:03:58Z

Check document

Perform check on document: