Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

A custom font in React Native falls back to the system font

ErrorText uses the default system font although fontFamily is set

Short answer

React Native does not report a missing font, it just draws the system font. Android looks for a file named exactly like your fontFamily in the app's assets/fonts folder. iOS wants the family or font name stored inside the file, listed in UIAppFonts. Check the name first, then the weight, then the build.

  • Applies to React Native 0.8x, Expo SDK 5x, Android 9 and later, iOS 17 and later
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the exact string you pass to fontFamily, and the exact name of the font file next to it. Almost every case is the two not matching on one platform. Then run the app: on iOS React Native logs a line about an unrecognized family when it cannot find the font, while Android quietly falls back to a system typeface.

    ls android/app/src/main/assets/fonts
    grep -rn "fontFamily" src/ | head -n 20
  2. 2Match what you see, then jump to its fix

    1. 1The font works on iOS only. Android shows the system font.Android: fontFamily is not the file nameFix
    2. 2The log shows Unrecognized font family followed by your string, and the text is drawn in the system font.iOS: fontFamily is not the name stored inside the fontFix
    3. 3Normal text uses the custom font and anything with fontWeight 700 or bold falls back to the system font.Android: bold text asks for a file the project does not haveFix
    4. 4The unrecognized-family line appears although the file name and the font name look right.iOS: the font file is not listed in UIAppFontsFix
    5. 5Expo Go shows the system font, or a change to the fonts list in the plugin has no effect on the installed app.Expo: the config plugin font is missing from the buildFix
    6. 6The first frame shows the system font, or the app shows a blank screen forever when a font fails.Expo: the screen renders before useFonts has finishedFix

What does the error look like?

  • Text uses the default system font although fontFamily is set
  • Unrecognized font family 'MyFont'
  • The font works on iOS and not on Android, or the other way round
  • Regular text uses the custom font, but text with fontWeight bold does not

Cause 1 of 6

Android: fontFamily is not the file name

1Check

In the React Native source, the Android font manager builds a file name from the fontFamily string and looks for fonts/<fontFamily>.ttf, then fonts/<fontFamily>.otf, in the app's assets. It compares nothing but the file name. A family name copied from the font's metadata does not help.

ls android/app/src/main/assets/fonts
# compare each file name, without the extension, to your fontFamily values

2Fix

Rename the file so its name without the extension is exactly the string you use in fontFamily, including capitals. Keep the file in the assets/fonts folder and rebuild.

android/app/src/main/assets/fonts/Poppins-Regular.ttf

// in the component
const styles = StyleSheet.create({
  title: { fontFamily: 'Poppins-Regular' },
});

3Verify

Rebuild the Android app. A change to native assets is not picked up by a JavaScript reload.

npx react-native run-android

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 6

iOS: fontFamily is not the name stored inside the font

1Check

On iOS the file name does not matter. React Native first treats the string as a family name, and when no family has that name it tries it as a font name. The names live inside the font file, not in its file name. Install the font on your Mac and read its family name in Font Book.

grep -rhno "fontFamily: '[^']*'" src/ | sort -u

2Fix

Use the family name or the font (PostScript) name exactly as the file reports it. If you name the file after its PostScript name, the same string also works on Android, which keys on the file name.

// file: Poppins-Bold.ttf, PostScript name: Poppins-Bold
title: { fontFamily: 'Poppins-Bold' },

3Verify

Rebuild the iOS app and check that the unrecognized-family line is gone from the Xcode console.

npx react-native run-ios

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 6

Android: bold text asks for a file the project does not have

1Check

The same font manager maps the requested weight to one of four styles. A weight of 700 or more is the bold style, and for it the lookup adds a suffix, so it opens fonts/<fontFamily>_bold.ttf or .otf. Two more suffixes exist, _italic and _bold_italic. If that file is missing the code uses a system typeface instead.

ls android/app/src/main/assets/fonts
grep -rn "fontWeight" src/ | head -n 20

2Fix

Either add a file named with the _bold suffix for that family, or give the bold face its own family string and stop setting fontWeight on it.

// Option 2: one family string per face, no fontWeight
body: { fontFamily: 'Poppins-Regular' },
heading: { fontFamily: 'Poppins-Bold' },

3Verify

Rebuild the Android app and look at a heading that used fontWeight before.

npx react-native run-android

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 4 of 6

iOS: the font file is not listed in UIAppFonts

1Check

The UIAppFonts array in Info.plist lists the app-specific font files that the system loads at runtime. Each entry is a file name including its extension, and the file must be in the app's bundle.

plutil -p ios/MyApp/Info.plist | grep -A 6 UIAppFonts

2Fix

Add every font file name, with extension, to UIAppFonts, and make sure Xcode includes the files in the app target.

<key>UIAppFonts</key>
<array>
  <string>Poppins-Regular.ttf</string>
  <string>Poppins-Bold.ttf</string>
</array>

3Verify

Rebuild the iOS app from Xcode or the CLI and check the Xcode console.

npx react-native run-ios

Confirmed by developer.apple.com

Did this fix it?

Cause 5 of 6

Expo: the config plugin font is missing from the build

1Check

The expo-font config plugin embeds fonts into the native project. Expo says it does not work in Expo Go, and that after adding the plugin you create a new development build and install it. On Android the file name without extension becomes the family name, on iOS the name is read from the font file.

grep -n -A 8 "expo-font" app.json

2Fix

Make a new development build after adding or changing the plugin, then use the platform's family name. Naming each file after its PostScript name gives one string that works on both platforms.

// app.json
"plugins": [
  ["expo-font", { "fonts": ["./assets/fonts/FiraSans-MediumItalic.ttf"] }]
]

// component: file name without the extension
title: { fontFamily: 'FiraSans-MediumItalic' },

3Verify

Install the new development build, open the screen, and check that the plugin entry is in the config the build used.

grep -n -A 6 "expo-font" app.json

Confirmed by docs.expo.dev

Did this fix it?

Cause 6 of 6

Expo: the screen renders before useFonts has finished

1Check

With the useFonts hook the fonts load at runtime, so the text can draw before they are ready. Expo pairs the hook with the splash screen: keep it visible until the hook reports loaded or error.

grep -rn "useFonts" app/ src/ 2>/dev/null

2Fix

Hold the first render back until fonts are ready, and hide the splash screen when loaded or error becomes true. Call the hook from a top-level component such as the root layout.

SplashScreen.preventAutoHideAsync();

export default function RootLayout() {
  const [loaded, error] = useFonts({
    'Inter-Black': require('./assets/fonts/Inter-Black.otf'),
  });

  useEffect(() => {
    if (loaded || error) {
      SplashScreen.hideAsync();
    }
  }, [loaded, error]);

  if (!loaded && !error) {
    return null;
  }
  // ...render the app
}

3Verify

Cold start the app: the first visible frame already uses the custom font.

grep -rn "preventAutoHideAsync\|hideAsync" app/ src/ 2>/dev/null

Confirmed by docs.expo.dev

Did this fix it?

How do I stop it coming back?

  • Name every font file after its PostScript name and use that string in fontFamily on both platforms.
  • Keep fonts in one folder and list them in one place, so a new font cannot be added to only one platform.
  • Use one family string per face instead of fontWeight on custom fonts.
  • Rebuild the native app after any change to font files; a JavaScript reload does not reach them.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.