Introducing Font Awesome 5 and SVG icons

In the *.hbs file, you can replace it with:

<a class="red" href="">{{d-icon "edit"}}<span>&nbsp; Courses</span></a>

In widgets:

+ import { iconHTML } from "discourse-common/lib/icon-library";
+ let icon_edit = iconHTML('edit');
+ ${icon_edit}

It works for us.

Much depends on where you add the icons (via plugin, admin panel …). Examples of the above we did for plugins.

1 Like

Thanks for the response @Stranik.

Something interesting is that I only changed my html for the “home” link, which is the first of my five links in the global nav bar. It didn’t work. Then about 30 minutes laters I looked at the site and it was working! So I’ve updated all of my other links to follow the same convention. Same issue… not working… but I’m wondering if some time passes and they will load as well ¯_(ツ)_/¯

While the Home icon seems to be working… for all of the links I’m getting an error…

But… back to your suggestion…

In widgets:

+ import { iconHTML } from "discourse-common/lib/icon-library";
+ let icon_edit = iconHTML('edit');
+ ${icon_edit}

If I were to go the route you suggested, where would I add all of this? :arrow_up:

The option with the plugin (widgets), the one that I gave above, does not suit you.

I think, in your case, the option suggested above in the post will work:

I tried on the test site and it worked.

I do not know how such a construction is correct, but apparently it works for me.

<svg aria-hidden="true" data-prefix="fas" width="25" height="25" data-icon="edit" role="img" xmlns="" viewBox="0 0 576 512" class="svg-inline--fa fa-edit fa-w-18"><path fill="currentColor" d="M402.6 83.2l90.2 90.2c3.8 3.8 3.8 10 0 13.8L274.4 405.6l-92.8 10.3c-12.4 1.4-22.9-9.1-21.5-21.5l10.3-92.8L388.8 83.2c3.8-3.8 10-3.8 13.8 0zm162-22.9l-48.8-48.8c-15.2-15.2-39.9-15.2-55.2 0l-35.4 35.4c-3.8 3.8-3.8 10 0 13.8l90.2 90.2c3.8 3.8 10 3.8 13.8 0l35.4-35.4c15.2-15.3 15.2-40 0-55.2zM384 346.2V448H64V128h229.8c3.2 0 6.2-1.3 8.5-3.5l40-40c7.6-7.6 2.2-20.5-8.5-20.5H48C21.5 64 0 85.5 0 112v352c0 26.5 21.5 48 48 48h352c26.5 0 48-21.5 48-48V306.2c0-10.7-12.9-16-20.5-8.5l-40 40c-2.2 2.3-3.5 5.3-3.5 8.5z" class=""></path></svg>


For the edit icon, you can use the following SVG code:

<svg class="fa d-icon d-icon-pencil svg-icon svg-node" aria-hidden="true">
  <use xlink:href="#pencil-alt"></use>

Note that you should aim to figure out how to use the JS/Handlebars helper functions in the OP, they automatically handle renamed FontAwesome icons. When using SVGs directly, you’re going to need to track down the icons yourself. As you can see in code above, the edit icon in FA5 is called pencil-alt in the <use> tag. (For other renames, refer to the FontAwesome upgrade guide.)

Also note that the class to include in the svg element is fa, not fas.


I agree with your sentiment here and am okay with a CSS only solution.

Can you tell me exactly what JS I need to put in my </head> ? And what the matching HTML element should look like?

I had a tough time interpreting the OP :disappointed: I’m pretty new to all of this

I think your best bet here is to look at how some theme components work. I would highlight these two specifically:


You can install these two components on your site, and/or inspect their code to see how they use JS to insert elements on the page.


Just reporting back a simple CSS solution that worked for me and coincides perfectly with my global navbar in wordpress:

I added the following to :

<link rel="stylesheet" href="" integrity="sha384-B4dIYHKNBt8Bc12p+WXckhzcICo0wtJAoU8YZTY5qE0Id1GSseTk6S+L3BlXeVIU" crossorigin="anonymous">

My html in the “Header” looks like this:

    <a class="red" href=""><i style="margin-top: -1px;" class="fas fa-home fa-sm"></i><span>&nbsp; Home</span></a> 
    <a class="red" href=""><i style="margin-top: -1px;" class="fas fa-edit fa-sm"></i><span>&nbsp; Courses</span></a> 
    <a class="red" href=""><i style="margin-top: -1px;" class="fas fa-calendar-alt fa-sm"></i><span>&nbsp; Events</span></a>
    <a class="grn" href=""><i style="margin-top: -1px;" class="fas fa-comments fa-sm"></i><span>&nbsp; Community</span></a>
    <a class="grn" href=""><i style="margin-top: -1px;" class="fas fa-star fa-sm"></i><span>&nbsp; Resources</span></a>

Annnnnnd, my navbar FA icons are back!


This will make your site load both the SVG version of Font Awesome and the WebFont version, which will be a extra bytes (85kb).

Not to mention that the extra CSS (foreign to Discourse now) can break in weird ways in the future.


YOWZA! That’s not good to have all the extra bytes. Is there a way to prevent it from loading the SVG version as well? It was just so much easier to do this approach, and I just wanted my icons back up as quick as possible.

I think you need to do this the correct way rather than the “easy” way…


Wiser words have never been spoken! ツ

Thanks for the tip about the implications of the hacky approach I shared, @Falco. I’ll see if I can figure out how to do it the “correct” way when I have some time!


