Change icons globally

Discourse · May 17, 2018, 3:45pm

This is an easy way to change a Discourse icon globally.

Right click on the icon you want to change and select “Inspect element” or “Inspect” (depends on the browser)
Find the icon name

image1039×318 20.2 KB
Search a new icon here Find Icons with the Perfect Look & Feel | Font Awesome, e.g. external-link-alt
Customize and add the code in your admin > customize > themes > edit code -> JS tab

// {theme}/javascripts/discourse/api-initializers/init-theme.gjs

import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  api.replaceIcon("link", "external-link-tab");
});

Icons that are not used by default from Discourse must be added in the site setting svg icon subset then force refresh your browser to see the changes applied.
Result:

All the “link” icons will be replaced by “external-link-tab”.
If an icon is used for multiple elements in other pages, such as badges, the icon will also be replaced there.

Exceptions

Note that there is already a theme component that allow you to change the Like icon. I’m using this case as example

The “heart” icon, used to give Like, is hardcoded with other names ('d-liked' and 'd-unliked') and should be treated differently than other icons, so to change the icon with icon:

api.replaceIcon("d-liked", "thumbs-up");
api.replaceIcon("d-unliked", "thumbs-o-up");

but on the badge page the icon is still “heart”:

so to change it on that page we add:

api.replaceIcon("heart", "thumbs-up");

Another example:

api.replaceIcon("d-watching", "eye");

changes the watching icon:

See here other exceptions that cover the tracking status, expand/collapse, notifications and likes of course.

const REPLACEMENTS = {
  "d-tracking": "bell",
  "d-muted": "discourse-bell-slash",
  "d-regular": "far-bell",
  "d-watching": "discourse-bell-exclamation",
  "d-watching-first": "discourse-bell-one",
  "d-drop-expanded": "caret-down",
  "d-drop-collapsed": "caret-right",
  "d-unliked": "far-heart",
  "d-liked": "heart",
  "d-post-share": "link",
  "d-topic-share": "link",
  "notification.mentioned": "at",
  "notification.group_mentioned": "users",
  "notification.quoted": "quote-right",
  "notification.replied": "reply",
  "notification.posted": "reply",
  "notification.edited": "pencil-alt",
  "notification.bookmark_reminder": "discourse-bookmark-clock",
  "notification.liked": "heart",
  "notification.liked_2": "heart",
  "notification.liked_many": "heart",
  "notification.liked_consolidated": "heart",
  "notification.private_message": "far-envelope",
  "notification.invited_to_private_message": "far-envelope",
  "notification.invited_to_topic": "hand-point-right",
  "notification.invitee_accepted": "user",
  "notification.moved_post": "sign-out-alt",
  "notification.linked": "link",
  "notification.granted_badge": "certificate",
  "notification.topic_reminder": "far-clock",
  "notification.watching_first_post": "discourse-bell-one",
  "notification.group_message_summary": "users",
  "notification.post_approved": "check",
  "notification.membership_request_accepted": "user-plus",
  "notification.membership_request_consolidated": "users",
  "notification.reaction": "bell",
  "notification.votes_released": "plus",
  "notification.chat_quoted": "quote-right",
};

Ref: discourse/icon-library.js at main · discourse/discourse (github.com)

Feel free to create other themes component and share it in our Theme component category!

This document is version controlled - suggest changes on github.

thegurjyot · March 6, 2019, 10:17pm

Your post does help in changing icons globally but how to change the share icon in posts only? I do not want to change the link icon in the editor but, only in the posts. I checked the other posts in the forum but none of those work in the current build of Discourse, thus I am asking it here.

Pad_Pors · April 22, 2019, 6:04pm

thanks for the clear guide. a small point:

is it possible to change d-watching to fas fa-eye and d-tracking to far fa-eye together?

if yes, how would one add the fas icon to the svg; as I tried adding fa-eye and this header:

<script type="text/discourse-plugin" version="0.8">
api.replaceIcon('d-watching', 'fa-eye');
api.replaceIcon('d-tracking', 'eye');
</script>

but the watching icon is not working.

also I was checking other icons such as bells, and I see even when I add bells to the svg icon subset it’s not loaded:

is there anything else I should do in order to be able to use bells?

pmusaraj · April 23, 2019, 2:08pm

Bells is a Pro icon, so it can’t be included, our default FA5 implementation only covers the free icons.

