Custom Fonts

Without Dripsy:

<Text style={{ fontFamily: 'SofiaPro-Bold' }}>Sad API</Text>

With Dripsy:

<Text sx={{ fontWeight: 'bold' }}>Great API</Text>

Example#

If you'd rather see a full example from the start, check this one out on Expo Snack.

How it works#

Dripsy lets you globally control your fonts in React Native. Before Dripsy, this was a huge pain. You had to manually set the fontFamily name to a string that corresponds to your actual font file name. If you ever changed custom fonts, you'd need to edit all your files that had it, or create an unnecessary CustomText component.

No longer. All of your custom font definitions can live in a single theme variable. Once you add your fonts to your theme, you can load them with expo-font (or your loader of choice).

Step-by-step guide#

1. Add your font to your theme.fonts#

There are two options for this:

a) Provide a single root font in your theme.fonts (easiest, recommended)

b) Provide multiple fonts (only use this if you're using multiple custom fonts)

1.a) Provide a single root in your theme.fonts (easiest, recommended)#

import { makeTheme } from 'dripsy'
const fontName = 'arial'
const theme = makeTheme({
  customFonts: {
    [fontName]: {
      // I recommend setting every weight here
      bold: 'arialBold',
      default: fontName,
      normal: fontName,
      400: fontName,
      500: 'arialMedium',
      600: 'arialBold',
      700: 'arialBold',
      800: 'arialBold',
      900: 'arialBlack',
    },
  },
  fonts: {
    root: fontName, // <- this string must match the key you set in custom fonts above!
  },
})

Recommended when using web, add a fallback for your fonts:

import { makeTheme } from 'dripsy'
const fontName = 'arial'
const webFont = (font: string) =>
  Platform.select({
    web: `${font}, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, Inter-serif`,
    default: font,
  })
const theme = makeTheme({
  customFonts: {
    [fontName]: {
      bold: webFont('arialBold'),
      default: webFont(fontName),
      normal: webFont(fontName)',
      '400': webFont(fontName)',
      '500': webFont('arialMedium'),
      '600': webFont('arialBold'),
      '700': webFont('arialBold'),
      '800': webFont('arialBold'),
      '900': webFont('arialBlack'),
    },
  },
  fonts: {
    root: fontName,
  },
})

You can also alias your fontWeights to make it easier, just like theme-ui:

import { makeTheme } from 'dripsy'
const fontName = 'arial'
const webFont = (font: string) =>
  Platform.select({
    web: `${font}, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, Inter-serif`,
    default: font,
  })
const theme = makeTheme({
  customFonts: {
    [fontName]: {
      bold: webFont('arialBold'),
      default: webFont(fontName),
      normal: webFont(fontName)',
      '400': webFont(fontName)',
      '500': webFont('arialMedium'),
      '600': webFont('arialBold'),
      '700': webFont('arialBold'),
      '800': webFont('arialBold'),
      '900': webFont('arialBlack'),
    },
  },
  fonts: {
    root: fontName,
  },
  // this is new here:
  fontWeights: {
    black: '900',
  },
})

Now that we've added the black shorthand to our fontWeights, we can use it anywhere in our app. The string 900 corresponds to theme.customFonts.arial['900'].

You can now style your fonts like so:

import { Text } from 'dripsy'
const Black = () => (
  <Text sx={{ fontWeight: 'black' }}>This font weight is 900!</Text>
)

You can also use this shorthand when creating custom text variants in your theme.

For instance, if you want to make a bold & caps text variant called thickCaps:

import { makeTheme } from 'dripsy'
const fontName = 'arial'
const webFont = (font: string) =>
  Platform.select({
    web: `${font}, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, Inter-serif`,
    default: font,
  })
