packages/font/README.md
Font registration, loading, and resolution library for react-pdf. Handles TTF, WOFF, and WOFF2 fonts from various sources including local files, remote URLs, and base64 data URIs. Includes built-in support for PDF standard fonts.
yarn add @react-pdf/font
import FontStore from '@react-pdf/font';
const fontStore = new FontStore();
// Register a custom font
fontStore.register({
family: 'Roboto',
src: 'https://example.com/fonts/Roboto-Regular.ttf',
});
// Load the font
await fontStore.load({
fontFamily: 'Roboto',
fontStyle: 'normal',
fontWeight: 400,
});
The library supports multiple font source types:
fontStore.register({
family: 'Open Sans',
src: 'https://example.com/fonts/OpenSans-Regular.ttf',
});
With custom request options:
fontStore.register({
family: 'Open Sans',
src: 'https://example.com/fonts/OpenSans-Regular.ttf',
method: 'GET',
headers: {
Authorization: 'Bearer token',
},
body: null,
});
fontStore.register({
family: 'Custom Font',
src: '/path/to/font.ttf',
});
Note: Local file resolution is only available in Node.js environments.
fontStore.register({
family: 'Embedded Font',
src: 'data:font/ttf;base64,AAEAAAALAIAAAwAwT1MvMg...',
});
fontStore.register({
family: 'Roboto',
src: 'https://example.com/fonts/Roboto-Regular.ttf',
fontWeight: 400,
fontStyle: 'normal',
});
fontStore.register({
family: 'Roboto',
fonts: [
{ src: 'https://example.com/fonts/Roboto-Regular.ttf', fontWeight: 400 },
{ src: 'https://example.com/fonts/Roboto-Bold.ttf', fontWeight: 700 },
{
src: 'https://example.com/fonts/Roboto-Italic.ttf',
fontWeight: 400,
fontStyle: 'italic',
},
{
src: 'https://example.com/fonts/Roboto-BoldItalic.ttf',
fontWeight: 700,
fontStyle: 'italic',
},
],
});
The following PDF standard fonts are pre-registered and available without any additional setup:
Helvetica variants are pre-loaded by default, so no explicit load() call is needed for them.
// Standard fonts are ready to use immediately
const font = fontStore.getFont({
fontFamily: 'Helvetica',
fontWeight: 700,
fontStyle: 'normal',
});
The library implements CSS font-weight resolution rules. You can specify font weights as numbers or keywords:
| Keyword | Numeric Value |
|---|---|
thin, hairline | 100 |
ultralight, extralight | 200 |
light | 300 |
normal | 400 |
medium | 500 |
semibold, demibold | 600 |
bold | 700 |
ultrabold, extrabold | 800 |
heavy, black | 900 |
When an exact weight match isn't available, the library uses CSS fallback rules to find the closest available weight.
Register an emoji source to enable emoji rendering:
// Using a URL pattern (must end with trailing slash)
fontStore.registerEmojiSource({
url: 'https://cdnjs.cloudflare.com/ajax/libs/twemoji/14.0.2/72x72/',
format: 'png',
});
// Using a custom builder function
fontStore.registerEmojiSource({
builder: (code) => `https://example.com/emojis/${code}.png`,
});
The code parameter passed to the builder is a hyphen-separated string of hex code points (e.g., 1f44d for 👍 or 1f44d-1f3ff for 👍🏿).
Set withVariationSelectors: true if your emoji source requires variation selectors in the code points.
Register a hyphenation callback for text wrapping:
import hyphenationCallback from 'hyphen/en';
fontStore.registerHyphenationCallback(hyphenationCallback);
register(data: SingleLoad | BulkLoad)Register a font or font family.
load(descriptor: FontDescriptor): Promise<void>Load a specific font variant.
getFont(descriptor: FontDescriptor): FontSourceGet a font source matching the descriptor.
registerEmojiSource(source: EmojiSource)Register an emoji image source.
registerHyphenationCallback(callback: HyphenationCallback)Register a hyphenation callback function.
reset()Reset all loaded font data (keeps registrations).
clear()Clear all font registrations, emoji source, and hyphenation callback.
getRegisteredFontFamilies(): string[]Get list of registered font family names.
getRegisteredFonts(): Record<string, FontFamily>Get all registered font families with their sources.
getEmojiSource(): EmojiSource | nullGet the registered emoji source, if any.
getHyphenationCallback(): HyphenationCallback | nullGet the registered hyphenation callback, if any.
type FontDescriptor = {
fontFamily: string;
fontStyle?: 'normal' | 'italic' | 'oblique';
fontWeight?: FontWeight;
};
type FontWeight =
| number
| 'thin'
| 'hairline'
| 'ultralight'
| 'extralight'
| 'light'
| 'normal'
| 'medium'
| 'semibold'
| 'demibold'
| 'bold'
| 'ultrabold'
| 'extrabold'
| 'heavy'
| 'black';
type SingleLoad = {
family: string;
src: string;
fontStyle?: 'normal' | 'italic' | 'oblique';
fontWeight?: FontWeight;
postscriptName?: string;
method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
headers?: Record<string, string>;
body?: any;
};
type BulkLoad = {
family: string;
fonts: FontSource[];
};
type EmojiSource =
| { url: string; format?: string; withVariationSelectors?: boolean }
| { builder: (code: string) => string; withVariationSelectors?: boolean };
type HyphenationCallback = (word: string) => string[];
MIT