Custom Fonts

React Native handles fonts differently from the web. There is no @font-face, no automatic font discovery, and no fallback font stacks. Every font weight is a separate file, and the file name matters. This guide walks through the full setup.

A complete working example is available at nativewind/custom-fonts-example-v5.

Prerequisites

An Expo project with Nativewind v5 installed
A custom font you want to use (this guide uses Inter)

Step 1: Choose your font files

Use OTF or TTF format. OTF files render slightly better and have a smaller file size. Either format works across iOS, Android, and web.

Variable fonts do not work on React Native. You must download individual static weight files. For Inter, that means separate files for Regular, Bold, Italic, Medium, etc.

Download the static font files from your font's release page. For Inter, grab the OTF files from the GitHub releases.

Step 2: Name files correctly

Place font files in your project, for example assets/fonts/:

assets/
  fonts/
    Inter-Regular.otf
    Inter-Bold.otf
    Inter-Italic.otf
    Inter-BoldItalic.otf
    Inter-Medium.otf
    Inter-SemiBold.otf

The file name must match the PostScript name of the font. iOS uses the PostScript name to look up fonts at runtime. If the names don't match, the font silently fails to load on iOS while appearing to work on Android.

You can check a font's PostScript name by opening it in Font Book (macOS) or using a tool like fontdrop.info.

Step 3: Load fonts with expo-font

The simplest approach is to use the expo-font config plugin in app.json:

bun add expo-font

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-font",
        {
          "fonts": [
            "./assets/fonts/Inter-Regular.otf",
            "./assets/fonts/Inter-Bold.otf",
            "./assets/fonts/Inter-Italic.otf",
            "./assets/fonts/Inter-BoldItalic.otf",
            "./assets/fonts/Inter-Medium.otf",
            "./assets/fonts/Inter-SemiBold.otf"
          ]
        }
      ]
    ]
  }
}

Alternatively, load fonts at runtime with the useFonts hook:

App.tsx

import { useFonts } from "expo-font";
 
export default function App() {
  const [fontsLoaded] = useFonts({
    "Inter-Regular": require("./assets/fonts/Inter-Regular.otf"),
    "Inter-Bold": require("./assets/fonts/Inter-Bold.otf"),
  });
 
  if (!fontsLoaded) return null;
 
  return <>{/* your app */}</>;
}

The app.json approach is preferred because fonts are available immediately without a loading state.

Step 4: Verify with inline styles

Before touching your CSS theme, confirm the fonts actually loaded:

<Text style={{ fontFamily: "Inter-Regular" }}>
  This should render in Inter
</Text>

If this does not work, the issue is with font loading, not with Nativewind. Check your file names and app.json config.

Step 5: Add to your CSS theme

In v5, fonts are defined in CSS using the @theme directive in your global.css:

global.css

@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css";
 
@import "nativewind/theme";
 
@theme {
  --font-inter: "Inter-Regular";
  --font-inter-bold: "Inter-Bold";
  --font-inter-italic: "Inter-Italic";
  --font-inter-bold-italic: "Inter-BoldItalic";
  --font-inter-medium: "Inter-Medium";
  --font-inter-semibold: "Inter-SemiBold";
}

Each --font-* variable becomes a font-* utility class automatically.

React Native does not support fallback fonts. The value must be a single font name, not a comma-separated list.

Step 6: Use in components

<Text className="font-inter">Regular text</Text>
<Text className="font-inter-bold">Bold text</Text>
<Text className="font-inter-medium">Medium text</Text>
<Text className="font-inter-semibold">SemiBold text</Text>
<Text className="font-inter-italic">Italic text</Text>

v5 vs v4

In v4, fonts were configured in JavaScript via tailwind.config.js:

// v4 approach (tailwind.config.js)
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        inter: ["Inter-Regular"],
        "inter-bold": ["Inter-Bold"],
      },
    },
  },
};

In v5, this moves to CSS, which is simpler and consistent with how Tailwind CSS v4 works:

/* v5 approach (global.css) */
@theme {
  --font-inter: "Inter-Regular";
  --font-inter-bold: "Inter-Bold";
}

The usage in components (className="font-inter") is identical in both versions.

Common pitfalls

Problem	Cause	Fix
Font works on Android but not iOS	File name doesn't match PostScript name	Rename the file to match exactly
Font doesn't render at all	Font not loaded by expo-font	Check `app.json` plugin config or `useFonts` hook
Using `font-bold` doesn't make Inter bold	`font-bold` sets `fontWeight`, not `fontFamily`	Use `font-inter-bold` to set the bold font family
Variable font doesn't work	React Native doesn't support variable fonts	Download static weight files instead
Font renders as system default	PostScript name mismatch	Open font in Font Book and verify the PostScript name

Platform-specific fonts

Use the ios: and android: variants for platform-specific font overrides:

<Text className="font-inter ios:font-inter-medium android:font-inter-semibold">
  Different weights per platform
</Text>

Or override the default system fonts in your theme:

global.css

@theme {
  --font-sans: "Inter-Regular";
}

This makes font-sans (the default) use Inter instead of the system font.

Custom Fonts

On this page