r3f-webgpu-text

Created by Anderson Mancini

Live demo: https://r3f-webgpu-text.vercel.app

MSDF WebGPU text components for React Three Fiber. Render crisp, scalable 3D text in WebGPU scenes with an API inspired by Drei's <Text />.

Built on top of three-msdf-text-utils, which provides MSDF geometry and WebGPU materials for vanilla Three.js. This package brings the same capabilities to R3F as ready-to-use React components.

Features

• WebGPU-first — uses MSDFTextNodeMaterial from three-msdf-text-utils/webgpu
• Drei-like API — familiar props: fontSize, anchorX, anchorY, maxWidth, lineHeight, etc.
• Font caching — shared loader avoids duplicate fetches across instances
• Performance modes — single text, batched instancing, and character-level instancing
• TypeScript — full type definitions included

Requirements

• React 18+
• React Three Fiber 8+
• Three.js 0.172+ with WebGPU support
• A browser with WebGPU enabled
• MSDF font atlas files (.json + .png)

Installation

npm install r3f-webgpu-text three-msdf-text-utils

You also need peer dependencies if not already installed:

npm install three @react-three/fiber react react-dom

Quick start

import * as THREE from 'three/webgpu'
import { Canvas, extend } from '@react-three/fiber'
import { WebGPUText } from 'r3f-webgpu-text'

extend(THREE)

function Scene() {
  return (
    <WebGPUText
      position={[0, 1, 0]}
      fontSize={0.5}
      color="#ffffff"
      fontData="/fonts/MyFont-msdf.json"
      fontAtlas="/fonts/MyFont.png"
    >
      Hello WebGPU
    </WebGPUText>
  )
}

export default function App() {
  return (
    <Canvas
      gl={async (props) => {
        const renderer = new THREE.WebGPURenderer(props)
        await renderer.init()
        return renderer
      }}
    >
      <Scene />
    </Canvas>
  )
}

Place your MSDF font files in your app's public/fonts/ folder (or any URL-accessible path).

Components

<WebGPUText />

Renders a single text label. Best for individual labels, titles, and UI elements.

<WebGPUText
  position={[0, 1, 0]}
  fontSize={0.5}
  color="#ffffff"
  anchorX="center"
  anchorY="middle"
  textAlign="center"
  lineHeight={1.1}
  letterSpacing={0}
  maxWidth={5}
  fontData="/fonts/Manrope-Medium-msdf.json"
  fontAtlas="/fonts/Manrope-Medium.png"
>
  Hello World
</WebGPUText>

Prop	Type	Default	Description
children	string	—	Text content
position	[x, y, z]	[0, 0, 0]	World position
rotation	[x, y, z]	[0, 0, 0]	Rotation in radians
fontSize	number	1	Text size in world units
color	string	"#ffffff"	Text color
opacity	number	1	Text opacity
anchorX	"left" | "center" | "right" | number	"center"	Horizontal anchor
anchorY	"top" | "middle" | "bottom" | ... | number	"middle"	Vertical anchor
textAlign	"left" | "center" | "right"	"center"	Text alignment
lineHeight	number	1.1	Line height multiplier
letterSpacing	number	0	Letter spacing
maxWidth	number	—	Max width before wrapping
fontData	string	—	Path/URL to BMFont JSON
fontAtlas	string	—	Path/URL to MSDF atlas PNG
renderOrder	number	0	Render order
visible	boolean	true	Visibility

<WebGPUBatchedText />

Renders many text labels efficiently. Identical strings (same text, size, color, anchors) are grouped into a single InstancedMesh — one draw call per group.

<WebGPUBatchedText
  texts={[
    { text: "Hello", position: [0, 0, 0], fontSize: 0.5 },
    { text: "Hello", position: [2, 0, 0], fontSize: 0.5 },
    { text: "World", position: [4, 0, 0], fontSize: 0.5, color: "#ff6600" },
  ]}
  fontData="/fonts/Manrope-Medium-msdf.json"
  fontAtlas="/fonts/Manrope-Medium.png"
/>

Prop	Type	Default	Description
texts	BatchedTextItem[]	[]	Array of text configs
fontData	string	—	Path/URL to BMFont JSON
fontAtlas	string	—	Path/URL to MSDF atlas PNG
defaultFontSize	number	0.02	Default font size for items
defaultColor	string	"#ffffff"	Default color for items

Each item in texts supports: text, position, rotation, scale, fontSize, color, anchorX, anchorY, textAlign, lineHeight, letterSpacing.

<WebGPUInstancedText />

Character-level instancing. Creates one InstancedMesh per unique character — roughly ~70 draw calls regardless of how many different text strings you render. Ideal for large numbers of labels (maps, dashboards, debug overlays).

<WebGPUInstancedText
  texts={[
    { text: "HELLO", position: [0, 0, 0] },
    { text: "WORLD", position: [1, 0, 0] },
  ]}
  lookAtCamera={true}
  fontData="/fonts/Manrope-Medium-msdf.json"
  fontAtlas="/fonts/Manrope-Medium.png"
/>

Prop	Type	Default	Description
texts	InstancedTextItem[]	[]	Array of text configs
lookAtCamera	boolean	false	Billboard effect — text faces camera
charset	string	alphanumeric + punctuation	Allowed characters
fontData	string	—	Path/URL to BMFont JSON
fontAtlas	string	—	Path/URL to MSDF atlas PNG
defaultFontSize	number	0.02	Default font size
defaultColor	string	"#ffffff"	Default color

Performance guide

Scenario	Component	Draw calls
1–20 labels	<WebGPUText />	1 per label
Many identical strings	<WebGPUBatchedText />	1 per unique string group
Hundreds/thousands of different labels	<WebGPUInstancedText />	~1 per unique character

Tips:

• Use <WebGPUText /> for simple scenes and interactive labels
• Use <WebGPUBatchedText /> when many texts share the same content and styling
• Use <WebGPUInstancedText /> for dense label clouds (maps, data viz, debug text)
• Always host font files locally — avoid loading fonts from remote URLs in production

Generating MSDF fonts

You need a BMFont JSON file and a matching PNG atlas generated as MSDF. Use msdf-bmfont-xml:

npx msdf-bmfont-xml -f json -m 512,512 -s 42 -o public/fonts/MyFont MyFont.ttf

This produces:

• MyFont-msdf.json — glyph metrics and kerning
• MyFont.png — MSDF texture atlas

Pass the paths to fontData and fontAtlas props.

Utilities

import {
  loadFontCached,
  clearFontCache,
  parseAnchor,
  DEFAULT_FONT_DATA,
  DEFAULT_FONT_ATLAS,
} from 'r3f-webgpu-text'

// Preload a font
await loadFontCached('/fonts/MyFont-msdf.json', '/fonts/MyFont.png')

// Clear cache (e.g. on route change)
clearFontCache()

Demo

Live demo: https://r3f-webgpu-text.vercel.app

Run the included demo locally:

git clone https://github.com/ektogamat/r3f-webgpu-text.git
cd r3f-webgpu-text
npm install
npm run dev

Open the URL shown in the terminal (requires WebGPU).

Build the demo for deployment:

npm run build:demo

Development

# Run demo dev server
npm run dev

# Build library to dist/
npm run build

# Build demo to demo-dist/
npm run build:demo

Author

Created by Anderson Mancini.

License

MIT © Anderson Mancini