Category List Widget

The Category List Widget lets you display a list of categories in a sidebar. It is typically used as form of navigation. You can see an example of it on this forum (in the left sidebar).

Follow this guide to install and administer this widget: Installation and Setup

Parents and subcategories

The widget will show parent categories and subcategories in a hierarchy, like you see in the example on this forum. Clicking on a parent will display a list of subcategories if the parent has any subcategories. If the parent doesn’t have any subcategories clicking on it will navigate to that category.

Excluded categories

You can exclude categories from the list by adding their category “slugs” to the excluded categories setting in the theme component setttings. You can find the category slug in the category’s settings (it’s also in the category url).

Order by activity (advanced)

The default order is the order the categories appear on the /categories page. You can change this order using the admin controls on the categories page.

The order by activity setting orders sub-categories by activity in that category (latest post created in the category), however this relies on additional data being sent from the server to the client, which we currently do in another plugin. The upshot of this is this won’t work out of the box. You need to have a plugin installed that includes this:

add_to_serializer(:site_category, :latest_post_created_at) { object.latest_post&.created_at }

Unless this makes sense to you, do not use this setting. We will be adding additional order settings in the future.

Show unread

If a category slug is included in this setting the category and any sub-categories will display their “unread” count. If you are a client of ours you will see this in action.


2 posts were split to a new topic: Add support for category icons component

Hello! We are using this Category List Widget and loving how it allows us to organize categories so our users can easily know where they are in community. Thanks for open sourcing this great tool!

I am also using this Theme Component called : Discourse Category Banners and noticed a potential bug/conflict with this TC…


Hey @jord8on, yes, that’s an alignment issue that’s tricky to address, partly because there a number of possible components and customisations that can cause it (not just via the category banner theme component).

I do want to address this in a general fashion at some point, but I’m still thinking over the best way to handle it so that it won’t happen regardless of what other banners or theme components you use. There are a few banner components that cause this, and some standard discourse banners.

The only way you can semi-address this now is by using absolute positioning for the sidebar (it’s a site setting). Basically that means the sidebar will scroll with the rest of the page content rather than being fixed in place. You may not want absolute positioning for the sidebar though.

1 Like

Ahhh… I like the way you alway seem to think about these types of things… not just a bandaid, but instead a universal fix. I’ll be cheering you one. Sure wish I had the know-how to contribute some code for a universal fix. :disappointed:

I think you’re right, about absolute positioning. That’s prob not the direction we want to go.

Hi! I just installed this widget and it works beautifully except for when I’m viewing our topics with the Kanban theme component view.

Here’s a screenshot of what I mean

See it live here: Internal Comms - Youth Power Hub

Do you have suggestions for how to remedy this?

I’m guessing I’ll also need to bring this up on Meta with David, the person who created the Kanban Board Theme Component?

I’m having the same problem, too, but I realize now that there’s another solution.

Angus, could you point us in the right direction for what you use to show category descriptions in a way that doesn’t conflict with your layouts plugin?

I’d like to do something similar to what you do for the Knowledge category, for example.

Also, I’m not sure where I should be posting questions like this so do correct me if you want my topics to go elsewhere.