Extend Font Awesome and Add New Icons

In a previous article I touched on iconography and we use them on the site. As a reminder, icons are used in three scenarios:

  1. As substitutes for text — this only applies when an icon is universally understood to mean something, e.g., a magnifying glass as a icon for search.
  2. As reinforcements for text — for messages, such as errors, icons cause the message to stand out and become stronger; for actions, we use them with text where icons alone wouldn't suffice.
  3. As visual hints — as a little nudge in the right direction. For example, if we want the user to enter a date, we show an icon of a calendar next to the input field.

There are many ways of delivering icons to a website, the evolution of which has gone from individual image files (which creates a lot of HTTP requests) to flat sprites (which cuts down on HTTP requests) to icon fonts, which is what SCA uses. There's even discussion about the benefits of moving on to SVG sprites.

While the Font Awesome library is extensive, there may come a time when you need to add in your own icons to your site and the question arises: what's the best way to do this? I had a chat with Joaquin Gatica, a consultant with our professional services team, about the best way to do this. He said that there are two options:

  1. Use your own font that includes your icons
  2. Extend Font Awesome to include your icons

Let's take a closer look at these options.

Option 1: Use Your Own Font

I've talked before about adding a custom font and so you can read there about the generic process of adding a font to your site. However, what is different for icon fonts is the construction of the font file itself.

The easiest way is to use a service to generate the file for us. There are a number of services that do this, varying in range and cost but here are some examples:

IcoMoon was the one Joaquin pointed me to, so let's take a look at that.


The service includes a large number of icons for free, with additional ones available for a fee. The easy interface lets you select the ones you want to add to your new font and download it. Of course, you can also edit existing ones or upload your own ones.

So, for example, you could create an SVG of your site's logo and upload it to the service to include your new font.

Converting a raster graphic (i.e., a PNG, JPG, or GIF) to a vector graphic can be done easily online using a converter (e.g., Online-Convert.com) but these tend to work best with very simple graphics. For more complicated graphics, you'll need to use a professional program and 'trace' the graphic.

I took the NetSuite logo, modified it in a graphic editing program so that it was monochrome and uploaded it the converter. Taking the SVG, I imported it into IcoMoon and this was the result:

Then from here, it's a case of adding in any extra icons that I want and then exporting it as a font file. After that, just follow the steps to adding a custom font:

  1. Download the files from IcoMoon
  2. Creating the file and directory structure
  3. Updating the distro.json file
  4. Creating the Sass file
  5. Using the new CSS class in your templates

For more information, you can see the the article on adding a custom font, or adapt the following steps in option 2 (below). When you want to add new icons to this set, you can just recompile the font using the service with the new ones added.

If you're not going to be adding a lot of new icons (e.g., you are just adding your brand's logo) then a cleaner solution is to simply extend the existing Font Awesome implementation.

Option 2: Extend Font Awesome

Note that when I use the word 'extend' here, it's different to the way we extend JavaScript. Unfortunately, it is not as easy to add another file that injects new icons into a font file. Instead, we're going to use the IcoMoon service (as an example) again, this time to generate a replacement for the Font Awesome files.

Before You Start

Firstly, you should know that we keep Font Awesome under Modules > third_parties > Font Awesome. Here we have a number of sub-directories that include one for the different font files and one for the Sass. Importantly, _icons.scss and _variables.scss contain declarations that define how the icons are used on the site. In _variables.scss we assign a variable name to each of the Unicode references of the font glyphs. Then in _icons.scss we declare CSS classes that inject the variables using the content CSS property. This helps users who use screen readers, so that they don't hear random characters that represent icons. When declaring your own icons, you'll need to replicate this in your Sass files.

The second thing you should be aware of is that we have a Gulp task for Font Awesome that runs when you deploy or start a local server. What it does is check your files for how you've used icons and then creates custom font files only containing the ones that you've actually used. This drastically reduces the size of the font files, improving performance. In order to ensure that your new glyphs are included, you'll need to use the glyph in a template and ensure it has a Unicode reference beginning with f. If you use any other letter or number, it will not be picked up by Gulp. You'll note Font Awesome uses references starting with f000 and ending with f20c; keep in mind that when you assign values, you should not clash with existing references and be wary of any new glyphs that could be assigned when you update Font Awesome. Therefore, I'd recommend assigning your custom icons references towards the end of the acceptable spectrum (e.g., start with f400).

With that in mind, let's get going.

Prepare the Module

We'll be using overrides to do this. As such you'll need to set up a new custom module. Mine's going to look like this:

  • Modules

    • customizations

      • CustomIcons@1.0.0

        • Fonts
        • Sass

Create an ns.package.json file for this module. We're going to be overriding all of the font files, so it should look something like the following:

    "gulp": {
        "font-awesome": [
        "sass": [
    "overrides": {
        "third_parties/font-awesome@4.2.0-custom/fonts/fontawesome-webfont.eot": "Fonts/fontawesome-webfont-custom.eot",
        "third_parties/font-awesome@4.2.0-custom/fonts/fontawesome-webfont.svg": "Fonts/fontawesome-webfont-custom.svg",
        "third_parties/font-awesome@4.2.0-custom/fonts/fontawesome-webfont.ttf": "Fonts/fontawesome-webfont-custom.ttf",
        "third_parties/font-awesome@4.2.0-custom/fonts/fontawesome-webfont.woff": "Fonts/fontawesome-webfont-custom.woff"

After that, you'll need to update your distro.json file to register you new module, and add it as a dependency to each of your site's CSS files.

Create the Font Files

Back on IcoMoon, click the Import Icons button. Navigate to the source files for the fonts (third_parties > font-awesome@4.2.0-custom > fonts) and select fontawesome-webfont.svg. This'll upload the glyphs for the existing Font Awesome font. Add your new glyphs to the collection. Then, using the menu icon, select all of the glyphs in the collection and click the Generate Font button.

On the next screen you'll be shown your glyphs as they'll appear in the font. Existing Font Awesome icons will retain their current Unicode references, but your new ones will be assigned default ones. Remember: your glyphs must have IDs that start with f, so I recommend editing them now. Click on the code for each of your custom icons and change them to, for example, f400, f401, etc. When you've changed them, click the cog icon next to the Download button in the bottom right, so that we can configure the generated file. Change the font name to fontawesome-webfont-custom. After that, click the Download button to get the font.

Open the zip file and navigate to where the font files are. Copy them to the Fonts directory. These will override the current Font Awesome font files, which we've declared in our ns.package.json file. Next we need to create the Sass and make a template change.

Create the Sass and Make a Template Change

For the purposes of this tutorial, what I'm going to do is replace my site's logo with a new glyph, one of which, in my example, is the NetSuite logo.

In the Sass directory create a new Sass file, I'm calling mine _font-awesome-additions.scss. In it, I'm putting the following:

$fa-var-brandlogo: "\f400";
%#{$fa-css-prefix}-brandlogo:before { content: $fa-var-brandlogo; }
.brand-logo-icon {
    @extend .fa;
    @extend %fa-brandlogo;
.header-logo-icon {
    @extend .brand-logo-icon;
    font-size: 3em;
    padding: $sc-small-margin 0;

So, in order, I am doing the following:

  1. Creating a variable with the Unicode reference. For my specific icon, it's reference is f400.
  2. Creating the class, which uses the content property to inject the glyph into our element.
  3. Creating a generic class, that can be used by other classes. It extends the fa class, which is the basic Font Awesome class for handling icons, and the class for the icon.
  4. Creating a specific class for my purposes, namely for replacing the header logo. I extend the generic class and then add in my own styling, which applies in this particular case.

With that, the Sass is in my place so now we just need to make a change to one of our templates. For my change I've made an override for header_logo.tpl and I'm replacing the bit of code which sources my site's logo with the following:

<i class="header-logo-icon"></i>

Simple. Now I'm in a position to test. After I spin up my local server and hit the homepage, I should see my change.


We use Font Awesome to provide icons on our site. Their existing library is extensive, and we have tools in place to ensure that only the ones used on your site are included in the final font files.

If, however, you find it lacking, and you want to add your own icons to the site, then we support two ways: creating a custom font file, or by 'extending' the existing Font Awesome font files. While it's not the same as extending a JavaScript file, the latter, while a little labour-intensive, makes for an easy way for you to integrate your own glyphs into the font files. This may require you to perform some maintenance should you wish to update Font Awesome. The simpler method — the one we covered first — is simpler as all you're doing is creating a separate font file with just your glyphs in it. You may prefer to go in this direction, but ultimately the choice is yours.