# @react-pdf/font

> Register font and emoji source for react-pdf document

Latest version **4.1.2** (published 2026-08-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install @react-pdf/font
pnpm add @react-pdf/font
yarn add @react-pdf/font
bun add @react-pdf/font
```

## Health

**Score 80/100 (A)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score; popular repo.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.1.2 |
| Published | 2026-08-27 |
| First published | 2020-07-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 42.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 16813 |
| Author | Diego Muracciole |
| Maintainers | diegomura |

## Links

- npm: https://www.npmjs.com/package/@react-pdf/font
- Repository: https://github.com/diegomura/react-pdf
- Homepage: https://github.com/diegomura/react-pdf#readme
- Issues: https://github.com/diegomura/react-pdf/issues
- npm.io page: https://npm.io/package/@react-pdf/font

## Dependencies (4)

- [is-url](https://npm.io/package/is-url.md) ^1.2.4
- [pdfkit](https://npm.io/package/pdfkit.md) 0.20.1
- [fontkit](https://npm.io/package/fontkit.md) ^2.0.2
- [@react-pdf/types](https://npm.io/package/@react-pdf/types.md) ^2.14.0

## Recent versions

- 4.1.2 (latest) — 2026-08-27
- 2.0.0-beta.20 (beta) — 2021-04-05
- 4.1.1 — 2026-08-24
- 4.1.0 — 2026-08-23
- 4.0.11 — 2026-08-23
- 4.0.10 — 2026-08-14
- 4.0.9 — 2026-08-08
- 4.0.8 — 2026-04-15
- 4.0.7 — 2026-04-15
- 4.0.6 — 2026-04-06
- 4.0.5 — 2026-04-04
- 4.0.4 — 2025-12-29
- 4.0.3 — 2025-09-23
- 4.0.2 — 2025-03-05
- 4.0.1 — 2025-03-03
- … 49 more at https://npm.io/package/@react-pdf/font/versions

## README

<p align="center">
  <img src="https://user-images.githubusercontent.com/5600341/27505816-c8bc37aa-587f-11e7-9a86-08a2d081a8b9.png" height="280px">
</p>

# @react-pdf/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

```bash
yarn add @react-pdf/font
```

## Usage

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

## Font Sources

The library supports multiple font source types:

### Remote URL

```js
fontStore.register({
  family: 'Open Sans',
  src: 'https://example.com/fonts/OpenSans-Regular.ttf',
});
```

With custom request options:

```js
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)

```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

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

## Registering Font Families

### Single Font

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

### Multiple Weights and Styles (Bulk Registration)

```js
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.

```js
// 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:

```js
// 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:

```js
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

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

### FontWeight

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

### SingleLoad

```ts
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

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

### EmojiSource

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

### HyphenationCallback

```ts
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

---
_Source: https://npm.io/package/@react-pdf/font · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._