A custom font in React Native falls back to the system font
Text uses the default system font although fontFamily is setShort 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.
Fix it fast
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 202Match what you see, then jump to its fix
- 1
The font works on iOS only. Android shows the system font.Android: fontFamily is not the file nameFix - 2
The 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
Normal 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
The unrecognized-family line appears although the file name and the font name look right.iOS: the font file is not listed in UIAppFontsFix - 5
Expo 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
The 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
- 1
What does the error look like?
Text uses the default system font although fontFamily is setUnrecognized font family 'MyFont'The font works on iOS and not on Android, or the other way roundRegular 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 values2Fix
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-androidConfirmed by raw.githubusercontent.com
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 -u2Fix
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-iosConfirmed by raw.githubusercontent.com
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 202Fix
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-androidConfirmed by raw.githubusercontent.com
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 UIAppFonts2Fix
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-iosConfirmed by developer.apple.com
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.json2Fix
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.jsonConfirmed by docs.expo.dev
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/null2Fix
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/nullConfirmed by docs.expo.dev
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:
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Mobile apps
Axios request works on iOS or in a browser but fails on Android with Network Error
AxiosError: Network Error
A React Native app has no CORS, so on Android a Network Error usually means the request never reached the server.
3 causes, each with a fixMobile apps
Axios returns Network Error in a React Native app on iPhone or the iOS Simulator
error.code is ERR_NETWORK and error.response is undefined
A Network Error means iOS stopped the request before any HTTP answer came back.
3 causes, each with a fixMobile apps
backgroundImage: url(...) does nothing in a React Native view
ImageBackground renders an empty area
In React Native the backgroundImage style draws linear and radial gradients, not pictures, so url(...) is ignored.
3 causes, each with a fixMobile apps
fetch fails with TypeError: Network request failed in React Native
Network request failed
Network request failed means the request never got an HTTP response, so there is no status code to read.
3 causes, each with a fixMobile apps
react-native-geolocation-service getCurrentPosition fails or never returns
Location provider not available
Read the error code in the callback.
5 causes, each with a fixMobile apps
A remote image in React Native shows nothing, or only for some URLs
The same component works with one URL and stays blank with another
A network image in React Native is blank for four reasons.
4 causes, each with a fix