How to use custom icons on Ionic 3

How to use custom icons on Ionic 3

One of the trending topics I see in the Ionic community is the usage of custom icons in an application. There are already awesome icons built in with Ionic 3, but sometimes you just want to make your application look more unique, or perhaps a designer gave you a set of image icons and you don’t know the best approach to use them. In that case, I highly recommend you to create your own font using SVG icons. This way, regardless of the icon size, it will look perfectly sharp in any device.

Today, I’ll be showing you the exact steps to integrate your custom icons and the ion-icon element.

This tutorial is inspired in this stack overflow topic.

Getting the icons

First of all, you’ve got to get your SVG icons. If you already have your icons or don’t want to pick icons manually, you can skip this step.
I’m no designer, so I use icons made by others. There’s an amazing platform called The Noun Project, which contains thousands of icons of every type and category you could think of. Really, you can search basically anything and you’ll find fantastic stuff. The icons are all free with creative commons, so we can create an entire set from there. In this example, we’ll be using just a few, for testing purposes.


Generating our new font
After downloading the desired icons, we are going to use an app called Icon Moon, which basically can turn a set of SVG icons into a font that a browser can easily understand. This app already has a few sets of icons (most of which are free), so if you haven’t picked your SVGs from somewhere else, you can get from there (you can browse its icon library).

Ok, the first thing we’ll do is import our SVGs:


Right after, we select which icons we want in our font and click on FONT:



Then we’ll get to a screen where it shows the icons configuration:

The icon names will be the name of our svg files. I like to have a way to distinguish between custom and default stuff, so the icons will all have a prefix of ai-(amazing icons). In this screen we can change the icon names, and also their content code. After setting everything up, we press the Download button at the right bottom corner and that’s it! The app will generate our webfont with all those nice icons.

Getting the css ready

After finishing downloading, open it up and you’ll see a bunch of files. What we want to use is style.css and the fonts folder, so ignore the rest. Add the font files to src/assets/fonts/, then rename the style.css file to icons.scss and add it under src/theme/.

Then, reference the newly created file on app.scss by adding this line: @import "../theme/icons"

Open up your recently added icons.scss.

First of all, add../assets/ to every path generated by iconmoon:
from: src: url('fonts/icomoon.eot?39m2i2');
to: src: url('../assets/fonts/icomoon.eot?39m2i2');

To make our icons work the same way as ion-icons, we have to add classes for device platforms (ios and android) just like ion-icon does. We have to do so because the ion-icon component renders the inside elements with dynamic classes generated depending on the platform the user is on, so we have to cover all cases. In case you want it for windows phone too, add the .ion-wp prefix as well.

Here I’m using an example for ai-pacman and ai-rock:

