Modernizing our Topic List HTML - preparing themes, components and plugins

Our topic list markup has been largely unchanged since the Discourse project began. To take advantage of the latest web technologies, we’re planning some changes which will improve the theming potential of Topic Lists.

To make the transition as smooth as possible, we’ll be making these changes step-by-step, and hope the migration to be completed some time in Q1 2022.

:white_check_mark: Step 1: Updating CSS selectors

We’ve recently added .topic-list-header , .topic-list-body and .topic-list-data classes to begin the transition.

  • thead now has a class of topic-list-header
  • tbody now has a class of… you guessed it! topic-list-body
  • td elements now also have topic-list-data classes attached to them as well

For the vast majority of sites, this change will be totally seamless. However, complex themes/plugins which override our core templates will need some updates.

Updating existing template overrides

If possible, we recommend that you remove template overrides and use a combination of CSS and plugin outlets for customization. If removing the overrides isn’t an option, then you will need to manually update your overrides to include the new classes.

The templates that have had classes added to them are:

:black_square_button: Step 2: Changing element types

The next step in this process will be to convert the existing table elements, into more suitable elements.

Preparing custom stylesheets targeting table elements

For now, you should remove any references to table , thead , tbody , tr , td from your custom stylesheets, and replace them with the new classes. Then, when we eventually change the element types, your custom theming should continue to work without a hitch.

We’re excited to see what our community of theme and plugin developers will be able to build following these changes! :partying_face:


Can you share a little more about what’s happening here?


The tl;dr is that we’re not going to be using the HTML table element for topic lists any more, they behave in some odd ways that aren’t great if you want to make significant changes with CSS.


This is huge - I’m so excited to move away from tables. It’ll allow much more flexible and simple theming across topic lists. :heart_eyes:


This is an excellent change, because Ember does not allow (afaik) dynamic swap out of tags, e.g. <table> or <tr> to <div> using bindings, unlike classes, which it thankfully does!

That means if a <table> is in the root of a component template, you are kind of stuck with it unless you override the entire thing, which would otherwise be a bit of an unnecessary overkill.

In short, I APPROVE! :heart_eyes:


thanks for introducing these changes! just double-checking before I adjust declarations…

the markup is:


and respective classes are/will be:

    (tr will be dropped here?)

Yep, this all looks correct :+1: