# FontRegistry

Loads fonts outside a viewer — for a font picker of your own, or to check what a font covers. A viewer builds its own registry from [fonts](https://kernstra.com/docs/web-sdk/config/fonts); one you construct is never seen by a viewer. No member needs a license feature or a document.

The catalog is `BUILTIN_FONTS` plus what you registered, as `FontDefinition`s: `{ id, displayName, category, source, cssFallback, ttfPath?, ttfUrl?, ttfBytes? }`, where `category` is `'sans-serif' | 'serif' | 'monospace' | 'display'`, `source` is `'standard' | 'bundled' | 'custom'`, `cssFallback` the CSS font-family stack for previews, `ttfPath` the file name under `fonts.fontsBaseUrl` (self-hosting), and `ttfUrl` / `ttfBytes` set for custom fonts.

- Kind: class
- Access: `new FontRegistry(fontsConfig?)`

## Usage

```ts
import { FontRegistry } from '@kernstra/pdf-web-sdk';

const fonts = new FontRegistry(fontsConfig); // optional: the same FontsConfig a viewer takes
fonts.registerCustomFontUrl({ id: 'brand', displayName: 'Brand Sans', ttfUrl: '/fonts/brand.ttf' });

for (const font of fonts.getAll()) {
  picker.add(new Option(font.displayName, font.id));
}

fonts.destroy();
```

## Constructor

```ts
new FontRegistry(config?: FontsConfig)
```

Constructing one with [fontsBaseUrl](https://kernstra.com/docs/web-sdk/config/fonts/fontsbaseurl) under a license without self-hosting throws `FEATURE_NOT_LICENSED`.

| Parameter | Type | Description |
| --- | --- | --- |
| `config?` | `FontsConfig` | The same [FontsConfig](https://kernstra.com/docs/web-sdk/config/fonts) a viewer takes. |

## Registering

### `registerCustomFont`

```ts
registerCustomFont(font: CustomFont & { ttfBytes: Uint8Array }): void
```

Adds a font from TTF/OTF bytes.

- Kind: method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `font` | `CustomFont & { ttfBytes: Uint8Array }` | `{ id, displayName, ttfBytes, category?, cssFallback? }` — the same bag as a [fonts.customFonts](https://kernstra.com/docs/web-sdk/config/fonts/customfonts) entry. `category` defaults to `'sans-serif'`; `cssFallback` to the display name, then `sans-serif`. |

Returns `void`

```ts
const ttfBytes = new Uint8Array(await (await fetch('/fonts/brand.ttf')).arrayBuffer());
fonts.registerCustomFont({ id: 'brand', displayName: 'Brand Sans', ttfBytes, category: 'sans-serif' });
```

Page: https://kernstra.com/docs/web-sdk/api/fontregistry/registercustomfont

### `registerCustomFontUrl`

```ts
registerCustomFontUrl(font: CustomFont & { ttfUrl: string }): void
```

Adds a font fetched from `ttfUrl` on first use.

- Kind: method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `font` | `CustomFont & { ttfUrl: string }` | `{ id, displayName, ttfUrl, category?, cssFallback? }` — the same bag as a [fonts.customFonts](https://kernstra.com/docs/web-sdk/config/fonts/customfonts) entry. `category` defaults to `'sans-serif'`. |

Returns `void`

```ts
fonts.registerCustomFontUrl({ id: 'brand', displayName: 'Brand Sans', ttfUrl: '/fonts/brand.ttf' });
```

Page: https://kernstra.com/docs/web-sdk/api/fontregistry/registercustomfonturl

## Catalog

### `getAll`

```ts
getAll(): FontDefinition[]
```

The catalog: `BUILTIN_FONTS` plus what you registered.

- Kind: method
- Since: 1.0.0

Returns `FontDefinition[]`

```ts
const serifs = fonts.getAll().filter((f) => f.category === 'serif');
```

Page: https://kernstra.com/docs/web-sdk/api/fontregistry/getall

### `getDefinition`

```ts
getDefinition(id: string): FontDefinition | undefined
```

One entry of the catalog, by id.

- Kind: method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | `string` | The font's id. |

Returns `FontDefinition | undefined`: `undefined` when no font has that id.

```ts
const brand = fonts.getDefinition('brand');
```

Page: https://kernstra.com/docs/web-sdk/api/fontregistry/getdefinition

## Lifecycle

### `destroy`

```ts
destroy(): void
```

Drops the loaded bytes and the preview faces it added to `document.fonts`.

- Kind: method
- Since: 1.0.0

Returns `void`

```ts
fonts.destroy();
```

Page: https://kernstra.com/docs/web-sdk/api/fontregistry/destroy

Web page: https://kernstra.com/docs/web-sdk/api/fontregistry