🗃 Category List Widget

The Category List Widget lets you display a list of categories in a sidebar. It is typically used as a navigation menu.

Follow this guide to install and administer this widget: https://discourse.pluginmanager.org/t/installation-and-setup

Parents and subcategories

The widget will show parent categories and subcategories in a hierarchy. 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 settings. 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 latest

If a category slug is included in this setting the category and any sub-categories will display their “latest” count.

Collapsible sidebar

Adds a nice Minimise button and arrow which collapses down the widget nicely. This is automatic when the available width is constrained.


You can also choose if this toggle should be at the top or the bottom.

Category logos

You can choose to have category logos auto-generated. This means that if a category has a Category Logo Image set in its category settings, that will appear to the left of the category name in the list.

You can also manually set each one using the custom logos setting.

Custom links

You can add links unrelated to your Categories, either above or below the Category list.
You can also set a Header before these links (which can also carry a link)

Category lock icon

This allows you to set an alternative category lock icon, for example unlock-alt !
to display in the Widget.

Theme translations

You can personalise the button labels on the Widget

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.

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: https://hub.youthpowercoalition.org/c/team/internal-comms/13/l/latest?board=default

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.

There’s a relatively straightforward solution to this problem that I didn’t think of before: sticky css positioning. I’ve changed the layouts_sidebar_{side}_fixed site settings to a choice between:

  • fixed
  • absolute
  • sticky

If you’re using the Category Banners Theme component use sticky positioning.

Getting the layouts plugin to work with the kanban theme component will require it’s own independent styles as both of them take over the layout of Discourse, i.e. I’m not sure it will make sense for either to change their structure in a “generic” fashion to make it possible to support the other. The change would be too specific to this particular problem.

I think I might help you out here though as I think this plugin needs an “interoperability” topic. Will post some CSS for Kanban interoperability there.


I don’t see this option currently, and I’m wondering if it’s because I actually don’t know how to update a plug-in. Could you point me to directions on how to do this?

I assumed it would be from the Plug-in page but I’m noticing that there’s a missing checkmark next to discourse-layouts if that means anything at all.


UPDATE: I’ve successfully updated the plug-in now. Thank you.

A post was split to a new topic: Tags route issue

A post was split to a new topic: Mobile display issue

Is there any way to automatically have the category hierarchy fully expanded, rather than hiding subcategories that aren’t part of the “current path” to the topic or list being viewed?

I agree. It would be a very useful feature for less complex forums.

I’ve got another thing - when I use sticky the position of the sidebar-container, it starts out 70px below the top, which is very annoying. Removing the 70px from the CSS doesn’t make it budge - the only thing that does is removing sticky. And sticky is much nicer aesthetically!

Sticky (what I want but can’t get it in the correct position)


Fixed (in the right position)


Any suggestions? Yes, at healthforum.nz

And wait - there is more!

I note that the button controlling the left hand widget hiding isn’t quite the right size, which looks a bit off. While I can target this by CSS easily enough, it would probably be better at your end.

What it is:

What I want:

Also, another nice enhancement would be to hide the now redundant Category dropdown (or have an option to do this) via the plugin rather than a bit of hacky CSS such as I used:

// hides category dropdown for desktop
.navigation-topics .category-drop {
display: none;}

Don’t you love engaged (but annoying) users?

Thanks @Nathan, @keegan or I will follow up here soon.

@keegan These are some nice discrete little open source tasks we can work on together. Let’s break them out into seperate topics. Perhaps in the #open-source:bug-reports or #open-source:feature-requests categories? Not 100% sure on the categorisation here. What do you think?

@angus Yes, I think there are some good ideas here we can work on. Breaking it up into bug reports and feature requests sounds good

A post was merged into an existing topic: [Category List Widget] Unable to scroll to reach bottom categories