Tag Icons

	Summary	Tag Icons allows tags to have an icon next to the tag label.
	Preview	Preview on Discourse Theme Creator
	Repository Link	https://github.com/discourse/discourse-tag-icons
	New to Discourse Themes?	Beginner’s guide to using Discourse Themes

Features

Here is an example of how this would look, with tag style set to the default (simple):

image1566×180 31.5 KB

Here is how this looks with tag style set to box:

image1364×122 30.3 KB

Settings

Hosted by us? Theme components are available to use on our Standard, Business, and Enterprise plans.

Last edited by @tobiaseigen 2025-08-27T06:57:11Z

Check document

Perform check on document:

Does this also work with custom svg?

Yes, but you would need to register the custom SVG in a plugin (themes should soon also be able to add custom icons to the SVG sprite set). See Introducing Font Awesome 5 and SVG icons for details.

Now that custom icons in themes has been merged is it possible to use FA Pro icons with this or does the component need to be updated?

Component doesn’t need to be updated, if you add custom icons via theme/plugin they will be available to the component.

Could the icon be added to the dropdown menu as well?

image.jpg1150×841 279 KB

This allows one to add custom icons to tag, but what if I wanted to change the color of the box of the tag?

You can do that with CSS, for example, the code below will set the “theme-component” text color to red:

.extra-info-wrapper .discourse-tag[data-tag-name="theme-component"] {
color: red !important;
}

(This is just for illustrative purposes only, you’ll need to figure out your own CSS.)

I see thanks. I just have to list every tag I have in the CSS by name and specify the color. Would be nice though if I could do this from the admin panel like with the theme components using a comma separated list and providing the hex code just like for the icons.

Is there a way I can set a color for all tags in a tag group via CSS?

I ended up getting something like this: (The default tag icon is still here)

Does anyone see this kind of result?

Look for “tag style” in your site settings, and change it to simple, that will remove the grey bullets.

I see, thanks, but I will need the default grey bullets for all other tags. I achieved this by remove that bullets for specific tag:

a[data-tag-name="test1"]::before {
    display:none!important;
}

Looks like a fantastic tweak. Question for advice to the author: I am thinking of pimping my bland tags, some of which I use to tag posts by language (so I have tags “castellano”, “deutsch” etc.), with little country flags. Would uploading a custom .svg as described above be the way or are there preconfigured iconsets or maybe discourse-built-in emoji-sets that could be used?

An emoji would make sense for country flags, but this component does not use emojis, it uses icons from an icon set like Font Awesome.

You can try adding the emoji directly in the tag label. I tried this locally, and the tricky thing is that tags can’t have spaces. An example:

If you are ok with the dash, that’s the way to go.

Oh wow that is actually rather neat. Minus the dash but I could probably live with it. Might even be worth trying a tag that is just a flag emoji…

Yes, just an emoji is cool… but you won’t be able to easily find that from a search in the tag dropdown (when posting).

Ok just one more semi-stupid question: how do I get the emoji to work as you did above with the francais? I tried creating a tag ":sweden:-svenska" but it doesn’t translate to the swedish flag

You need to use an emoji symbol (on mobile, for example, you would switch to the emoji keyboard).

Ohhhh I thought the emojis in Discourse. Okay, need to switch to a mobile then. I thought I could somehow use these. It worked thanks!

If I understood it right there isn’t an easy way of discovering the group a tag belongs to within the tag renderer?

This one would be great. I was using a custom CSS approach before and ditched it for this theme component with a fallback icon for all non-set tags (at least before the support for tag groups) and this is the one thing I miss.

Considering discourse-category-icons supports this, I’m guessing the renderer that replaceCategoryLinkRenderer replaces is used by the category dropdown while the renderer replaceTagRenderer replaces is NOT used by the tag dropdown, right? So maybe this would need a core change? The tag dropdown on the composer is using the replaced renderer, with icons.

Yes, that’s the issue with tag groups.

Yes, I just had a look and this seems like a fairly simple fix, core needs to use the tag renderer in the filter dropdown (it would match the tag picker in the composer). I will look into it shortly.

I just noticed that the category renderer is also replaced on the dropdown shown when #mentioning on the composer, showing the category icon from the theme component, but the tag renderer shows a renderer different from all other places, with a tag icon beside the tag name:

@pmusaraj do you think it’s possible to make this renderer use the one replaced by the theme component too?

Thanks.

