React Native Custom Icon Font With No Sad Red Screen

Kelley Rose
Jan 11, 2018 · 8 min read

This is a step by step guide for adding a custom icon font to your React Native project using react-native-vector-icons. Look out for the BIG TIPS, which will help you pay attention to the details that sometimes fall between the cracks. You can find basic instructions in react-native-vector-icons’ docs… this here is a more in depth look.

I’m not going to split this up by iOS and Android, because when I set up configuration for my apps, I tend to both at the same time.

Are you troubleshooting only?

See troubleshooting tips at the bottom if you’ve already tried installing your custom icon font, but are seeing a red screen and/or ‘Unrecognized font family…’

Let’s start!


I recommend this because generally speaking, if I have anything running, I will start seeing red screens and that raises my blood pressure, so best to wait until it’s all set up.

Step 0: React Native Vector Icons install and link

Make sure you have react-native-vector-icons installed and linked. If you haven’t installed it yet, follow install instructions from their docs. Usually these two commands should do it for you.

npm install react-native-vector-icons --savereact-native link

I would double check this is working before you move on.


Fontello is the custom icon font provider I’ve found to be the friendliest, so that’s what I’ll be using.

Note: You can use Fontello even if your design team hands off an icon font from another provider… you can just add the font file as mentioned below.

Step 1: Add icons in Fontello

First, you have to get your icons into a font. Go to, and as their UI so accurately suggests, ‘Drag custom SVG icons or SVG font here’.

Drag and drop individual icons or an SVG font file

Step 2: Select icons

This might not be as obvious, but after you upload the icons, you have to select which you want to include (one by one). This is nice because you can choose icons from other libraries if you want to and they’ll all be a part of your one icon font. You’ll see your selections clearly with a red circle.

Selected fonts for my custom icon font


I recommend naming your font in the little box next to the big red button in Fontello. This way there won’t be any questions what your font name is. And the file name will match the font name, so you can use the same name in iOS and Android leaving less room for error — phew.

Step 4: Download webfont

Click the red ‘Download webfont’ button in top right. You can get the config file on its own by clicking the down arrow, but you’ll need the .ttf file as well.

Step 5: Add .ttf file to project

Find the .ttf file in the fonts directory from your download and add it somewhere in your src file that makes sense. I usually have a src/assets/fonts directory that I use. I like to have this file accessible somewhere in a shared file for my own sanity.

Step 6 (iOS): Add .ttf to Resources in Xcode

Open the project in Xcode ios/yourprojectname.xcodeproj. Once in Xcode, right click on the resources directory, select ‘Add files to “yourprojectname”…’ and select the custom icon font .ttf file (I have mine available in that src/assets/fonts directory I mention in step 5).


While still in Xcode, go to ‘Build Phases’ in the top bar, open ‘Copy Bundle Resources’ and you’ll see a list of the icon fonts from react-native-vector-icons. Check for your icon font name in that list, if it’s not there, click the ‘+’ and select your .ttf file.

I have this listed as a big tip, because, while it’s not really just a tip as much as it is a required step, if you’re troubleshooting why your icons aren’t working, this could be a reason.

Sometimes you won’t have to add this, sometimes you will. Idk.


Open your info.plist file (preferably before you add any additional targets, because this is the info.plist that will get copied) and open ‘Fonts provided by application. Click the little circled ‘+’. It’ll add a line at the top for you to type in your font file name.

I have this listed as a big tip, because, while it’s not really just a tip as much as it is a required step, if you’re troubleshooting why your icons aren’t working, this could be a reason.

Before my custom font is added
Type file name exactly as is

Step 9 (Android): Add .ttf to Android

Add the .ttf file to theandroid/app/src/main/assets/fonts directory. This should already exist because you’ve already installed react-native-vector-icons and run react-native link which places all it’s icon font files here for Android.

Step 10: Add configuration and the icon component to your project

Back to the shared src directory! Add two files somewhere in your shared src directory called icon-font.js and icon-font.json or whatever you want to call them. I like to have a src/config directory for (you guessed it) configuration stuff.

Go back to the files you downloaded from Fontello, grab the config.json contents and paste them into your icon-font.json file.

Open your icon-font.js file and paste the following (replacing kelleyicons with whatever you named your custom icon font of course).

import { createIconSetFromFontello } from 'react-native-vector-icons';
import fontelloConfig from './icon-font.json';
const Icon = createIconSetFromFontello(fontelloConfig, 'kelleyicons');
export default Icon;

Step 11: Add instance for testing

Before running the app, go ahead and add an instance of your icon font somewhere so you can double check it’s working right off the bat. In any of your component or screen files, import your icon from the icon-font.js file.

import MyIcon from './../config/icon-font.js';

And in your view somewhere, use it like so. You can find the individual names to use in the icon-font.json file.

color={'#333333'} />

Step 12: Save, run and (hopefully) celebrate!

Make sure everything is saved up, go to your terminal, run npm start, open your app, and cross your fingers for zero errors!

Please work, please work, please work

Get excited when there isn’t a red screen, and your icon shows up! Woohoo!

Custom Chrome icon from my Fontello file. Weeeeee!

Final Notes (troubleshooting tips further below)

You can add the shared files before you add the platform specific font files to their respective directories. Whichever order you prefer will work.

The biggest causes of the red screen for me in the past have been making sure I have the font file added and referenced correctly in Xcode, so I made myself a sticky note (by now I think it’s engrained in my brain however) with the information.

  1. Have .ttf in Resources directory
  2. Font file added to Copy Bundle Resource in Build Phases
  3. Font file added to list of fonts used in project in info.plist

Hopefully you’re up and running with a custom icon font now. If you’re having issues, see some troubleshooting tips below. Have fun building! ❤

My reminder to myself for custom icon fonts (or regular fonts too) :)


1: Are you using the correct font name?

Check the font name matches your icon font component file where you define your icon component. In the code below ‘kelleyicons’ is the name of my font and the name of my font file name.

Note: iOS uses the font name and Android uses the font file name for declaring fonts — best to make sure your file name and font name match in this situation.

const Icon = createIconSetFromFontello(fontelloConfig, 'kelleyicons');

Don’t know the name of your font? If you used Fontello, you should see the font name as the first line of code after the opening bracket inside the config.json file. If not, try opening the .ttf file in font book on a Mac to get the name.

Or you can add the following code to your AppDelegate.m file in Xcode, run the app, and see the list of available fonts logged in the Xcode console. Be sure to use the name exactly as it is in this logged list when you are defining your icon component (and make sure the font file in your Android directory uses this same name as well).

for (NSString* family in [UIFont familyNames])
NSLog(@"%@", family);

for (NSString* name in [UIFont fontNamesForFamilyName: family])
NSLog(@" %@", name);

2: iOS | Have you referenced the font everywhere necessary?

Double check these three locations in Xcode.

  1. Resources directory should include the custom icon font .ttf file.
  2. Target Build Phases > Copy Bundle Resources > Should see your custom icon font file name in list
  3. Info.plist > Fonts provided by application > Should see your custom icon font file name in list (click ‘+’ if not, and add file name)

3: Android | Have you added the font file in the correct location?

Make sure the .ttf file is in android/app/src/main/assets/fonts and has the exact same file name as your icon font.

Thanks for reading! If you found this article helpful, give me some claps 👏.

Also, if you have any thoughts around this content, be sure to comment. I’m always open to gathering information from others.

Happy React Native developing friends! ❤

Kelley Rose

Written by

Developing is my craft, design is my recreation, learning is my always and forever. Developer @digitalscience.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade