Phonegap for iOS: The Definitive Guide to Using Custom Fonts

Last Friday inspiration struck – I was tired of having to look up the phase of the moon every time I wanted to know when the next full moon was so I decided to make an app for that. Not knowing Objective C or anything about iOS development I decided to create it as a mobile web app with Angular on the front end talking to a simple Sinatra backend. It worked out better than I thought and people liked the app so I decided I would turn it into a native iOS app. That’s where Phonegap comes in.

It was really easy to port all of my code over to Phonegap then build and run the new app in the emulator. But there was just one problem: the icon font and Google Web Font I was using refused to work. After an entire day of digging (most people go longer) and literally hundreds of posts on the topic that were outdated and/or incorrect I finally figured out how to make it work. This is how to get custom fonts working in a Phonegap 3.4.0 app meant for iOS.

UPDATE: Since this was written in 2014 I appears things have changed and you no longer need to go through all these steps. Please see the comments at the end of this post as many have added alternative methods. I’m leaving this here in case there’s some edge case where these steps are necessary or the commenters are wrong.

NOTE: I built this app using the Yeoman Angular Phonegap Generator. If you’re putting this together differently please always read the official docs for the most up to date information.

Phase 0: Setup

Before we begin, let me tell you about my setup as different versions of this software could make things slightly different for you. I’m running:

  • Mac OS X 10.9 Mavericks
  • Xcode 5.1.1
  • Phonegap 3.4.0
  • AngularJS, Grunt, and Bower (but this stuff isn’t as important to this)

Phase 1: Installing custom fonts for the compiled app

Getting to use your custom fonts is actually pretty simple. Follow these steps:

  1. Go to your platforms/ios/AppName/Resources folder

  2. Drop the original font files you wish to use into this folder (be aware of licensing issues)

  3. In your AppName-Info.plist file you’ll want to add the following lines:


At this point you should be aware of a few things:

  • Font file names should be entered exactly as they appear in the Finder including the extension

  • iOS only supports True Type and Open Type fonts (.ttf and .otf)

Once this is done, you should see some new items in your app info pane in Xcode. Open your project in Xcode and click on the target for which you want to use custom fonts and then click on the info tab like so:

Your new fonts should show up

If you saved your AppName-Info.plist file with the new array from step 3 then you should see a new item under “Custom iOS Target Properties” called “Fonts provided by application”. If you expand this item you should see each of the font files you added to your Resources folder.

Most articles and tutorials online will have you stop here. But there’s more to it and that’s what trips everyone up!

Now you need to go into the Build Phases tab and expand the “Copy Bundle Resources” item. At the bottom of that list you’ll see a little plus sign. Click it because you need to add some resources. A dialog box will open letting you select the files you want to copy into the app. Just go to platforms/ios/AppName/Resources/ in your project and select the files you just copied there in step 2. You can select multiple files by holding down Command and clicking each file you added. Click Next (or Finish or whatever the Continue button actually says) and then another dialog box will show up. I checked the first checkbox that was originally unchecked and left the rest of the settings the way they are and clicked through to finish.

If all went well you should now see your font files in the list:

Your font files will show here when you finish

Now you can really use custom fonts in your app. But wait! There’s still another catch! Yes, there’s even more that could trip you up at this point. Normally when we write CSS we’re used to either picking a font-family name ourselves (when using @font-face) or using the font family name given to use by the font provider (like Google Web Fonts). This won’t always work in the compiled app even if it works when running the app on a local server.

Phase 2: Double-check Font Family References

The reason installed fonts may not work still is because sometimes what a font specifies as it’s font family in the font file differs from what we use in our CSS. So, in my case I was using a custom icon font created with Fontello along with a font I got from Google’s Web Font service. In order to make sure the fonts show up when running the app on a local server and in the iOS emulator I had to change the @font-face declarations a bit.

Your compiled app will only know your fonts by their formal name specified in the font file. So the first step to figuring out how to modify your @font-face declaration is to open up Font Book, expand the name of the font, and click on the style you plan to use and have loaded into your app’s Resources folder (you’ll need the font installed locally on your system to be able to do this).

Now, click on the info button (shown below) to get the details about your font. You’ll want to look at what the “Font Family” item says (also shown below). That’s what you need to use when you call your font in your CSS.

Font info screen in Font Book