I think standardising this would make sense, yes. Are you interested in working on a PR for this @renato?

(FYI, a PR is up for the filter dropdown, will be merged probably sometime next week.)

I’ve begun using this component to visually alert users when applying a tag will trigger a chat integration.

Would it be possible to optionally color the tag text as well directly from this component? I see a manual option on the forum here. Thanks for the great component!

edit: It’d also be useful to add multiple icons to a tag. Thanks for considering!

This can be done with SCSS in your theme, we don’t have plans to add this functionality to the component.

No plans to allow multiple icons per tag, either.

Hey @pmusaraj

Is there any workaround to set a fallback icon per tag-group yet?

Is it possible to change icons on all tags? Instead of bullets to smth else? This component is only for listed tags if I got it right.

Answer found:

.discourse-tags .bullet:before { 
    background: transparent;
    content: svg-uri('<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" version="1.1" style="shape-rendering:geometricPrecision;text-rendering:geometricPrecision;image-rendering:optimizeQuality;" viewBox="0 0 467 856.25" x="0px" y="0px" fill-rule="evenodd" clip-rule="evenodd"><defs><style type="text/css">.fil0 {fill:black}</style></defs><g><path class="fil0" d="M234 0c129,0 233,105 233,234 0,64 -26,122 -68,165l-165 286 -166 -286c-42,-43 -68,-101 -68,-165 0,-129 105,-234 234,-234zm0 125c50,0 90,40 90,90 0,50 -40,91 -90,91 -50,0 -91,-41 -91,-91 0,-50 41,-90 91,-90z"/></g></svg>'); 
    vertical-align:baseline;
}

SVG icon images can be freely downloaded from sites such as https://thenounproject.com/

Bullet tags + tag-color

If you’re using bullet-style tags and

• you want to have the same tag icon and tag text colors
• you want to show the bullet only if there’s no tag icon set

here’s how i did it for the tags books and science-fiction:

End result:

image938×111 13.3 KB

1. Setup of Tag icons component (this component)

image1466×799 70.1 KB

2. Setup of a secondary component that must be kept in sync with Tag Icons
   In this component we’re doing 2 things:
   1. Hide the bullet for specific tags
   2. Color the tag text with the same color as the icon

For this to work, we create a new theme component: Tag Icons extra.
In the Common/CSS section:

1. Add the following mixin (needed only once):

@mixin updateBulletTag ($col) {
    &.bullet {
        color: $col !important;
    }
    &.bullet::before {
        content: none !important;
    }
}

2. For every tag you want to edit, paste the following and replace REPLACEMETAG with the tag name and REPLACEMECOLOR with the same color as the icon:

[data-tag-name="REPLACEMETAG"] {
    @include updateBulletTag(REPLACEMECOLOR);
}

image1554×621 41.4 KB

Bug report: in the tag selector of a post, the icons are not colored:

Here, the icons should have the same color as the text (text is my own custom css):

My config:

image955×146 9.98 KB

@pmusaraj I have 50 or so tags that I put icons next to about two weeks ago. I check my list of tags now, and five of them don’t have icons anymore… And even if I delete them and re-enter them in, no cigar. I might try deleting all 50 of them and then re-entering them all in to see if that helps, but I wish I didn’t have to, since that’s a pain…

Can you post a screenshot of your settings pointing out the tags whose icons are no longer working?

Hmm, it’s curious that the last five entries are not working. Can you try flipping an entry in the last 5 with another one above and see what happens? It looks like the setting value is getting truncated at some point…

Just so you know, it wasn’t originally the last five that started not to show up. It was five seemingly random ones, and then I went and deleted them and then re-entered them in to see if they would show up (which they didn’t), and that’s why it seems like they might not be showing up because they are the last few.

With that said, I deleted the proof-verification tag, and re-entered it so that it’s at the front of the line. Was orange, and is still orange and showing up fine. Still seems to be just those five…

Is there any way to use those color variables for the tag icon colors?

You can use every color for the tag icons.

Or what do you mean?

Good question, yes, it looks like you can use CSS custom properties, this worked for me:

image1508×330 28.4 KB

Ah my mistake. Just found my error and it’s working just fine.
Awesome that it’s possible!

any way to use a png for the icon? I have all my images I want to use as png images and converting them to svg just ruins them and when I do convert I can’t get the icons to load anyways.

Iv got over 400+ images that I would need to convert and seeing that I can’t even get one conversion to work it would be nice to be able to just use the pngs I already have.