The solid eye icon is a bit of a special case: the FontAwesome 4 eye icon was moved to the regular bundle, so in Discourse we have a matcher for it that converts ‘eye’ to ‘far-eye’. Unfortunately, this stops you from using the solid ‘eye’ icon in Discourse, because Discourse will redirect eye to far-eye. If you absolutely must use that icon, you can copy the svg into a custom icon that you can rename to something of your liking, and add that to a theme or plugin.

Pad_Pors · April 23, 2019, 5:25pm

thanks for the complete information , meanwhile I’ve tried several other icons, e.g. user-shield.

here is the header:
<script type="text/discourse-plugin" version="0.8">
api.replaceIcon('d-watching', 'fa-user-shield');
</script>

and I added fa-user-shield to the svg icon subset, but it still shows empty icon.

pmusaraj · April 23, 2019, 5:37pm

Try without the “fa-” prefix for user-shield (both in the JS code and the site setting).

Pad_Pors · April 23, 2019, 5:42pm

still empty (tried with flag for easier snapshot):

pmusaraj · April 23, 2019, 5:45pm

That works locally for me. Did you refresh the page after making these changes?

Pad_Pors · April 23, 2019, 5:50pm

yes, refreshed with F5 and ctrl+R just to be sure!

is there anyway to look for possible errors?

pmusaraj · April 23, 2019, 5:52pm

If you are familiar with the rails console, I would try logging in to the console and running SvgSprite.expire_cache and then refreshing the page to see if that does it.

GuilhermeBac · April 23, 2019, 10:56pm

How to change the solid (fas fa-bookmark) to regular version (far fa-bookmark)?

https://fontawesome.com/icons/bookmark?style=regular

P16 · April 25, 2019, 11:26am

@dax Is there a way to change the default heart icon to an emoji icon?

pmusaraj · April 25, 2019, 1:36pm

Currently, no, you can only replace svg icons with other svg icons, not emojis.

porterbayne · September 15, 2019, 1:52pm

Is it possible to change to custom SVG icons we add, rather than just FA icons?

pmusaraj · September 15, 2019, 2:15pm

Yes, see Introducing Font Awesome 5 and SVG icons for details.

porterbayne · September 15, 2019, 2:44pm

Thank you! I also found Replace Discourse’s default SVG icons with custom icons in a theme

I ended up embedding the SVG sprite directly into the Header file, as uploading it and naming it as that article says to do did not work for me (could be operator error, of course).

So my Header is:

<svg width="0" height="0" class="hidden" style="display: none;">
    <symbol id="myicon-search" ..... </symbol>  
    <!-- all of my symbols here... -->
</svg>
<script type="text/discourse-plugin" version="0.8">
    api.replaceIcon('search', 'myicon-search'); 
</script>

And that is easy to manage.

I use the SVG sprite generator at https://svgsprit.es to make sure the format is correct.

bekircem · February 1, 2020, 10:46pm

Can we use Microsoft’s Fabric Icons with this method?

pmusaraj · February 2, 2020, 1:05pm

You should be able to, yes. I don’t see an official SVG sprite distribution of those icons, but according to https://github.com/OfficeDev/office-ui-fabric-core/issues/1008 you can extract SVGs yourself, one by one, using their names.

tomwrench · May 2, 2020, 2:54am

I’m trying to do the same thing. I’ve changed the ‘share’ icon successfully in posts but it appears it also changes the ‘link’ icon in the editor. Any ideas how to change just the posts icon?

ghgoodreau · July 30, 2020, 2:25am

Is there a way to change a fontawesome icon globally to an SVG icon uploaded in the theme upload section? I am working on a site and would like to specifically change the fontawesome icon for when a topic is solved (using the discourse-solved plugin) to my site’s logo. I am having a hard time approaching this via the actual plugin code and I was wondering if this header method works for something like that.

Topic		Replies	Views
Replace Discourse's default SVG icons with custom icons in a theme Developer Guides how-to , theme-guides	8	8511	September 17, 2025
I can't change the notification icons Dev	6	822	January 30, 2023
Change the Like Icon to :+1: Theme component official , change-like-icon	6	13992	February 27, 2024
Introducing Font Awesome 5 and SVG icons Announcements new-feature	135	41899	December 1, 2023
How to replace an existing SVG icon with a custom one? Dev	11	447	September 4, 2023

Change icons globally

Exceptions

Related topics