---
title: "@quario/pdf — API reference"
description: "The PDF render target for quario, covering the pdf() factory, page geometry, document metadata and embeddable fonts."
url: "https://getquario.com/docs/reference/pdf"
---

# @quario/pdf

The paginated PDF render target. It typesets the pages itself and resolves the
document bytes.

## `pdf(options?)`

```ts title="signature"
function pdf(options?: PdfOptions): Target<'pdf', Promise<Uint8Array>>
```

It returns the target. It validates options at the factory call, and takes three:
`page`, `meta` and `fonts`. Any other key, or one of the wrong type, throws a
`TypeError` naming the path. The factory copies `meta` as it reads it, so
mutating that object afterwards changes nothing the target writes.

## `capabilities`

```ts title="signature"
const capabilities: {
  readonly target: 'pdf'
  readonly declarations: Readonly<Record<string, Fate>>
}

type Fate = 'resolved' | 'approximated' | 'withdrawn' | 'unread'
```

What this target makes of each declaration the [support
matrix](https://getquario.com/docs/reference/support-matrix.md) names, keyed by the schema name an
author writes. Pass it to `plan(schema, functions, { targets })` to check a
document’s `required` marking before you render. It carries no version of its
own. The package that ships it sets the version.

## `PdfOptions`

| Field | Type | Meaning |
| --- | --- | --- |
| `page` | `PdfPage` | Page geometry. |
| `meta` | `PdfMeta` | Optional `/Info` dictionary. |
| `fonts` | `Record<string, PdfFontFamily>` | TrueType families to embed, selected from styles by `family`. |

## `PdfPage`

```ts title="signature"
interface PdfPage {
  size?: 'A4' | 'letter' | [number, number]
  margin?: number | { top: number; right: number; bottom: number; left: number }
}
```

`size` defaults to `'A4'`, which is 595.28 by 841.89 points. An array is a
custom `[width, height]` in points. `margin` is points on all four sides, or
each side named, defaulting to 54. Each key applies when the document doesn’t
declare its own `page.size` or `page.margin`, and declaring one in both places
is a render error. The document turns the paper, through `page.orientation`.

## `PdfMeta`

```ts title="signature"
interface PdfMeta {
  title?: string
  author?: string
  subject?: string
}
```

Each field takes a string only, never a date, so output stays deterministic.

## `PdfFontFamily`

```ts title="signature"
interface PdfFontFamily {
  regular: Uint8Array | ArrayBuffer
  bold?: Uint8Array | ArrayBuffer
  italic?: Uint8Array | ArrayBuffer
  boldItalic?: Uint8Array | ArrayBuffer
}
```

The target uses `regular` for a missing variant. Embedding requires the optional peer
`fontkit`. The base-14 families need nothing extra. A parser that won’t load
reports `options.fonts: the font parser did not load. Install fontkit to use
TrueType families`, with whatever actually threw attached as `cause`, rather
than advising an install you may already have made.

```json
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://getquario.com/"},{"@type":"ListItem","position":2,"name":"Docs","item":"https://getquario.com/docs"},{"@type":"ListItem","position":3,"name":"@quario/pdf","item":"https://getquario.com/docs/reference/pdf"}]}
```