# Upcoming topic-list changes - how to prepare themes and plugins

**URL:** https://meta.discourse.org/t/upcoming-topic-list-changes-how-to-prepare-themes-and-plugins/343404
**Category:** Development
**Tags:** dev-news
**Created:** [December 19, 2024, 5:43pm UTC](https://meta.discourse.org/t/upcoming-topic-list-changes-how-to-prepare-themes-and-plugins/343404 "2024-12-19T17:43:05Z")
**Posts on this page:** 1
**Showing post:** 1

<div class="post-metadata">

### Author: ![david](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/david/32/157490_2.png) [@david](https://meta.discourse.org/u/david)
#### Post date: [December 19, 2024, 5:43pm UTC](https://meta.discourse.org/t/upcoming-topic-list-changes-how-to-prepare-themes-and-plugins/343404/1 "2024-12-19T17:43:05Z")

</div>

As part of our ongoing quest to standardise the rendering systems across Discourse’s codebase, we’re replacing the implementation of the topic-list.

Previously, this used a ‘raw handlebars’ (`.hbr`) approach, and could be customized via template overrides and raw-plugin-outlets. The new implementation of the topic-list uses modern Glimmer components, and has been built from the ground-up to to be customizable in sustainable ways.

The new implementation is now available behind the `glimmer_topic_list_mode` setting.

- `disabled`: use the legacy “raw handlebars” topic-list
- `auto`: will detect the compatibility of your current plugins and themes. If any are incompatible, it will use the legacy system; otherwise it will use the new implementation.
- `enabled`: will use the new topic-list implementation. If you have any incompatible plugins or themes, your site may be broken.

We’ve already updated most of our official themes and plugins to be compatible with the new menu. But, if you run any third-party plugins, themes, or theme components which customize the topic list, upgrading them will be required.

> Warnings will be printed in the browser console identifying the source of the incompatibility.

## ⏲ Roll-out Timeline

_These are rough estimates subject to change_

## Q4 2024:

- ✅ core implementation finished
- ✅ updating official themes/plugins (in progress)
- ✅ enabled on Meta
- ✅ published upgrade advice

## Q1 2025:

- ✅ updating official themes/plugins

- ✅ `glimmer_topic_list_mode` default to `auto`; console deprecation messages enabled

- ✅ deprecations will trigger an admin warning banner for any remaining issues

- third-party plugins and themes should be updated

- ✅ **1st March** - enable the new topic-list for all sites. The default for the site setting will be switched to `enabled`, but it will still be possible to switch back to ‘disabled’

## Q2 2025

- ✅ after **1st April** - final removal of the legacy mode & associated code

## 👀 What does it mean for me?

If your plugin or theme has any ‘raw handlebars’ files (named `.hbr` or `.raw.hbs`) then those will need to be updated for compatibility with the new version. Regular `.hbs` files for Ember components/routes are unaffected by this change.

Upgrades will also be required if you use modifyClass on `component:topic-list` or `component:topic-list-item`.

If your site has any of these incompatible customizations, warning messages will be printed to the browser developer console, including information about which theme/plugin is the cause.

## What are the replacements?

Some of the old raw-plugin-outlets have been converted to [regular Plugin Outlets](https://meta.discourse.org/t/using-plugin-outlet-connectors-from-a-theme-or-plugin/32727). Those can be updated in a 1:1 fashion.

More advanced customizations will need to be assessed on a case-by-case basis. The new topic-list has a number of new APIs for easy and robust customization. Find out more here:

> [@Customizing the topic list](https://meta.discourse.org/t/customizing-the-topic-list/350411):
>
> The topic-list is one of the most-used and most-customized user-interfaces in Discourse. There are many different tools available to theme and plugin developers to achieve this customization, each with their own advantages, disadvantages and maintenance considerations. CSS-based Customization The safest and most common customization method is CSS. As with any other Discourse customization: the more complex your changes, the more maintenance is likely to be required in your theme or plugin. Gen…

Here are some examples:

- `discourse-assign` introduces a [new column](https://github.com/discourse/discourse-assign/blob/471cfdff63a400cda5318508b912980992218d9f/assets/javascripts/discourse/initializers/assignment-list-actions.gjs#L19-L31) to a specific topic-list

- `discourse-calendar` uses one of the [new plugin outlets to display the event date badge](https://github.com/discourse/discourse-calendar/commit/8bdd580e2ec88dcb2aa9b14c3f1df4577435b9ea)

- `discourse-solved` [uses a new valueTransformer](https://github.com/discourse/discourse-solved/commit/024d9dd70f5a2510fd1744aa3108fda44cf0201e) to replace the previous modifyClass

## 🆘 What about other customizations?

If your customization cannot be achieved using the new APIs we’ve introduced, please let us know by creating a new #Development topic to discuss.

## ✨ I am a plugin/theme author. How do I update a theme/plugin to support both old and new topic list during the transition?

The new plugin outlets are rendered in both the old and new implementations of the topic list. So: when you’ve implemented the new one, simply delete the old raw-plugin-outlet connector.

For DAG-based customizations which replace template-overrides or non-modernized outlets, you will need to maintain both implementations during the transition period.

Once your theme/plugin supports both old and new implementations, you can add this magic comment at the top of all your `.hbr` files:

```plaintext
{{!-- has-modern-replacement --}}

```

This will silence the deprecation messages, and allow the new implementation to be used when in “auto” mode.

---

_[View the full topic](https://meta.discourse.org/t/upcoming-topic-list-changes-how-to-prepare-themes-and-plugins/343404)._