This component isn’t meant to be used with pngs. You can probably just use css in your case.

Ok, iv gotten it to fit in the tag box how it looks nice but that’s for every tags box, iv found how to target specific tags but what would be the right way of selecting that tags box to put in the png icon?

trying to select one -

.tag-question::before {
    content: url(https://s2.coinmarketcap.com/static/img/coins/16x16/1.png);
    width: 8px;
    height: 4px;
    margin-right: 10px;
    margin-top: 3px;
    display:inline-block;
}

Selecting all -

a.discourse-tag.box::before {
    content: url(https://s2.coinmarketcap.com/static/img/coins/16x16/1.png);
    width: 8px;
    height: 4px;
    margin-right: 10px;
    margin-top: 3px;
    display:inline-block;
}

If you’re still looking, I found this site has lots of flag SVG icons and there may be a way to upload them as custom SVG icons on Discourse, not yet sure.

Working great! Here’s a few feature requests:

1. Auto-suggest adding the svg-icons automatically by the tag icon list inputs
2. Convert the tag icon list into a 3 column table, where there can be autocompletion on tags and font-awesome v5 icons
3. Add a link to Search v5 Icons | Font Awesome as turns out I was searching the latest font awesome (current v6) and wondering why my inputs weren’t working.
4. Adopt font awesome v6

Thank you for this.

Any idea why I havent a space between tags? Only happens on mobile

Screenshot

photo_2022-07-23_21-03-101080×1198 153 KB

2 created tags are not working for some reason, could this be a bug? I created the tag interview with the SVG logo microphone-stand and the tag lecture with the SVG logo camcorder. Both remain blank.

Screenshot 2022-08-27 at 18-57-23 Tags - TZM Community Forum1090×159 5.01 KB

Screenshot 2022-08-27 at 18-57-56 Admin - TZM Community Forum741×399 24.5 KB

It does work when I set both tags to use the film SVG logo, which I already used for another tag. So for some reason the 2 initial logos I want to use don’t get accepted.

Can someone reproduce this issue? I could just reproduce it in a clean dev environment with just with this theme component installed. How can I see which version of FontAwesome is in use. Maybe I’m just selecting icons that aren’t included in the version on Discourse. I guess it’s version 5.15. Since these icons were included in 5.11 or 6.0, it should be included.

I can’t get them to work either, so it may be a case of them not being included in the available set.

Hi!

I wonder Can I use some icons with images like nature?

Does this work with tags in tag groups?

I just ran a test in a private category with your tag1 and it works. However tags in a tag group seem to not work?

I am having a similar issue. It seems when a tag exceeds 10 chars the icons do not display.

Figured out tag group issue. seems needed to add tags from groups directly to category vs adding tag group?

I cant get the tag icons to appear anywhere but in the sidebar. Anyone has any idea why this is the case? Tried reinstalling the component, using only that component together with the default theme, still no joy.

image815×215 15.2 KB

Just to check, you added the icons to the svg icons setting in the theme component?

Yeah I did, you can see that the icons themselves appear to the left in the sidebar, but they do not appear anywhere else:

image1372×425 45.7 KB

Hi, Darojax, welcome

I am unable to reproduce this on my side.

Unless CSS is involved or templates are overwritten, the tags are rendered the same way everywhere.

If possible, can you share your forum URL?

Hello, thanks for your reply. Unfortunately at this stage the forum is still in development and not open on internet. I’ll get back to you once we go public, or if the issue is resolved.

Alright, it’s fine. Can you provide your current Discourse version strictly and list the active plugins/components? Maybe it could give us a hint.

I would try to enable only the Tag Icons component with the default theme without any CSS modifications to see if the issue appears. If not, from that, you can figure out what the culprit is.

Of course:

Discourse Version Installed
3.2.0.beta2
(be04154838)

Latest
3.2.0.beta2

I’ve created a fresh Default theme and am only using the Tag icons component installed directly via github:

along with two plugins:

image1111×192 20.5 KB

discourse-landing-pages

docker_manager

No other CSS or html or other customisations have been made.

OK I have found the issue. The plugin doesn’t seem able to handle tags that begin with capital letters. I changed the tag names to all lower case and now it works as intended. Tags starting with capital letters look more tidy in my opinion, would be great if this issue could be handled. : ) But still thanks for a great component.

I’m glad it’s working now. However, how did you create those tags? They are normally forced to be lowercase.

There is a setting for this in the admin panel:

image723×143 7.04 KB

You’re right, my bad, I forgot about this setting.

I know where the issue is, I will propose a fix later.

Cheers!

When an icon is added to the tags, the bullet tag style icon is still displayed. Is it just me?

Screenshot_20231102-183653_Kiwi Browser~21080×2400 171 KB

Make sure tag style is set to “simple”

image935×478 20 KB

That means you will lose the bullet style everywhere.

A new setting allowing users to choose whether to overwrite the tag style setting would be nice, I think.

With this componen it should be box if I’m remembering right.

Here is a quick & dirty CSS to hide the bullet.
You can add it in your theme CSS or a component.

a.discourse-tag.bullet:has(span.tag-icon):before {
   display: none;
}

It works, thank you so much!

Feature request: Could it be possible to add partial slug support similar to Category Icons component?

I have multiple groups of tags, I could easily set an icon for each because the tags share the same prefixes.

For example;

acme-2023, acme-2022, acme-2021 …

If I could select tags starting with acme- and assign the same icon to them, that would simplify so many things for me.

I’m curious about flag emojis as tag icons. Following earlier threads on it from past years.

Is there an easy’ish fix to get this component to recognize tags written in sentence case? As of now, it doesn’t work if it isn’t lowercase.

How are you able to create tags with uppercase characters? When I go to create a tag, it automatically converts it to kebab-case:

Probably just disable this site setting:

Thanks Firepup, I didn’t know that was an option

@ncaming215 It looks like the component converts existing tags to lowercase before comparing them to the tag-slug part in the settings. I was able to get it to work by using a lowercase version of the tag in the theme component settings.

I created a PR a while ago for that issue (reported by another user)

It looks like I will need to update it to match the core change, though. Hopefully, once it is fixed, it will get some attention.

This should be done now.

IS there a way to have all the tags in the same style?

This confused me yesterday when I created a new tag and by default I went to FA5 instead of 6 after the update.

Thanks for pointing that out @ondrej. I have updated the OP. Apologies for any confusion there.

I created a PR which changes the descriptions in the component (and moves them to locales/en.yml)

how to get my custom technology icons imported in this component. eg. like cisco, dell

I have had the issue for a while: the tag icon is displayed in bigger size in header tag icons in topic view:

screenshot from tc’s preview:

Screenshot 2025-02-20 at 21.39.17412×154 8.91 KB

Core has a rule that increases specifically the house icon:

You can overwrite it like:

.d-header .discourse-tags .d-icon-house {
    font-size: var(--font-0);
}

Oh, interesting. I believe the core rule is there when the house icon is used as the site logo. We could update core to increase the specificity and target the logo icon, thus leaving the tag/category icons alone.

I noticed that there are 2 places where the icons don’t show: the dropdown and in the tag banner

image581×378 18.8 KB

@Arkshine @pmusaraj FYI we just reproduced the same issue in search modal. But your CSS workaround fixed it, too

tag icons zu gross search542×825 36.1 KB

for some reason this override CSS wasn’t sufficient since 3.6.0.beta1

I adjusted it to the following and it did the trick:

.d-header .search-result-tag .d-icon-house {
    font-size: var(--font-0);
}

Can you please add option to set default tag icon for all tags that do not have a specific icon?

Also, would be great to have integration with Tag Banners

That’s a nice idea, Hyteller! I’m not a programmer so don’t have that power, but if you suggest it in a new Feature topic we could discuss what that might look like and it might be considered by the team. Would be nice if you could provide some more detail from your end about why you think it is a good idea.

Personally I’d love to see tag icons be included in core discourse instead of having to be added as a theme component.

Welcome to our community!

After today’s update, the forum homepage layout is messy:

It seems this component is broken. It shows up on the sidebar, but does not show up on posts. Perhaps I am missing something.

image279×803 13.4 KB

It seems to work fine on this topic

I cannot spot the tag from your first screenshot in your sidebar screenshot. Can you share the configuration of the theme component for the “Itaa” tag?

Figured it out. It conflicts with the “Remove dashes from tags” component.
Edit 2: The issue still does not change the color, but the icon does appear now.
I have a lot of tags, which is why they are not all visible.

I tried on different themes, and between the different tag styles available for use. I even disabled other components just to be sure.

image1731×336 33.3 KB

image1016×446 14.8 KB

5 posts were split to a new topic: Tag Icons component bug