const theme = makeTheme({
  customFonts: {
    [fontName]: {
      bold: webFont('arialBold'),
      default: webFont(fontName),
      normal: webFont(fontName)',
      '400': webFont(fontName)',
      '500': webFont('arialMedium'),
      '600': webFont('arialBold'),
      '700': webFont('arialBold'),
      '800': webFont('arialBold'),
      '900': webFont('arialBlack'),
    },
  },
  fonts: {
    root: fontName,
  },
  fontWeights: {
    black: '900'
  },
  text: {
    thickCaps: {
      fontWeight: 'black', // this is 900 from fontWeights.black
      textTransformation: 'uppercase'
    }
  }
})

And you can use it in your component with the variant prop:

import { Text } from 'dripsy'
const BoldCaps = () => (
  <Text variant="thickCaps">This font weight is 900, & it's capitalized!</Text>
)

Considerations for naming conventions#

Notice how the theme.fonts.root is arial. This tells Dripsy to check for theme.customFonts.arial.

If you wanted to name it something other than arial, you could. However, you can't name the font itself root. That's the only exception.

There are 2 important details when it comes to the naming:

1. The name of your customFont key must match the name you pass to theme.fonts.root. In the example above, I picked the name arial.
2. The name you use to load in your font at its default weight (often 400 or default) must also match the key you pass to theme.customFonts. (We'll see this in step 2.)

• Explanation In step 2, when you import your font using expo-font, you have to make sure you name the default font weight with the same name passed to customFonts.
• In the example above, we would import our font using expo-font, and name it arial. You can skip down to step #3 to see what I mean. We need to make these the same to ensure that we always fall back to the correct default font. If we don't do this, then React Native will raise an error, saying it could not find the custom font.

1b) Provide multiple fonts (only use this if you're using multiple custom fonts)#

If you have multiple custom fonts you'd like to use, this step is for you.

1. Follow the same steps as step #1.a.
2. Add your other fonts to theme.customFonts, just like step #1a.

import { makeTheme } from 'dripsy'
const rootFontName = 'arial'
const headingFontName = 'inter'
const theme = makeTheme({
  customFonts: {
    [rootFontName]: {
      // ... from step 1.a
    },
    // these are new
    [headingFontName]: {
      bold: 'InterBold',
      default: headingFontName,
      normal: headingFontName,
      '400': headingFontName,
      '500': 'InterSemiBold',
      '600': 'InterBold',
      '700': 'InterBold',
      '800': 'InterBold',
      '900': 'InterBlack',
    },
  },
  fonts: {
    root: rootFontName,
    heading: headingFontName,
  },
  text: {
    h1: {
      // use inter, from fonts.heading
      fontFamily: 'heading',
    },
    h2: {
      fontFamily: 'heading',
    },
    h3: {
      fontFamily: 'heading',
    },
  },
})

This tells Dripsy we have 2 custom fonts, named arial and Inter. These are custom names made by you. They will be used in your app later to reference which font you're picking.

2. Loading in fonts with expo-font (or whatever loader you prefer)#

As an added step (to include in docs later), you can use expo-font to actually load the fonts in:

// fonts.tsx
import { useFonts } from 'expo-font'
export default function Fonts({ children }: { children: React.ReactNode }) {
  const [loaded] = useFonts({
    // 🚨🚨🚨 the name (`Inter`) of the default weight here should equal the key from theme.customFonts
    // otherwise, you will need to explicitly set the fontWeight everywhere
    // since we have theme.customFonts.Inter, we name this `Inter`
    ['inter']: require('./public/fonts/InterBook.ttf'),
    ['InterBold']: require('./public/fonts/arialBlack.ttf'),
    // same goes here, load in the default font name with the one that matches your theme.customFonts
    ['arial']: require('./public/fonts/arialBook.ttf'),
    ['arialBold']: require('./public/fonts/arialBold.ttf'),
  })
  if (!loaded) return null
  return <>{children}</>
}

Chances are, you'll set the font names as variables:

// fonts.tsx
import { useFonts } from 'expo-font'
import { headingFontName, rootFontName } from './theme'
export default function Fonts({ children }: { children: React.ReactNode }) {
  const [loaded] = useFonts({
    [headingFontName]: require('./public/fonts/InterBook.ttf'),
    ['InterBold']: require('./public/fonts/arialBlack.ttf'),
    [rootFontName]: require('./public/fonts/arialBook.ttf'),
    ['arialBold']: require('./public/fonts/arialBold.ttf'),
  })
  if (!loaded) return null
  return <>{children}</>
}

It's very important that the default font weight above is named to match the keys of our custom fonts.

By changing the name into a variable (headingFontName = 'inter'), we make that easy.

To reiterate, once again: the name of the default font weight you use in useFonts must match the key for the font in your theme.customFonts.

Another caveat: you cannot name a font "root". Dripsy uses this field to identify your root font, so please do not name a font root when you load it in. Any other word works.

Use Fonts#

Use the new Fonts component in your App.tsx:

// App.tsx
import Fonts from './fonts'
export default function App() {
  return (
    <Fonts>
      <YourAppHere />
    </Fonts>
  )
}

The <Fonts /> component should only be used for iOS and Android. For loading fonts on Web, skip to web optimizations.

3. Using and customizing your custom fonts in your app#

Now that we've defined our fonts in our theme, we can use them anywhere in our app. To globally style all text, you could add a theme.text.body field:

import { makeTheme } from 'dripsy'
const fontName = 'inter'
const theme = makeTheme({
  customFonts: {
    [fontName]: {
      bold: 'InterBold',
      default: fontName,
      normal: fontName,
      400: fontName,
      500: 'InterSemiBold',
      600: 'InterBold',
      700: 'InterBold',
      800: 'InterBold',
      900: 'InterBlack',
    },
  },
  fonts: {
    root: fontName,
  },
  text: {
    body: {
      // this sets defaults for all <Text> components
      // it will use customFonts.inter.bold
      fontWeight: 'bold',
      color: 'cyan',
    },
    h1: {
      // this sets defaults for all <H1> components
      // it will use customFonts.Inter[900]
      fontWeight: '900',
    },
  },
})

You can also style like normal throughout your app, and watch your font weights change elegantly:

import { Text } from 'dripsy'
const Bold = () => (
  <Text>Whoa, this is a custom bold font (& it's color is cyan)</Text>
)

For context, without dripsy, you'd have to do this:

import { Text } from 'react-native'
const Bold = () => (
  <Text style={{ fontFamily: 'InterBold' }}>Lame, this isn't easy.</Text>
)

You probably don't want to make your text.body bold, since this will style your entire app's Text.

But you could make a custom variant in theme.text called thick:

const theme = makeTheme({
  ...,
  text: {
    thick: {
      fontWeight: 'bold'
    }
  }
})

In your component:

import { Text } from 'dripsy'
const Thick = () => (
  <Text variant="thick">Hey, this is bold. That's all it takes.</Text>
)

Web Optimizations#

To improve the performance of loading your fonts on web, you can add something like this to the head of your HTML:

<link
  rel="preload"
  href="/fonts/InterBook.ttf"
  as="font"
  crossOrigin=""
/>
<link
  rel="preload"
  href="/fonts/InterSemibold.ttf"
  as="font"
  crossOrigin=""
/>

Create a <link /> for each font you're importing, and make sure to keep the preload prop to make it load early.

If you're using Next.js, this would go in your pages/_document.js file, inside of Next's <Head> component, and you'd put your fonts folder inside of /public.

Optimize Icon fonts#

In fact, when I use icons in my app with @expo/vector-icons, I copy the icon TTF files into my /public folder (such as Ionicons.ttf) and load them in the same way:

// I copied Ionicons.ttf from /node_modules/@expo/vector-icons/build
<link rel="preload" href="/fonts/Ionicons.ttf" as="font" crossorigin="" />

Final Example#

I made a full example of custom fonts on Expo Snack.