This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Learn how to integrate custom fonts in your app using local files or Google Font packages

Android and iOS come with their own set of platform fonts. To provide a consistent user experience and enhance your app's branding, you can use custom fonts.

This guide covers different ways you can add and load a custom font into your project and also provides additional information related to fonts.

Add a custom font

There are two ways you can add a custom font into your project:

• Add a font file into your local assets. For example, a font file in the assets/fonts directory.
• Install a Google Font package. For example, installing @expo-google-fonts/inter package.

Supported font formats

Expo SDK officially supports OTF and TTF font formats across Android, iOS and web platforms. If your font is in another font format, you have to set up advanced configuration to support that format in your project.

Variable fonts

A variable font holds many faces in one file. Instead of shipping one file per weight, you ship one file and select a face with the fontWeight and fontStyle style props. Both the config plugin and the useFonts hook accept variable fonts.

Android and iOS support variable fonts in SDK 58 and later. On earlier versions, use static font files.

Each platform decides which faces a file offers in a different way, so check the file before you rely on it:

• Android reads the wght axis and draws each weight fontWeight can name from it, limited to the range the axis declares. This needs Android 10 or later. On earlier versions the font renders at its default weight, and Android creates the bold by thickening the letters.
• iOS reads the named instances the file declares. A named instance is a face the font designer gave a name and a fixed position on each axis, such as "Bold" or "Condensed Light". React Native selects the named instance whose weight is closest to the one you request. A weight that no named instance covers is out of reach. If the file declares no named instances, only its default face renders.

For fontStyle: 'italic', Android applies the font's ital axis on Android 15 and later. On earlier versions, Android creates the italic by slanting the upright letters. iOS uses the italic named instances in the file.

On React Native 0.88 (Expo SDK 58) and later, you can also set any axis directly on a component with the fontVariationSettings style prop, such as fontVariationSettings: "'wght' 650, 'wdth' 90". It works on <Text> and <TextInput> on both platforms (Android 8 and newer), and the axes you set there take precedence over fontWeight and fontStyle.

Inspect a file's axes and named instances with a utility such as fontTools. If a face you need is out of reach on a platform, use fontTools to extract that axis configuration and save it as a separate static font file.

How to choose between OTF and TTF

If the font you're using has both OTF and TTF versions, prefer OTF. The .otf files are smaller than .ttf files. Sometimes, OTF also renders slightly better in certain contexts.

Use a local font file

Copy the file into your project's assets/fonts directory.

assets/fonts directory path is a common convention in React Native apps to put font files. You can place these files elsewhere if you follow a custom convention.

Two ways to use the local font file in your project:

• Embed the font file with expo-font config plugin (Android and iOS only).
• Load the font file with useFonts hook at runtime (Android, iOS, and web).

With expo-font config plugin

The expo-font config plugin allows embedding one or more font files in your project's native code. It supports ttf and otf for both Android and iOS, and woff and woff2 are supported on iOS only.

Note: Config plugins only run on native platforms (Android and iOS). For web, use the useFonts hook instead.

This is the recommended method for adding fonts to your app due to its benefits:

• Fonts are available immediately when the app starts on a device.
• No additional code required to load fonts in a project asynchronously when the app starts.
• Fonts are consistently available across all devices where the app is installed because they're bundled within the app.

However, this method also has some limitations:

• Doesn't work with Expo Go since this method requires creating a development build.

To embed a font in a project, follow the steps below:

{
  "expo": {
    "plugins": [
      [
        "expo-font",
        {
          "fonts": [
            "./assets/fonts/FiraSans-MediumItalic.ttf"
          ],
          "android": {
            "fonts": [
              {
                "fontFamily": "Inter",
                "fontDefinitions": [
                  {
                    "path": "./assets/fonts/Inter-BoldItalic.ttf",
                    "weight": 700,
                    "style": "italic"
                  },
                  {
                    "path": "./assets/fonts/Inter-Bold.ttf",
                    "weight": 700
                  }
                ]
              },
              {
                "fontFamily": "Roboto Flex",
                "path": "./assets/fonts/RobotoFlex.ttf",
                "fontDefinitions": [
                  { "weight": 400 },
                  { "weight": 700 },
                  { "weight": 400, "style": "italic", "axes": { "slnt": -10 } }
                ]
              }
            ]
          },
          "ios": {
            "fonts": [
              "./assets/fonts/Inter-Bold.ttf",
              "./assets/fonts/Inter-BoldItalic.ttf",
              "./assets/fonts/RobotoFlex.ttf"
            ]
          }
        }
      ]
    ]
  }
}

