This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 52).
A library that allows loading fonts at runtime and using them in React Native components.
expo-font
allows loading fonts from the web and using them in React Native components. See more detailed usage information in the Fonts guide.
-
npx expo install expo-font
If you are installing this in an existing React Native app, start by installing expo
in your project. Then, follow the additional instructions as mentioned by the library's README under "Installation in bare React Native projects" section.
The recommended way to add fonts to your app is through expo-font
built-in config plugin if you use config plugins in your project (EAS Build or npx expo run: [android|ios]
). The plugin allows you to embed font files at build time which is more efficient than using loadAsync
. See the Fonts guide on how to use it.
{
"expo": {
"plugins": [
[
"expo-font",
{
"fonts": ["path/to/file.ttf"]
}
]
]
}
}
Name | Default | Description |
---|---|---|
fonts | [] | An array of font files to link to the native project. The paths should be relative to the project root. The file names will become the font family names on Android. On iOS, the font family name may not be the same as the file name — use |
import { useFonts } from 'expo-font';
import * as SplashScreen from 'expo-splash-screen';
import { useEffect } from 'react';
import { Text, View, StyleSheet } from 'react-native';
SplashScreen.preventAutoHideAsync();
export default function App() {
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;
}
return (
<View style={styles.container}>
<Text style={{ fontFamily: 'Inter-Black', fontSize: 30 }}>Inter Black</Text>
<Text style={{ fontSize: 30 }}>Platform Default</Text>
</View>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
},
});
import * as Font from 'expo-font';
useFonts(map)
Parameter | Type | Description |
---|---|---|
map | string | Record<string, FontSource> | A map of |
[boolean, null | Error]
boolean
) - A boolean to detect if the font for fontFamily
has finished
loading.Error | null
) - An error encountered when loading the fonts.getLoadedFonts()
Synchronously get all the fonts that have been loaded.
This includes fonts that were bundled at build time using the config plugin, as well as those loaded at runtime using loadAsync
.
string[]
Returns array of strings which you can use as fontFamily
style prop.
isLoaded(fontFamily)
Parameter | Type | Description |
---|---|---|
fontFamily | string | The name used to load the |
Synchronously detect if the font for fontFamily
has finished loading.
boolean
Returns true
if the font has fully loaded.
isLoading(fontFamily)
Parameter | Type | Description |
---|---|---|
fontFamily | string | The name used to load the |
Synchronously detect if the font for fontFamily
is still being loaded.
boolean
Returns true
if the font is still loading.
loadAsync(fontFamilyOrFontMap, source)
Parameter | Type | Description |
---|---|---|
fontFamilyOrFontMap | string | Record<string, FontSource> | String or map of values that can be used as the |
source (optional) | FontSource | The font asset that should be loaded into the |
An efficient method for loading fonts from static or remote resources which can then be used
with the platform's native text elements. In the browser, this generates a @font-face
block in
a shared style sheet for fonts. No CSS is needed to use this method.
Note: We recommend using the config plugin instead whenever possible.
Promise<void>
Returns a promise that fulfils when the font has loaded. Often you may want to wrap the
method in a try/catch/finally
to ensure the app continues if the font fails to load.
FontResource
An object used to dictate the resource that is loaded into the provided font namespace when used
with loadAsync
.
Name | Type | Description |
---|---|---|
default (optional) | string | - |
display (optional) | FontDisplay | Only for: Web Sets the |
uri (optional) | string | number | - |
FontSource
Literal Type: multiple types
The different types of assets you can provide to the loadAsync()
function.
A font source can be a URI, a module ID, or an Expo Asset.
Acceptable values are: string
| number
| Asset
| FontResource
FontDisplay
Sets the font-display
for a given typeface. The default font value on web is FontDisplay.AUTO
.
Even though setting the fontDisplay
does nothing on native platforms, the default behavior
emulates FontDisplay.SWAP
on flagship devices like iOS, Samsung, Pixel, etc. Default
functionality varies on One Plus devices. In the browser this value is set in the generated
@font-face
CSS block and not as a style property meaning you cannot dynamically change this
value based on the element it's used in.
FontDisplay Values
AUTO
FontDisplay.AUTO = "auto"
(Default) The font display strategy is defined by the user agent or platform. This generally defaults to the text being invisible until the font is loaded. Good for buttons or banners that require a specific treatment.
BLOCK
FontDisplay.BLOCK = "block"
The text will be invisible until the font has loaded. If the font fails to load then nothing will appear - it's best to turn this off when debugging missing text.
FALLBACK
FontDisplay.FALLBACK = "fallback"
Splits the behavior between SWAP
and BLOCK
.
There will be a 100ms timeout
where the text with a custom font is invisible, after that the text will either swap to the
styled text or it'll show the unstyled text and continue to load the custom font. This is good
for buttons that need a custom font but should also be quickly available to screen-readers.
OPTIONAL
FontDisplay.OPTIONAL = "optional"
This works almost identically to FALLBACK
, the only difference is that the browser will
decide to load the font based on slow connection speed or critical resource demand.
SWAP
FontDisplay.SWAP = "swap"
Fallback text is rendered immediately with a default font while the desired font is loaded. This is good for making the content appear to load instantly and is usually preferred.
Code | Description |
---|---|
ERR_FONT_API | If the arguments passed to loadAsync are invalid. |
ERR_FONT_SOURCE | The provided resource was of an incorrect type. |
ERR_WEB_ENVIRONMENT | The browser's document element doesn't support injecting fonts. |
ERR_DOWNLOAD | Failed to download the provided resource. |
ERR_FONT_FAMILY | Invalid font family name was provided. |
ERR_UNLOAD | Attempting to unload fonts that haven't finished loading yet. |