Since you’re adding the elements above the header, you can use the above-site-header plugin-outlet

Now, it’s very simple to do so, there’s more details here but the simple version is that you need to wrap your html in this

<script type="text/x-handlebars" data-template-name="/connectors/above-site-header/custom-menu">


Once you do that, you’ll be able to use the {{d-icon}} component. So instead of

<i class="fas fa-home fa-sm"></i>

you’d use

{{d-icon "home"}}

So you end up with this in the header section of your theme

<script type="text/x-handlebars" data-template-name="/connectors/above-site-header/custom-menu">
<div class="navbar">
  <a class="red" href="">
    {{d-icon "home"}}
  <a class="red" href="">
    {{d-icon "edit"}}
  <a class="red" href="">
    {{d-icon "calendar"}}
  <a class="grn" href="">
    {{d-icon "comment"}}
  <a class="red" href="#">
    {{d-icon "star"}}

and this small CSS rule

.navbar .d-icon {
  margin-right: 0.5em;

and that would create

Notice how there’s a couple of icons that are missing, well that happens because those icons you want to use are not included in the default set. FontAwesome 5 has tons of icons and there’s no point loading them if they’re not going to be used.

The missing icons are star and edit.

Adding icons to the set on your site is very simple. Search for the


setting in the admin, and add those there like so:

and go look at the header (after a page refresh) and all the icons should display nicely now


I’ve noticed some of the SVG icons look less elegant than their FontAwesome icon font equivalent.

Example SVG:


Example FA:


Is it possible for me to tweak the SVG rendering (e.g. stroke width in the above example) to improve their style?


I understand where you’re coming from but It actually has nothing to do with SVG icons V.S. font-file.

FontAwesome 5 changed a lot of icons. One of the icons that changed is the calendar icon in your screenshot.

Here’s what the calender icon looked like in FA4


Here are the two free options available for the calendar icon in FA5



and here’s what the FA5 pro - paid - calendar icon looks like



Thanks for the insight @Johani. I wonder if there are some nicer SVGs on offer elsewhere (assuming I can use CSS to substitute custom SVGs)

1 Like ?


Good shout @TheBestPessimist


I’m brand new to all of this. Is it possible to use icons for each catogery?

For example there is a :poop: posting section, so I’ve added fas fa-poop to the library.

How would I go about using that icon to act as the icon on the :poop: posting section rather than the brown square that is there now?

I’ve no real experience with css/html but if anyone could show me a quick example and then I’m quite confident I can use that to then go on to change the rest of the icons.

Thank you.

For those struggling with this change breaking all the Font Awesome 4 icons on their website, I have found “the easy way” to fix it and highly recommend it for the time being. (Disclaimer: I am not an authority here, just someone who uses and loves this software)

  1. Go to this official Font Awesome page titled Get Started with Font Awesome which seems to be the latest 4.x.x-version
  2. Type your email to have them send you what is called a CDN
  3. Copy the short <script src=[...]></script> that they emailed you into your skin’s HTML (such as the </head> tab)
  4. Refresh your page (and maybe your browser cache) and your Font Awesome 4 icons will be restored.

Yes, this will add a few KB to your page, but it will also make your page function immediately. If you are interested in shaving off the extra KB on your site’s initial load time, then you can add “convert to FA5” to your list for when you have the time. Meanwhile your site continues to function while you take the time to do these changes.

In the future I hope Discourse can avoid silently dropping features like this, especially when it is definitely aware of them as “breaking changes”. I used the previously-supported CSS :before method in my skin to insert icons where I wanted them, because there were no handlebars at those locations and this was a simple and easy way to get them exactly where I wanted with no fuss. In retrospect, I would have expected one or two of the following options to have been in place:

  • Show a message on the admin panel or update pages explaining that certain features (:before and <i> icon methods) would soon be dropped, so that we are aware beforehand that all our icons are about to be replaced with empty boxes. (meta-discourse announcements are not otherwise in my radar, and they shouldn’t have to be)
  • Provide a new website option for reverting to Font Awesome 4, with the note that all new discourse installations will use only FA5 and that support for this FA4 compatibility option would eventually be dropped.
  • Provide a set of official instructions for converting :before or <i class="fa fa-icon"></i> usages to the new system. In this case I don’t think this would have been possible, because these changes are not necessarily trivial, especially in the case of :before.
  • Allow us to use an older version of Discourse that will continue to receive security updates but not breaking changes. (Right now the big sad face on the admin screen every 20 days seems to discourage this method of keeping our websites intact)

Fact is, this update has breaking changes in it, and these changes were not advertised to all the site admins using discourse, and these changes do not have any official instructions for making a smooth transition. Shaving off KBs and other optimizations are great, but in my opinion, not unexpectedly breaking websites to get there is even better, so I am confused why the official statements here actively discourage “the easy way” I have given as a temporary solution. I love Discourse and hold a very high opinion of it, but I also want to have to visit meta-discourse as infrequently as possible. :slight_smile:


@troid92 you’ve given problematic advice for these reasons, as previously stated:

If you don’t want to fix things, never upgrade your Discourse instance. You will eventually get hacked and compromised, of course, but that’s your choice. If you want zero effort, I suggest you pay for managed hosting. Otherwise, you may have to do an hour or two of work per month when choosing to host your own Discourse.

Free software is indeed free, but people’s time isn’t.