Moving to a Single Category Style Site Setting

:information_source: Discourse updates made 2023-11-13T05:00:00Z or later will include this change.

In an effort to unify how categories are styled in the UI, such as in the sidebar or when mentioning a category in chat or in a post, we are removing the non-default category styles from the category_style site settings and ultimately removing this setting entirely.

:information_source: For those of you already using the default (bullet) category style, no action is required.

For those of you using a category style other than the default (bullet), we have a new theme component that you can safely install right away. By doing this, your site will continue to use your existing category style setting even when we eventually remove this setting from core sometime before the final 3.2 release.

If you are not strongly attached to your non-default category style, we encourage you to switch back to the default (bullet) style to avoid needing an additional theme component on your site. Here’s how to do it:

There is nothing to install to switch back to the default bullet style.

Look for the category_style admin setting and change it to “bullet”, so that it looks like this:

Screenshot 2023-11-09 at 6.38.11 AM

Here are the steps:

  1. go to /admin on your site
  2. select SETTINGS from the menu
  3. search for “category style”
  4. select “category style” pulldown and select “bullet” (or select RESET to change it back to the default, which is bullet)

Once you’ve done the above, you will see the bullet style everywhere categories are displayed.

Soon, there will be a notification on the admin dashboard for all sites that aren’t using the default category style, informing them that they will need to install the Category Badge Styles theme component.

Once you have the theme component installed, please select the existing category style you would like to continue using. Please note that any selections made here will not take effect until the category style setting has been removed from core. This measure is to ensure a seamless transition.


How would this affect theme components such as this one?


Same question… when using category icons the category style is usually set to none, otherwise it would show both icon and bullet right now:

Would this be merged into the Category Icons component or would we need two components (or custom styles) for a plain style with icons?

Another feedback:

Right now the sidebar styles look like the bullet badge, but they are not the same class of element, declared by the same style declaration. So wonder if classes and style declarations will be unified as well?

E.g. this shows when you want to have round bullets:


That can be done with a simple declaration on the bullet badges:

.badge-wrapper.bullet .badge-category-bg {
  border-radius: 10px;
  width: 9px;

Showing the same plain colored round bullets on the sidebar gets more complicated. (by default they will mix colors from parent and child category in a gradient declaration) E.g I did this recently:

.sidebar-section-link-prefix > span {
// move the background color of a potential parent category out of view
  background-size: 15px 15px !important;
  background-position: right center !important;
.sidebar-section-link-wrapper .sidebar-section-link-prefix .prefix-span {
  width: 0.5em;
  height: 0.5em;
  border-radius: 50%;

So, the official discourse site (this, will also revert back to bullet style? (as I notice some of your categories are also using “box style”). I don’t understand the removal of perfectly fine features. Is it too overwhelming to maintain code? or just to promote/sell the same theme components in the future?

1 Like

The category style setting is for the style of the category badges, not the layout of a category page:

This is the ‘box’ version:

Versus the default ‘bullet’:

With the introduction of the sidebar and hashtag-autocomplete, those styles now don’t translate as well across all elements of the UI, and as most sites stick to the default it makes sense to create a theme component for those that do still want it and to remove the setting from core to simplify things overall.

As all of our theme components are free for everyone, we’re not looking for opportunities to sell anything. :slight_smile:


If I understand Blake correctly in the first post, nothing will be taken away here and you will be able to configure your site to behave as it does currently using the new GitHub - discourse/discourse-category-badge-styles: Adds the box and bar style for Discourse categories theme component. Just install that and set the category style to none. You can do that right away, even though it does not have any effect yet while the category style site setting exists.

Here’s what the theme complnent setting looks like:

Screenshot 2023-10-18 at 5.39.27 AM


That actually brings up a different question for me, since categories currently disable the color selection for display style of none, will the TC match that behavior, or will it still allow selecting colors? If it allows color selection, then that makes config for the category colors a lot easier.


I just tried it on my site and saw a significant styling difference for the ‘box’ option.

This is how it looks without the theme component:

And with the theme component (larger padding from and blue font from var(--category-badge-text-color)):


I tested this and was able to replicate it.


Are there any intentions of removing or touching the desktop category page style setting?


This theme component won’t work properly until the changes that remove the alternate styles are merged into Discourse. Currently our work is on a branch, GitHub - discourse/discourse at category-bullet-only… and the theme component is working with that. It’s still a work in progress.

The category icons component will need to be refactored, we can work on that before this update happens.

For the default bullet category style with icons, this should be handled by the component… but for the additional box/bar styles it will require both components.

This is also true for mentions like announcements — we looked at this and the outcome was that it’s too complicated to use a shared component… but I can take another look at how closely we can mirror the HTML & CSS between the variations.

There are a few reasons, but the default bullet style is used by the vast majority of sites we host, and as we’ve introduced new features like the sidebar and category mentions (like this: announcements) multiple styles complicates things.

Supporting multiple variations means we have to accommodate and test for everything 3-4 times. This becomes hard to justify when a feature is purely visual and only used by a small % of sites. Moving something like this to a theme component means we can simplify Discourse a little while still supporting the sites that use the alternative styles.

We generally don’t sell theme components, but we do build custom components for our Enterprise customers. There are no plans for this to change.

No plans at the moment, but this is a similar situation where most sites use the default style (by a wide margin). If we were to do this, we’d likely follow a similar plan and support the removed styles via theme component.


So how exactly to revert to the default to get rid of the warning? Setting Category badge style to bullet?


Yes, that’s correct. No immediate urgency to change anything but you will get a warning on the admin home page until you do.


And that helper component will start work at some point and will hide bullets? Because now it leave bullets untouch and show icons too (for me with none and category icons).


We just pushed an update to the theme component to fix this issue. So you can update to the latest version and enable it now.

This will allow you to choose your existing category badge style within the theme component, but it will not have any effect yet.


I reset our forum back to bullet and the theme component to none, and the bullets are still displaying, is that intentional?


If you want “none” you should set them both to “none” for now. That way when core is updated (we are still working on an update for core) and those settings go away from core the theme-component will know to keep you on “none”. Right now the precedence is still on the core setting, but soon it will be on what you have selected in the theme component.


It works perfectly now. Thanks for the quick update!


Thanks, Bullet helped. In fact it looks even ok, I remeber the bullets have been smaller before thats why i used the lines. (But maybe that was changed in my theme, no idea).


Is there a video of the install process, I find it helpful to view the process and read the instruction at the same time. I rarely make chances to our site as I have this fear I’ll make mistakenly big changes which I’d be unable to fix.