three-text-geometry

The port of the JavaScript versions of three-bmfont-text, layout-bmfont-text, load-bmfont, and word-wrapper to Pure Typescript, this library enables fast text rendering with Three.js and bitmap font.
The difference in rendering speed is noticeable when animations are enabled, and it runs 10x faster than canvas texture based text rendering.

v4.0 introduces WebGPU support with TSL (Three Shading Language) based node materials that work with both WebGLRenderer and WebGPURenderer.

Requirements

• Three.js 0.172.0 or later
• React 19 or later
• React Three Fiber 9 or later
• Node.js 22 or later

Installation

NPM

$ npm install three-text-geometry three react @react-three/fiber

PNPM

$ pnpm add three-text-geometry three react @react-three/fiber

Yarn

$ yarn add three-text-geometry three react @react-three/fiber

Note: three, react, and @react-three/fiber are peer dependencies and must be installed alongside three-text-geometry.

Usage

For detailed information, read the documentation and check the demo.

TextGeometry supports word wrapping, text aligning, letter spacing, kerning. See the list for all available options.

React Three Fiber

three-text-geometry provides first-class support for React Three Fiber.

Setup

TextGeometry is automatically registered with the R3F catalog when the library is imported. No manual setup is required.

import 'three-text-geometry'
// <textGeometry ... /> is now available

Factory pattern (R3F v9)

Alternatively, use R3F v9's extend to create a component directly.

import { extend } from '@react-three/fiber'
import TextGeometry from 'three-text-geometry'

const TextGeometryEl = extend(TextGeometry)
// Now you can use <TextGeometryEl ... />

Example

The useFont hook loads a BMFont file and its texture asynchronously. Combined with <textGeometry>, you can render bitmap text in just a few lines.

import * as THREE from 'three'
import { Canvas } from '@react-three/fiber'
import { TextAlign, useFont } from 'three-text-geometry'

function TextMesh() {
  const { font, texture, isLoading } = useFont(
    'https://example.com/font.json',
    'https://example.com/font.png'
  )

  if (isLoading || !font || !texture) return null

  return (
    <mesh rotation={[Math.PI, 0, 0]}>
      <textGeometry args={['Hello World', { font, align: TextAlign.Left, width: 800, flipY: texture.flipY }]} />
      <meshBasicMaterial map={texture} transparent side={THREE.DoubleSide} />
    </mesh>
  )
}

function App() {
  return (
    <Canvas camera={{ fov: 45, position: [0, 0, 500] }}>
      <TextMesh />
    </Canvas>
  )
}

Type definitions

Importing three-text-geometry automatically augments R3F's ThreeElements interface, enabling type completions for <textGeometry> in TypeScript projects.

import 'three-text-geometry' // Adds textGeometry to ThreeElements

Vanilla Three.js

You can also use TextGeometry directly without React Three Fiber.

import * as THREE from 'three'
import TextGeometry, { BMFont, BMFontJsonParser, TextAlign } from 'three-text-geometry'

// Load font and texture
const res = await fetch('https://example.com/font.json')
const font: BMFont = new BMFontJsonParser().parse(await res.json())
const texture = await new THREE.TextureLoader().loadAsync('https://example.com/font.png')

// Create geometry and mesh
const geometry = new TextGeometry('Hello World', {
  font,
  align: TextAlign.Left,
  width: 800,
  flipY: texture.flipY,
})
const material = new THREE.MeshBasicMaterial({
  map: texture,
  side: THREE.DoubleSide,
  transparent: true,
})
const mesh = new THREE.Mesh(geometry, material)
  .rotateY(Math.PI)
  .rotateZ(Math.PI)
scene.add(mesh)

Materials

three-text-geometry provides TSL-based node materials for text rendering. These materials work with both WebGLRenderer and WebGPURenderer.

BasicTextNodeMaterial

Samples a font texture and multiplies by color and opacity. Suitable for standard bitmap fonts.

import { BasicTextNodeMaterial } from 'three-text-geometry'

const material = new BasicTextNodeMaterial({
  map: texture,
  color: new THREE.Color(0xffffff),
  opacity: 1,
})

SDFTextNodeMaterial

For SDF (Signed Distance Field) fonts. Uses screen-space derivatives for anti-aliased edges.

import { SDFTextNodeMaterial } from 'three-text-geometry'

const material = new SDFTextNodeMaterial({
  map: texture,
  color: new THREE.Color(0xffffff),
})

MSDFTextNodeMaterial

