Extend ionic / add custom fonts/icons (ionic.config.json)

Hi community,

I would like to add Font-awesome to my Ionic2 app and I already found these instructions, but they are based on the old ionic.config.js and now I don’t get the clue how to do it with the new ionic.config.json.

Can anybody provide hint or has an example for this?
Or is there a guide in general howto extend with the new ionic.config.json?

@tim: in this post you mention it’s easier to extend now :slight_smile: Could you provide an example? I’m currently using beta22.

Kind regards


Sure thing! This should be more well documented, but here are the steps to using font-awesome:

npm install font-awesome

Then edit your gulpfile to add options to the sass and fonts tasks:

gulp.task('sass', function(){
  return buildSass({
    sassOptions: {
      includePaths: [

gulp.task('fonts', function(){
  return copyFonts({
    src: [

You can find more information on the gulp tasks here: https://github.com/driftyco/ionic-gulp-tasks.

Then you should be able to @import "font-awesome" in your app/theme/app.core.scss file and use it in your project wherever :grin:


Thank you very much @tim! It helped me a lot to understand how it is all glued together :slight_smile:

There are another two questions about the usage coming up:
Using ionicons works like a charm:
<ion-icon name="home"></ion-icon>

But how the following does not
<ion-icon name="fa-bullhorn"></ion-icon>
because it transformed to
<ion-icon aria-label="fa bullhorn" class="ion-ios-fa-bullhorn" role="img" name="fa-bullhorn"></ion-icon>
and the style class ion-ios-fa-bullhorn does not exist.

If I change it to <ion-icon aria-label="fa bullhorn" class="fa fa-bullhorn" role="img" name="fa-bullhorn"></ion-icon> the icon appears (in FF webdev console, just for trying).

I could also use a <span class="fa fa-bullhorn"></span>, or define specific css classes, or create an <fa-icon> component, but is this the desired way?

=> How should these custom icons be used correctly in ionic2?

In the app/theme/app.core.scss file:
@import "font-awesome"; -> complains about the file is not found

@import "../../node_modules/font-awesome/scss/font-awesome";-> seems fine

Maybe there is still something missing in the configuration? Fonts and stuff is copied fine by the gulp task.

Hmm, if Sass isn’t finding the import then there’s something wrong with the includePaths.

I wrote the gulp task from memory and didn’t test it so it’s possible there’s a typo here, but it’s not immediately apparent what it might be. Sometimes I forget to include sassOptions, is that it? Or did you leave your old ‘sass’ task in in addition to the new one? Just some ideas.

gulp.task('sass', function(){
  return buildSass({
    sassOptions: {
      includePaths: [

Regarding the ion-icon, I believe that component makes some assumptions about using Ionicons. @brandyshea any ideas on custom icons? I would maybe just set the fa class on an <i> or <span>.

So ion-icon is an Ionic component. You pass the name of the icon you want to use in the name property, and then it adds the class for that icon based on the mode. For example, if you pass heart:

<ion-icon name="heart"></ion-icon>

on iOS it would be:

<ion-icon class="ion-ios-heart"></ion-icon>

and for material design mode it would be:

<ion-icon class="ion-md-heart"></ion-icon>

So when you pass fa-* to the name property it will perform all of our logic. You should be able to use the i element for font awesome, like:

<i class="fa fa-heart"></i>



Thanks for your answers and great explanations!

  1. I remove the existing sass task and just replaced it with your example. The issues with the includePath were Webstorm specific. I am still trying different IDEs to find my favorite one.

  2. I used the provide example with the <i> element. That’s alright :slight_smile:

This has been a very helpful thread. I’m trying to implement the weather-icons font in my project. But I’m stuck because, unlike font-awesome, they use less. there is a pre-compiled css file however. Any clue how I can include it with the sass gulp task?

Hi @jasonwaters, I think it’s better to open separate topic for this question/issue, because I already marked this topic as solved.

Good Morning. I tried to carry out this step by step, but my project can not find the the Font Awesome files. He can find it in the folder node_modules still on the app icon appears only a square, as if he had not caught the family source.
In the ‘ionic serves’ it shows the message that failed to find or the file is unreadable.

Well that could have an official topic on the use of custom fonts, it is something that everyone uses.

Need help :confused:

@daniel_rf121 Have you added @import "font-awesome" in your app/theme/app.core.scss file? Have you updated both your sass and files tasks in gulpfile.js as explained in the following comment? Also make sure that you’re using them correctly, e.g.:

<i class="fa fa-heart"></i>

Yes, I performed all the steps. Font Awesome installed via NPM, then I added the codes in gulpfile and used the @import in the core. still displaying the error:

Starting ‘sass’…
Error: File to import not found or unreadable: font-awesome
Parent style sheet: /Users/danielrodrigues/Projects/funlife-ionic/app/theme/app.core.scss
on line 10 of app/theme/app.core.scss

@import “font-awesome”;

@daniel_rf121 Try importing it this way:

1 Like

Yes. So it works in the web browser. But when I deploy to a device does not work.

@daniel_rf121 Actually after looking closer at this, you should use only @import "font-awesome"; if you configured both sass and files tasks properly in gulpfile.js. Also note that you should not just add the code from the comment to your gulpfile.js - you have to replace the existing tasks with the same names (or delete these). And check if the FontAwesome font files are copied to your www/build/fonts folder.

See how is my gulpfile. The part that is highlighted is that we included.

var gulp = require('gulp'),
gulpWatch = require('gulp-watch'),
del = require('del'),
runSequence = require('run-sequence'),
argv = process.argv;

* Ionic hooks
* Add ':before' or ':after' to any Ionic project command name to run the specified
* tasks before or after the command.
gulp.task('serve:before', ['watch']);
gulp.task('emulate:before', ['build']);
gulp.task('deploy:before', ['build']);
gulp.task('build:before', ['build']);

// we want to 'watch' when livereloading
var shouldWatch = argv.indexOf('-l') > -1 || argv.indexOf('--livereload') > -1;
gulp.task('run:before', [shouldWatch ? 'watch' : 'build']);

* Ionic Gulp tasks, for more information on each see
* https://github.com/driftyco/ionic-gulp-tasks
* Using these will allow you to stay up to date if the default Ionic 2 build
* changes, but you are of course welcome (and encouraged) to customize your
* build however you see fit.
var buildBrowserify = require('ionic-gulp-browserify-typescript');
var buildSass = require('ionic-gulp-sass-build');
var copyHTML = require('ionic-gulp-html-copy');
var copyFonts = require('ionic-gulp-fonts-copy');
var copyScripts = require('ionic-gulp-scripts-copy');

var isRelease = argv.indexOf('--release') > -1;

gulp.task('watch', ['clean'], function(done){
        ['sass', 'html', 'fonts', 'scripts'],
            gulpWatch('app/**/*.scss', function(){ gulp.start('sass'); });
            gulpWatch('app/**/*.html', function(){ gulp.start('html'); });
            buildBrowserify({ watch: true }).on('end', done);

gulp.task('build', ['clean'], function(done){
        ['sass', 'html', 'fonts', 'scripts'],
                browserifyOptions: {
                    debug: !isRelease
            }).on('end', done);

+ gulp.task('sass', function(){
+   return buildSass({
+     sassOptions: {
+       includePaths: [
+         'node_modules/ionic-angular',
+         'node_modules/ionicons/dist/scss',
+         'node_modules/font-awesome/scss'
+       ]
+     }
+   });
+ });

+ gulp.task('fonts', function(){
+   return copyFonts({
+     src: [
+       'node_modules/ionic-angular/fonts/**/*.+(ttf|woff|woff2)',
+       'node_modules/font-awesome/fonts/**/*.+(eot|ttf|woff|woff2|svg)'
+     ]
+   });
+ });

gulp.task('sass', buildSass);
gulp.task('html', copyHTML);
gulp.task('fonts', copyFonts);
gulp.task('scripts', copyScripts);
gulp.task('clean', function(){
    return del('www/build');

@daniel_rf121 Both tasks are being redefined/reset at the end of the file, i.e. delete the following lines:

// ...

- gulp.task('sass', buildSass);
  gulp.task('html', copyHTML);
- gulp.task('fonts', copyFonts);
  gulp.task('scripts', copyScripts);
  gulp.task('clean', function(){
    return del('www/build');

Good evening my friend, I managed to make it work. I removed the lines you listed, deleted the build folder, then run the ionic serve command again. The gulp could import sources to the folder just right. Now I will try to make the import of icomoon.

Thanks a lot for the help.

1 Like

I followed the same steps, but using other type of font (google maven), which is local under my app folder. I then copied all the fonts with the gulp task to www/build/fonts.

In the app.variable I tried to set $font-family-base to have my custom font name.

When I run the app and debug it, my custom font is there, but current font-family is still the old one.

Any clue?


@tim @brandyshea
the projects, generated with the new ionic-cli 2.1, using ionic 2.0.0-rc.0 do not have gulpfile.js anymore. What is the way to add custom fonts and icons now?

I must use both font-awesome and other custom fonts in my application, so it’s really important to know how to do it with the new build process.


Edit: I found out that everything from the src/assets/ directory is already configured to be copied in the www/assets/ directory, so custom fonts can be just dropped there and referenced from the scss file.
Still wondering how to use fonts and scss from external libraries, installed with npm, like font-awesome.

1 Like

I do like this:

  1. Copy/paste font-awesome files (.ttf, .woff, .woff2) to src/assets/fonts directory.

  2. Copy/paste font-awesome.scss to src/theme of your app.

  3. Open font-awesome.scss and add below font-face instead of exist:

    @font-face {
    font-family: ‘FontAwesome’;
    src: url(’…/assets/fonts/fontawesome-webfont.eot?v=4.6.3’);
    src: url(’…/assets/fonts/fontawesome-webfont.eot?#iefix&v=4.6.3’) format(‘embedded-opentype’), url(’…/assets/fonts/fontawesome-webfont.woff2?v=4.6.3’) format(‘woff2’), url(’…/assets/fonts/fontawesome-webfont.woff?v=4.6.3’) format(‘woff’), url(’…/assets/fonts/fontawesome-webfont.ttf?v=4.6.3’) format(‘truetype’), url(’…/assets/fonts/fontawesome-webfont.svg?v=4.6.3#fontawesomeregular’) format(‘svg’);
    font-weight: normal;
    font-style: normal;

Notice: Your font-awesome version might be different from 4.6.3, so check it before copy!

  1. Open variables.scss file which is in the src/theme and import font-awesome like below:

@import "font-awesome";

  1. Done! :relaxed: You can use font-awesome classes in your app like below:

<ion-icon class="fa fa-heart"></ion-icon>