expo-font
allows loading fonts from the web and using them in React Native components. See more detailed usage information in the Fonts guide.Android Device | Android Emulator | iOS Device | iOS Simulator | Web |
---|---|---|---|---|
→
expo install expo-font
If you're installing this in a bare React Native app, you should also follow these additional installation instructions.
import * as React from 'react'; import { View, Text, StyleSheet } from 'react-native'; import { useFonts } from 'expo-font'; export default function App() { const [loaded] = useFonts({ Montserrat: require('./assets/fonts/Montserrat.ttf'), }); if (!loaded) { return null; } return ( <View style={styles.container}> <Text style={{ fontFamily: 'Montserrat', fontSize: 30 }}>Montserrat</Text> </View> ); } %%placeholder-start%%const styles = StyleSheet.create({ ... }); %%placeholder-end%%const styles = StyleSheet.create({ container: { flex: 1, backgroundColor: '#fff', alignItems: 'center', justifyContent: 'center', }, });
import * as React from 'react'; import { Text, View, StyleSheet } from 'react-native'; import * as Font from 'expo-font'; export default class App extends React.Component { state = { fontsLoaded: false, }; async loadFonts() { await Font.loadAsync({ // Load a font `Montserrat` from a static resource Montserrat: require('./assets/fonts/Montserrat.ttf'), // Any string can be used as the fontFamily name. Here we use an object to provide more control 'Montserrat-SemiBold': { uri: require('./assets/fonts/Montserrat-SemiBold.ttf'), display: Font.FontDisplay.FALLBACK, }, }); this.setState({ fontsLoaded: true }); } componentDidMount() { this.loadFonts(); } render() { // Use the font with the fontFamily property after loading if (this.state.fontsLoaded) { return ( <View style={styles.container}> <Text style={{ fontSize: 20 }}>Default Font</Text> <Text style={{ fontFamily: 'Montserrat', fontSize: 20 }}>Montserrat</Text> <Text style={{ fontFamily: 'Montserrat-SemiBold', fontSize: 20 }}> Montserrat-SemiBold </Text> </View> ); } else { return null; } } } %%placeholder-start%%const styles = StyleSheet.create({ ... }); %%placeholder-end%%const styles = StyleSheet.create({ container: { flex: 1, backgroundColor: '#fff', alignItems: 'center', justifyContent: 'center', }, });
import * as Font from 'expo-font';
string | Record<string, FontSource>
) - A map of fontFamily
s to FontSource
s. After loading the font you can
use the key in the fontFamily
style prop of a Text
element.const [loaded, error] = useFonts({ ... });
Load a map of fonts with loadAsync
. This returns a boolean
if the fonts are
loaded and ready to use. It also returns an error if something went wrong, to use in development.
Note, the fonts are not "reloaded" when you dynamically change the font map.
string
) - The name used to load the FontResource
.Synchronously detect if the font for fontFamily
has finished loading.
string
) - The name used to load the FontResource
.Synchronously detect if the font for fontFamily
is still being loaded.
string | Record<string, FontSource>
) - string or map of values that can be used as the fontFamily
style prop with React Native Text elements.FontSource
) - the font asset that should be loaded into the fontFamily
namespace.Highly 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.
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.
null | string
) - Name of font to process.Used to transform font family names to the scoped name. This does not need to be called in standalone or bare apps but it will return unscoped font family names if it is called in those contexts.
string | Record<string, UnloadFontOptions>
) - The name or names of the custom fonts that will be unloaded.UnloadFontOptions
) - When fontFamilyOrFontMap
is a string, this should be the font source used to load
the custom font originally.Unload custom fonts matching the fontFamily
s and display values provided.
Because fonts are automatically unloaded on every platform this is mostly used for testing.
An object used to dictate the resource that is loaded into the provided font namespace when used
with loadAsync
.
Name | Type | Description |
---|---|---|
display (optional) | FontDisplay | Web Only. Sets the font-display property for a given typeface in the
browser. |
uri | string | number | - |
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
.
Web Only. 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.
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.FontDisplay.AUTO = "auto"
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.FontDisplay.BLOCK = "block"
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.FontDisplay.FALLBACK = "fallback"
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.FontDisplay.OPTIONAL = "optional"
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.FontDisplay.SWAP = "swap"
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. |