@nutshelllabs/font

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.

Installation

yarn add @nutshelllabs/font

Usage

import FontStore from '@nutshelllabs/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,
});

Font Sources

The library supports multiple font source types:

Remote URL

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,
});

Local File (Node.js)

fontStore.register({
  family: 'Custom Font',
  src: '/path/to/font.ttf',
});

Note: Local file resolution is only available in Node.js environments.

Base64 Data URI

fontStore.register({
  family: 'Embedded Font',
  src: 'data:font/ttf;base64,AAEAAAALAIAAAwAwT1MvMg...',
});

Registering Font Families

Single Font

fontStore.register({
  family: 'Roboto',
  src: 'https://example.com/fonts/Roboto-Regular.ttf',
  fontWeight: 400,
  fontStyle: 'normal',
});

Multiple Weights and Styles (Bulk Registration)

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',
    },
  ],
});

Standard Fonts

The following PDF standard fonts are pre-registered and available without any additional setup:

• Helvetica (with Bold, Oblique, and BoldOblique variants)
• Courier (with Bold, Oblique, and BoldOblique variants)
• Times-Roman (with Bold, Italic, and BoldItalic variants)

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',
});

Font Weight Resolution

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.

Emoji Support

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.

Hyphenation

Register a hyphenation callback for text wrapping:

import hyphenationCallback from 'hyphen/en';

fontStore.registerHyphenationCallback(hyphenationCallback);

API Reference

FontStore

register(data: SingleLoad | BulkLoad)

Register a font or font family.

load(descriptor: FontDescriptor): Promise<void>

Load a specific font variant.

getFont(descriptor: FontDescriptor): FontSource

Get 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 | null

Get the registered emoji source, if any.

getHyphenationCallback(): HyphenationCallback | null

Get the registered hyphenation callback, if any.

Types

FontDescriptor

type FontDescriptor = {
  fontFamily: string;
  fontStyle?: 'normal' | 'italic' | 'oblique';
  fontWeight?: FontWeight;
};

FontWeight

type FontWeight =
  | number
  | 'thin'
  | 'hairline'
  | 'ultralight'
  | 'extralight'
  | 'light'
  | 'normal'
  | 'medium'
  | 'semibold'
  | 'demibold'
  | 'bold'
  | 'ultrabold'
  | 'extrabold'
  | 'heavy'
  | 'black';

SingleLoad

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;
};

BulkLoad

type BulkLoad = {
  family: string;
  fonts: FontSource[];
};

EmojiSource

type EmojiSource =
  | { url: string; format?: string; withVariationSelectors?: boolean }
  | { builder: (code: string) => string; withVariationSelectors?: boolean };

HyphenationCallback

type HyphenationCallback = (word: string) => string[];

Supported Font Formats

• TTF - TrueType Font
• WOFF - Web Open Font Format
• WOFF2 - Web Open Font Format 2.0

License

MIT