.ai-pacman:before ,
.ion-ios-ai-pacman:before ,
.ion-ios-ai-pacman-outline:before ,
.ion-md-ai-pacman:before ,
.ion-md-ai-pacman-outline:before  {
  content: '\e916';
  font-size: 26px;

.ai-rock:before ,
.ion-ios-ai-rock:before ,
.ion-ios-ai-rock-outline:before ,
.ion-md-ai-rock:before ,
.ion-md-ai-rock-outline:before  {
  content: '\e905';
  font-size: 26px;

Did you notice how poluted this gets? For each and every icon, we had to add 8 lines of code. I wonder how many lines we would have to write for over 30-50 icons.. Nah, too much work.

Fortunately, by using SASS we can create something called mixin. Mixins work similar to functions in javascript, in a way that we can define something that receives a set of arguments and outputs some css code. This way we can eliminate all our effort by creating a mixin that automates the process for us:

@mixin makeIcon($arg, $val) {
  .ai-#{$arg}:before ,
  .ion-ios-ai-#{$arg}:before ,
  .ion-ios-ai-#{$arg}-outline:before ,
  .ion-md-ai-#{$arg}:before ,
  .ion-md-ai-#{$arg}-outline:before  {
    content: $val;
    font-size: 26px;

Now we only have to write a single line of code for each icon:

@include makeIcon(ai-rock, '\e905');
@include makeIcon(ai-pacman, '\e916');

Still.. refactoring the css to use the mixin is quite an effort. As I like to automate stuff, I use the tools in my favor. I created a find-replace regex to do that job for us (replace ai for whatever prefix you are using):

find: \.ai-([\S]*):before {\n\s*content: "(.*?)";\n}
replace: @include makeIcon($1, '$2');

With that you can do a find replace from your editor and get from this:

To this:

ps: For some reason that regex doesn’t work on Visual Studio Code. I still don’t know why.


For some reason which I’m still trying to figure out, if we try running the project now, all custom icons will work, but Ionic’s default icons will break. What we have to do to fix this is go to variables.scss and change the line that has @import "ionic.ionicons"; to @import "ionicons";:

// In order to make custom icons work and not break ionic icons, change ionic.ionicons to ionicons
// @import "ionic.ionicons";
@import "ionicons";

We are done! Now our project is fully capable of using either Ionic default icons or our custom icons! The usage is the same, we just need to use our custom icons names such as:

<!--Using with ion-icon-->
<ion-icon name="ai-pacman"></ion-icon>

<!--Using with ion-tabs-->
  <ion-tab [root]="tab1Root" tabTitle="Default icon" tabIcon="home"></ion-tab>
  <ion-tab [root]="tab2Root" tabTitle="Custom icon"  tabIcon="ai-pacman"></ion-tab>
  <ion-tab [root]="tab3Root" tabTitle="Custom icon"  tabIcon="ai-whatsapp"></ion-tab>

And here’s the result:


That’s it! I hope you guys find this tutorial useful, and please let me know in case of any questions.

You can access a repository with the whole project here.


Web and mobile developer. Occasionally do some origami on spare time :)

You may also like

  • Hi, i can’t have custom icons working.
    The first error i have is when i add

    @import “../theme/icons”;

    i got this

    so i must write

    @import “../theme/icons.scss”;

    After that the custom icons still not appear

    • Francesco Mussi

      Check the github repo to see if you have done it all correctly

    • Could you check the following repo and see if you missed anything?

      If that’s not the case, push a repo on your github and I’ll gladly help you 😀

    • Dieter Woestemeier

      Maybe you haven’t replaced the ai- prefix in the function makeIcon…

  • Francesco Mussi

    Great tutorial!
    I am having an headache trying to style the custom inside an ion-list.
    I don’t know why – but it has by default a strange positioning inside the list.
    Will try to figure it out

    • Hey @francesco_mussi37:disqus , thanks for trying this out. It may happen because all default ion-icons have the same proportion and are all square sized. When using custom icons, you also have to make sure they are all square and proportional. Of course you can use different shaped icons, but then it’s up to you to adjust the stylings accordingly.

      If that wasn’t the case, feel free to push a sample repo on github then paste the link here, I’ll gladly help you 🙂


      • Francesco Mussi

        Thanks for replying.
        Yes, that was exactly the reason. Different proportions. I managed anyway with some custom style, thanks!

  • Jeronimo Nascimento

    Great tutorial, it helps a lot!

    • My pleasure, I’m really glad it was useful for you!

  • Sukumar Dhoni

    simple and clear. Thanks!

  • Jose Pena

    Hello, this is exactly what I needed, but with Font Awesome. I was able to make it work based on your work and can now use Font Awesome icons as if they were Ionic icons. Thank you lots.

  • Best tutorial out there for adding custom icons.
    Cheers man, I owe you a pint!

  • Max Helskens

    Thanks for the great tutorial, my custom icons work perfectly. I have one problem however, the original ionicons won’t appear anymore..
    I checked the repo but I can’t find anything wrong with my code.

    • Max Helskens

      I found the problem, apparently ionic wants you to put your new files in a directory named ‘assets/fonts’. Naming the file ‘font’ or anything else won’t work.

      Thanks again for the great tutorial!

      • Hey @maxhelskens:disqus, I’m really glad this was useful to you, even more that you managed to solve your issue! I’m not sure if having the folder is utterly necessary, but I did structure my files using ‘assets/fonts’.
        Perhaps you followed the tutorial and didn’t notice the `url(‘../assets/fonts/icomoon.eot?39m2i2’);` part, which asked for the fonts to be within that folder?


        • Max Helskens

          No, I definitely had all the correct paths.
          I really think it should be assets/fonts since that is what the ionicons use.
          Anyway, it works perfectly now and I wanted to leave the comment here for others stumbling upon the same problem.

          • Elroi Francis

            Hello, i have the same issue “my custom icons work perfectly. I have one problem however, the original ionicons won’t appear anymore..”

            i do not understand what your solution was.

          • Hey Elroi, did you forget to follow this step?

            Change @import “ionic.ionicons”; to @import “ionicons”; in your variables.scss

  • Guille Acosta

    Hi there, great job man! But I’m facing a problem with your implementation:
    I’m getting weird icons, seems like browser shows some default icons instead of “icomoon” ones.
    Do you know why?
    I already checked every commit of your repo and also checked that stackoverflow link you’ve posted and everything seems to be ok.
    Maybe font files are corrupted? Hope to read your reply.

    global packages:

    @ionic/cli-utils : 1.5.0
    Cordova CLI : 7.0.1
    Gulp CLI : CLI version 3.9.1 Local version 3.9.1
    Ionic CLI : 3.5.0

    local packages:

    @ionic/app-scripts : 2.0.0
    @ionic/cli-plugin-cordova : 1.4.1
    @ionic/cli-plugin-ionic-angular : 1.3.2
    Cordova Platforms : android 6.1.2
    Ionic Framework : ionic-angular 3.5.0


    Node : v7.7.4
    OS : Linux 4.4
    Xcode : not installed
    ios-deploy : not installed
    ios-sim : not installed
    npm : 4.1.2

    • Hey @guille_acosta:disqus , thanks for trying this tutorial out! By checking the console section of your image, I notice the browser is having a hard time to decode the font file. Check if your css @font-face rule specifies every file format (ttf, woff, eot, svg)… like you can see here:

      Also check if you have your paths correctly, like Max Helskens did on the previous comment.

      In case you can’t fix the issue, please upload a sample of the project so I can assist you better.

      • Guille Acosta

        I missed ‘/assets’ in my path. Now it’s working fine. Thank you!

  • Bananna

    i have no knowledge of this.. so i didnt get it that much but ill try hehe

  • Bananna

    hello. i cant increase the size of the customized icons using font-size but i can with default ionicons. please help. thanks.

  • Christian Novak

    Works perfekt! Ty for Sharing

  • Sergio Talente

    Hello Yann, thanks a lot for sharing this! I’m trying to make it work with multi-color icons, I found a solution to manage two colors icon here but it seems there is nothing about multi color (more than 2 colors) in Ionic. Do you have any ideas/hints for that?

  • rout0978

    Hi Yann, Great tutorial! However I am running into some issues. I have followed exact steps mentioned above at end the icon doesn’t appear: Here is what I see inside the css style:
    .ion-md-ai-nyp-home-outline:before {
    content: “”;
    font-size: 26px;

    This doesn’t seem right. Can you help me out?

    Thanks in advance!

  • Jane Dawson

    Thanks for the tutorial @yannbraga:disqus. Using custom icons works fine with this approach. However, resizing the icons cannot be done as it is done with default icons. In css I cannot say “.iconclass { font-size: 30px; }” for example, as it is done with default icons. I have to use “.iconclass::before { font-size: 30px; }” to make it work.
    Do you know why it is like this? Do you have an idea of what we have to do, to make it work the “default way” without “::before”?

    I often use the same css classes for custom and default icons. It would, hence, be more easy to just have one css definition.

    Thanks for any suggestions!

  • Girdhari Agrawal

    You last line saved me, was struggling for 3 days to make icons work for me.

    Changing @import “ionic.ionicons”; to @import “ionicons”; worked for me

  • Saskiasteph

    Hi, I’m not sure what’s going on but I’ve followed everything to the letter, double checked it multiple times, compared my files to your github, and still nothing…the thing that hurts the most is that everyone else has had such an easy time implementing it…! I don’t know what I’m doing wrong???

    The interesting thing is that I’m not getting any errors and the space is still being made for the Icon, it’s just not rendering the icon…

  • Hanan Ur Rehman

    my variables.scss file had

    @import “ionic.globals”;

    instead of
    @import “ionic.ionicons”;
    when i wrote
    @import “ionicons”;
    the icons remained broken

    • Hanan Ur Rehman

      never mind I fixed it
      instead of erasing
      @import “ionic.globals”;
      I added @import “ionicons”; under it

  • Kunal Dhenge

    Thank you man you saved my day…

  • Vincent Brulé

    Hi ! Thank you for the tutorial !

    I have just one problem, my own icon in ion-tab are not aligned, how can I fix that please ? 🙂

  • terrycollinson1

    I have the demo code working like a charm. But how easy is it to then add additional icons? I tried appending to the icomoon.svg file but that did not work. What else do i have to do?

  • You’re a lifesaver! Thanks for this. Was having this exact problem.

  • Best tutorial out there for adding custom icons.