Change icons globally using the APIs


(Daniela) #1

:loudspeaker: We recently upgraded to Font Awesome 5.5, many things have changed since the previous version, please read Introducing Font Awesome 5 and SVG icons :eyes:

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

  1. Right click on the icon you want to change and select “Inspect element” or “Inspect” (depends on the browser)
  2. Find the icon name
  3. Search a new icon here Icons | Font Awesome, e.g. external-link-alt
    • remember that after switching from Fontawesome 4.7 to Fontawesome 5.5, icons that are not used by default from Discourse must be added manually in the site setting svg icon subset.
  4. Customize and add the code in your admin > customize > themes > Header tab
    <script type="text/discourse-plugin" version="0.8">
        api.replaceIcon('link', 'external-link-tab');


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


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 :heart: icon with :+1: icon:

    <script type="text/discourse-plugin" version="0.8">
        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:

    <script type="text/discourse-plugin" version="0.8">
        api.replaceIcon('d-liked', 'thumbs-up');
        api.replaceIcon('d-unliked', 'thumbs-up');
        api.replaceIcon('heart', 'thumbs-up');


Another example:

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

changes the watching icon:
watching-original watching

See here other exceptions that cover the tracking status, expand/collapse, notifications and likes of course.
  'd-tracking': 'circle',
  'd-muted': 'times-circle',
  'd-regular': 'circle-o',
  'd-watching': 'exclamation-circle',
  'd-watching-first': 'dot-circle-o',
  'd-drop-expanded': 'caret-down',
  'd-drop-collapsed': 'caret-right',
  'd-unliked': 'heart-o',
  'd-liked': 'heart',
  'notification.mentioned': "at",
  'notification.group_mentioned': "at",
  'notification.quoted': "quote-right",
  'notification.replied': "reply",
  'notification.posted': "reply",
  'notification.edited': "pencil",
  'notification.liked': "heart",
  'notification.liked_2': "heart",
  'notification.liked_many': "heart",
  'notification.private_message': "envelope-o",
  'notification.invited_to_private_message': "envelope-o",
  'notification.invited_to_topic': "hand-o-right",
  'notification.invitee_accepted': "user",
  'notification.moved_post': "sign-out",
  'notification.linked': "link",
  'notification.granted_badge': "certificate",
  'notification.topic_reminder': "hand-o-right",
  'notification.watching_first_post': "dot-circle-o",
  'notification.group_message_summary': "group"

Ref: discourse/icon-library.js.es6 at master · discourse/discourse · GitHub

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

How can change share link icon
Howto: Change lock icon for restricted categories
Harmonizing Discourse icons and emojis
How to remove the lock icon in private categories
Can you change (or remove) hamburger menu icon?
Alternatives to lock icon for categories
How to change notification level icons?
Change sharing icon on posts