For MSDF (Multi-channel Signed Distance Field) fonts. Computes a median from RGB channels for high-quality rendering.

import { MSDFTextNodeMaterial } from 'three-text-geometry'

const material = new MSDFTextNodeMaterial({
  map: texture,
  color: new THREE.Color(0xffffff),
  negate: true, // Invert RGB channels (default: true)
})

MultiPageTextNodeMaterial

For multi-texture fonts. Selects the correct texture atlas per vertex using a page attribute. Requires multipage: true in TextGeometryOption.

import { MultiPageTextNodeMaterial } from 'three-text-geometry'

const material = new MultiPageTextNodeMaterial({
  textures: [texture0, texture1, texture2],
  color: new THREE.Color(0xffffff),
})

const geometry = new TextGeometry('Hello', {
  font,
  multipage: true,
})

Migration from v3

v4 removes the legacy GLSL shader modules. If you were using MultiPageShaderMaterial or the GLSL shader sources from three-text-geometry/shaders, migrate to the new TSL-based node materials:

v3 (Removed)	v4 (Replacement)
shaders/basic	BasicTextNodeMaterial
shaders/sdf	SDFTextNodeMaterial
shaders/msdf	MSDFTextNodeMaterial
MultiPageShaderMaterial	MultiPageTextNodeMaterial

How to run the demo

The demo is built with React Three Fiber. Clone the repository and run:

git clone https://github.com/gumob/three-text-geometry.git
cd three-text-geometry/demo
corepack enable
pnpm install
pnpm dev

Screen coordinate system and Three.js coordinate system

TextGeometry places text based on the screen coordinate system. Therefore, when THREE.Mesh is added to the scene, the text will be placed inverted when viewed from the positive direction of the Z axis. To make the text visible from the positive z-axis, you need apply transformation.

BMFontParser interface supports JSON, XML, ACII, and Binary fromat

Parse font data in JSON format

import { BMFontJsonParser } from 'three-text-geometry'
const font: BMFont = new BMFontJsonParser().parse(/** `string` or `object` data JSON format */)

Parse font data in XML format

import { BMFontXMLParser } from 'three-text-geometry'
const font: BMFont = new BMFontXMLParser().parse(/** `string` data in XML format */)

Parse font data in ASCII format

import { BMFontAsciiParser } from 'three-text-geometry'
const font: BMFont = new BMFontAsciiParser().parse(/** `string` data in ASCII format */)

Parse font data in Binary format

import { BMFontBinaryParser } from 'three-text-geometry'
const font: BMFont = new BMFontBinaryParser().parse(/** `string` data in ASCII Binary */)

The value list of TextGeometryOption

key	type	description	default	required
font	BMFont	The BMFont definition which holds chars, kernings, etc	undefined	✔
width	number	The desired width of the text box, causes word-wrapping and clipping in WordWrapMode mode. Leave as undefined to remove word-wrapping (default behaviour)	undefined
mode	WordWrapMode	A mode for word-wrapper; can be WordWrapMode.Pre (maintain spacing), or WordWrapMode.NoWrap (collapse whitespace but only break on newline characters), otherwise assumes normal word-wrap behaviour (collapse whitespace, break at width or newlines)	undefined
align	TextAlign	This can be TextAlign.left, TextAlign.center or TextAlign.right	TextAlign.left
letterSpacing	number	The letter spacing in pixels	0
lineHeight	number	The line height in pixels	font.common.lineHeight
tabSize	number	The number of spaces to use in a single tab	4
start	number	The starting index into the text to layout	0
end	number	The ending index (exclusive) into the text to layout	text.length
flipY	boolean	Whether the texture will be Y-flipped	true
multipage	boolean	Whether to construct this geometry with an extra buffer containing page IDs. This is necessary for multi-texture fonts	false

Generate Bitmap Font

The following tools can be used to convert fonts to a bitmap font:

• msdf-bmfont-web (Online Tool)
• msdf-bmfont-xml (Commandline Tool)
• Hiero (Desktop App, Windows Only)

Read the Three.js documentation about a bitmap font.

Using msdf-bmfont-xml

Install msdf-bmfont-xml

$ npm install msdf-bmfont-xml -g

Generate a bitmap font

$ msdf-bmfont \
    --output-type json \
    --filename 'OdudoMono-Regular-128' \
    --font-size 128 \
    --texture-size 1024,1024 \
    --field-type 'sdf' \
    'OdudoMono-Regular.otf'

Copyright

Punycode is released under MIT license, which means you can modify it, redistribute it or use it however you like.