Once this is done for each custom font you’re using you should go through your stylesheets and make sure that any font-family declarations use that exact name (capital letters and all).

Now, if you followed all the steps correctly so far, you should be able to build and run your app in the simulator and see your custom fonts in action. Unfortunately, that’s still not always enough.

Phase 3: Custom fonts simultaneously on localhost and in the build

Because we’re using Phonegap we have the luxury of being able to run our app on a local server to some extent and see our design changes quickly. Even though we’ll be seeing our fonts in the compiled version of the app the changes we just made may not work if you try to develop on a local server. To fix this, we just need to fix our @font-face declarations.

Although you have a copy of your fonts in the app’s Resources folder you’ll still need another copy of them in your working directory just like you would had you been developing a website or web app. I always keep my fonts in a /font/ folder for websites. To make the fonts work with the new font-family name (if you had to change it at all) you need to host all custom fonts yourself. The reason for this is because font services don’t let you change the name by which you reference your fonts in a @font-face declaration. Google Web Fonts allows you to download the actual font files. Other providers may vary.

Before we move on, there’s one exception to this. In my case, I was using Source Sans Pro as one of my fonts which is hosted by Google Web Fonts. I have the font files in my Resources folder for my compiled app to use but I also have a reference to the file in my HTML page uses the <link /> tag Google gives you. Because the font file specifies the Font Family as “Source Sans Pro” and Google references the font family by the same exact name, I didn’t have to host that particular font locally. However, for my Fontello icon font, I did have to go through the following procedure.

  1. Above all else, do NOT change the font-family declarations in your CSS once you’ve got the font showing up in the compiled app running on your phone or the iOS simulator. Keep it as it is. You only need to change the font-family property in your @font-face declarations.

  2. Although you already have a copy of your font in your app’s Resources folder, you’ll need a duplicate copy of each font you want to see when running your app from a local web server. So create another copy of those fonts in your working directory (I choose /fonts/). When I say “working directory” I mean the directory that a web server would serve files from and that Phonegap creates a copy of during the build process.

  3. Now that you know the proper font-family you need to reference in order to see your fonts work in the compiled app, create or change any existing @font-face declarations using the following template:

@font-face {
    font-family:'Proper Font Family Name From Phase 2';
    src: url('../relative/path/to/webfont-file.eot');
    src: url('../relative/path/to/webfont-file.eot?#iefix') format('embedded-opentype'),
         url('../relative/path/to/webfont-file.woff') format('woff'),
         url('../relative/path/to/webfont-file.ttf') format('truetype');
    font-weight: normal;
    font-style: normal;

2a. I cannot stress this enough: DO NOT reference the Resources folder in your @font-face declarations. You need a duplicate copy of the font files in a path accessible by your web server. We’re assuming here that we’ll be developing the app on localhost with MAMP, XAMPP, or in Grunt server.

  1. Change the @font-face declaration for each custom font you need to use. That’s it.

Now you should be able to see your custom font when running the app on your local server and when you build and run it on the iOS simulator.

The reason this works is because the font-family is now standardized. So when running the compiled app on an iOS device or in the simulator the app will ignore the font files referenced in the CSS and instead use the ones you specified in your app’s configuration in Xcode like we did in the first couple of steps. When you run the app on a local server, those same font-family names sill apply and will work because you’ve told the browser what the path to the font file that corresponds to the font name you’re using is.

To put it simply, the compiled app (basically) ignores your @font-face rules and uses the built-in fonts you provided. Any server you run it on will follow the @font-face rules.

You may wonder if there’s a performance hit when doing things this way. Maybe there is a cost to having those extra font rules in your CSS when the compiled app doesn’t need them but my opinion is that the performance hit is worth the convenience of being able to develop on a local server and preview your work before compiling. Without this process you’d have to compile your app after every little change in order to see your design with the custom font in use.

I was incredibly surprised by how few resources there are out there explaining how to do this so I have to give credit where credit is due. The one and only blog post that actually helped me figure this out resides here. That blog post is responsible for helping me figure out the second part of editing the app .plist file to use the custom fonts which is the part where you edit the resources to copy into your bundle.

Digital Ocean Affordable VPS hosting

Web development, iOS development

« Create a Weather App with Sinatra and AngularJS - Part 1 The Importance of Having a Git Branching Strategy »