Custom Fonts

The Text component supports custom fonts. By default, uikit provides Inter. There are two ways to add your own:

Under the hood, fonts are rendered using MSDF (multi-channel signed distance fields).

Load TTF files directly at runtime using the built-in TTFLoader (vanilla) or useTTF hook (React). These convert TTF fonts to MSDF format on-the-fly using WebAssembly.

import { Suspense } from 'react'
import { useTTF, Fullscreen, Text } from '@react-three/uikit'

function UI() {
  const fontFamilies = useTTF('/fonts/Roboto.ttf')

  return (
    <Fullscreen fontFamilies={fontFamilies}>
      <Text fontSize={24}>Hello World</Text>
    </Fullscreen>
  )
}

function App() {
  return (
    <Suspense fallback={null}>
      <UI />
    </Suspense>
  )
}

import { TTFLoader, Container, Text } from '@pmndrs/uikit'

const loader = new TTFLoader()
const fontFamilies = await loader.loadAsync('/fonts/Roboto.ttf')

const root = new Container({ fontFamilies })
const text = new Text({ fontSize: 24, text: 'Hello World' })
root.add(text)

Load multiple TTF files at once by passing an array:

// React
const fontFamilies = useTTF(['/fonts/Roboto.ttf', '/fonts/NotoSansJP.ttf'])

// Vanilla
const fontFamilies = await loader.loadAsync(['/fonts/Roboto.ttf', '/fonts/NotoSansJP.ttf'])

There are two ways to generate MSDF fonts ahead of time: using a web-based tool or using local tooling. The web-based option is simpler and doesn't require installing any software.

You can use the MSDF Generator at https://msdf.zap.works/ to convert your TTF font to MSDF format.

The generated JSON file contains the MSDF texture embedded inline, so you don't need to manage separate texture files.

If you prefer to use local tooling or need more control over the generation process, you can use msdf-bmfont-xml.

This example shows how to compile the Roboto font family with the weight medium.

The first step is to download a .ttf file for the font family with the correct weights. After downloading the font to roboto.ttf, the overlaps need to be removed.

This is necessary because msdf-bmfont has a problem with overlapping paths, creating weird artifacts.

fontforge -lang=ff -c 'Open($1); SelectAll(); RemoveOverlap(); Generate($2)' roboto.ttf fixed-roboto.ttf

Next, we use msdf-bmfont to convert the .ttf file to a texture and a .json file. For that we need the FontForge generated font and a charset file containing all the characters we want to include in our msdf-font.

npx msdf-bmfont -f json fixed-roboto.ttf -i charset.txt -m 256,512 -o public/roboto -s 48

example charset.txt:

 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!?.,;:'"()-[]{}@#$%&*+=/\<>

If you are using some kind of hashes in your filenames, you won't be able to use the separate texture. In that case you need to inline the texture in the .json file. Here's a sample script to do it:

import { writeFile } from 'fs/promises'
import generateBMFont from 'msdf-bmfont-xml'

const charset = ' ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!?.,;:\'"()-[]{}@#$%&*+=/\\<>'

generateBMFont(
  'src/assets/fonts/Inter-Bold.woff',
  {
    smallSize: true,
    charset,
    outputType: 'json',
  },
  async (
    error: Error | undefined,
    textures: { filename: string; texture: Buffer }[],
    font: { filename: string; data: string },
  ) => {
    if (error) {
      throw error
    }
    const pages = await Promise.all(
      textures.map((texture) => 'data:image/png;base64,' + texture.texture.toString('base64')),
    )
    const json = JSON.parse(font.data)

    json.pages = pages
    await writeFile(font.filename, JSON.stringify(json))
  },
)

Once you have generated the JSON file (using either method), you can add the font family via the fontFamilies property.

For web-generated fonts (Option 1), the texture is already inlined in the JSON file. For locally-generated fonts (Option 2), it's necessary to host the .json file and the texture on the same URL and provide the URL to the .json file to the fontFamilies property.

Repeat the previous process for other weights, such as bold, to support different weights.

<Container
  fontFamilies={{
    roboto: {
      medium: 'url-to-medium.json',
      bold: 'url-to-bold.json',
    },
  }}
>
  <Text fontFamily="roboto">Test123</Text>
</Container>