<Text style={{ fontFamily: 'Inter', fontWeight: '700' }}>Inter Bold</Text>
<Text style={{ fontFamily: 'Inter', fontWeight: '700', fontStyle: 'italic' }}>Inter Bold Italic</Text>
<Text style={{ fontFamily: 'FiraSans-MediumItalic' }}>Fira Sans Medium Italic</Text>
<Text style={{ fontFamily: 'Roboto Flex', fontWeight: '400', fontStyle: 'italic' }}>Roboto Flex Italic</Text>

How to determine which font family name to use

• If you provide fonts as an array of file paths (as described above), on Android, the file name (without the extension) becomes the font family name. On iOS, the font family name is read from the font file itself. We recommend naming the font file same as its PostScript name so the font family name is consistent on both platforms.

• If you use the object syntax, provide the "Family Name". This can be found in the Font Book app on macOS, fontdrop.info or other programs.

What is PostScript name of a font file?

The PostScript name of a font file is a unique identifier assigned to the font that follows Adobe's PostScript standard. It is used by operating systems and apps to refer to the font. It is not a font's display name.

For example, Inter Black font file's PostScript name is Inter-Black.

Screenshot from Font Book app on macOS.

With useFonts hook

The useFonts hook from expo-font library allows loading the font file asynchronously. This hook keeps track of the loading state and loads the font when an app is initialized.

It works with all Expo SDK versions and with Expo Go. To load a font in a project using useFonts hook, follow the steps below:

import { useFonts } from 'expo-font';
import * as SplashScreen from 'expo-splash-screen';
import {useEffect} from 'react';

SplashScreen.preventAutoHideAsync();

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

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

  if (!loaded && !error) {
    return null;
  }

  return (
    %%placeholder-start%%... %%placeholder-end%%
  )
}

<Text style={{ fontFamily: 'Inter-Black' }}>Inter Black</Text>

<Text style={{ fontFamily: 'Roboto Flex', fontWeight: '300' }}>Roboto Flex Light</Text>
<Text style={{ fontFamily: 'Roboto Flex', fontWeight: '700' }}>Roboto Flex Bold</Text>

Loading multiple weights and styles for one font family

Loading several font files under one family name is available in SDK 58 and later.

The map syntax above treats each key as a separate font family. To load several font files (for example regular, bold, and italic cuts) under one fontFamily name, pass useFonts an array of FontFamilyDefinitions instead of a map:

const [loaded, error] = useFonts([
  {
    fontFamily: 'Inter',
    fontDefinitions: [
      { path: require('./assets/fonts/Inter-Regular.otf'), weight: 400 },
      { path: require('./assets/fonts/Inter-Italic.otf'), weight: 400, style: 'italic' },
      { path: require('./assets/fonts/Inter-Bold.otf'), weight: 700 },
    ],
  },
]);

Then select a face with the fontWeight and fontStyle style props:

<Text style={{ fontFamily: 'Inter', fontWeight: '700' }}>Inter Bold</Text>
<Text style={{ fontFamily: 'Inter', fontWeight: '400', fontStyle: 'italic' }}>Inter Italic</Text>

Declare every face of a family in one call. A fontFamily loads once, so a later loadAsync or useFonts call for a name that is already loaded adds no faces to it. This also applies across the two call styles: after useFonts({ Inter: require('./assets/fonts/Inter-Regular.otf') }), passing an array for Inter loads nothing more.

Declare weight and style on every face of a multi-face family. Web needs both values, and explicit values keep the three platforms in agreement. A single variable font file is the exception: leave its style unset, and leave its weight unset or declare a weight range such as '100 900'. Android then instances the font's wght axis for every fontWeight instead of pinning it to one weight.

Platform notes:

• Android uses the declared weight and style values, and falls back to the values in the font file when not declared. A declared weight pins a variable font face to that one weight, and Android synthesizes the others. Below API 29 (Android 10), only the default face loads, chosen by the declared values (closest to weight 400, upright). Fonts embedded with the config plugin use Android's XML font resources and do not have this limit.
• iOS matches faces by the weight and style metadata embedded in the font files. It uses the declared weight and style values only to pick the family's default face when a file carries no readable metadata.
• Web generates one CSS @font-face rule per face, with the declared weight and style values. CSS cannot read the metadata inside a font file, so a face that declares no style renders as upright. Two faces of one family that leave the same values undeclared produce the same CSS rule, and the browser renders the last one.

Use Google Fonts

Expo has first-class support for all fonts listed in Google Fonts. They are available using @expo-google-fonts library. With any of the font package from this library, you can quickly integrate that font and its variants.

Two ways to use a Google Font in your project:

• Embed the installed font with expo-font config plugin.
• Load the installed font with useFonts hook at runtime asynchronously.

With expo-font config plugin

Note: Embedding a Google Font using expo-font config plugin has same benefits and limitations as embedding a custom font on your own. See using a local font file with expo-font config plugin for more information.

{
  "plugins": [
    [
      "expo-font",
      {
        "fonts": ["node_modules/@expo-google-fonts/inter/900Black/Inter_900Black.ttf"]
      }
    ]
  ]
}

import { Platform } from 'react-native';

// Inside a React component:
<Text
  style={{
    fontFamily: Platform.select({
      android: 'Inter_900Black',
      ios: 'Inter-Black',
    }),
  }}>
  Inter Black
</Text>

With useFonts hook

Note: Loading a Google Font using useFonts hook has same benefits and limitations as embedding a custom font on your own. See using a local font file with useFonts hook for more information.

Each Google Fonts package provides the useFonts hook to load the fonts asynchronously. This hook keeps track of the loading state and loads the font when an app is initialized. The font package also imports the font file so you don't have to explicitly import it.

// Rest of the import statements
import { Inter_900Black, useFonts } from '@expo-google-fonts/inter';
import * as SplashScreen from 'expo-splash-screen';
import {useEffect} from 'react';

SplashScreen.preventAutoHideAsync();

export default function RootLayout() {
  const [loaded, error] = useFonts({
    Inter_900Black,
  });

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

  if (!loaded && !error) {
    return null;
  }

  return (
    %%placeholder-start%%... %%placeholder-end%%
  )
}

<Text style={{ fontFamily: 'Inter_900Black' }}>Inter Black</Text>

Additional information

Minimal example

Beyond OTF and TTF

If your font is in format other than OTF or TTF, you have to customize the Metro bundler configuration to include it as an extra asset for it to work. In some cases, rendering a font format that a platform doesn't support may cause your app to crash.

For reference, the following table provides the list formats that work on each native platform:

Platform built-in fonts

If you don't want to use a custom font by specifying a fontFamily, platform's default font will be used. Each platform has a set of built in fonts. On Android, the default font is Roboto. On iOS, it's SF Pro.

A platform's default font is usually easy-to-read. However, don't be surprised when the system default font is changed to use another font that is not easy to read. In this case, use your custom font so you have precise control over what the user will see.

Handle @expo/vector-icons initial load

When the icons from @expo/vector-icons library load for the first time, they appear as invisible icons in your app. Once they load, they're cached for all the app's subsequent usage. To avoid showing invisible icons on your app's first load, preload during the initial loading screen with useFonts. For example:

import { useFonts } from 'expo-font';
import Ionicons from '@expo/vector-icons/Ionicons';

export default function RootLayout() {
  useFonts([require('./assets/fonts/Inter-Black.otf', Ionicons.font)]);

  return (
    %%placeholder-start%%... %%placeholder-end%%
  )
}

Now, you can use any icon from the Ionicons library in a React component:

<Ionicons name="checkmark-circle" size={32} color="green" />

Loading a remote font directly from the web

If you're loading remote fonts, make sure they are being served from an origin with CORS properly configured. If you don't do this, your remote font might not load properly on the web platform.

Loading fonts from a local asset is the safest way to load a font in your app. When including fonts as local assets, after you submit your app to the app stores, these fonts are bundled with the app download and will be available immediately. You don't have to worry about CORS or other potential issues.

However, loading a font file directly from web is done by replacing the require('./assets/fonts/FontName.otf') with the URL of your font as shown in the example below.

import { useFonts } from 'expo-font';
import { Text, View, StyleSheet } from 'react-native';

export default function App() {
  const [loaded, error] = useFonts({
    'Inter-SemiBoldItalic': 'https://rsms.me/inter/font-files/Inter-SemiBoldItalic.otf?v=3.12',
  });

  if (!loaded || !error) {
    return null;
  }

  return (
    <View style={styles.container}>
      <Text style={{ fontFamily: 'Inter-SemiBoldItalic', fontSize: 30 }}>Inter SemiBoldItalic</Text>
      <Text style={{ fontSize: 30 }}>Platform Default</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});