---
title: "@quario/xlsx — API reference"
description: "The spreadsheet render target for quario, covering the xlsx() factory and its document metadata."
url: "https://getquario.com/docs/reference/xlsx"
---

# @quario/xlsx

The spreadsheet render target. Resolves workbook bytes with typed cells.

## `xlsx(options?)`

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

Returns the target. It takes three options, `meta`, `page` and `filter`. Any
other key, or one of the wrong type, throws a `TypeError` naming the path. The
factory reads `meta` once and copies it, so mutating that object between renders
no longer changes the workbook.

## `capabilities`

```ts title="signature"
const capabilities: {
  readonly target: 'xlsx'
  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.

## `XlsxOptions`

| Field | Type | Meaning |
| --- | --- | --- |
| `meta` | `XlsxMeta` | Optional document information. |
| `page` | `XlsxPage` | Print setup, written to every worksheet. |
| `filter` | `boolean` | Put an autofilter over a worksheet’s one table. Off unless asked. |

## `XlsxPage`

```ts title="signature"
interface XlsxPage {
  size?: 'A4' | 'letter'
  margin?: number | { top: number; right: number; bottom: number; left: number }
  orientation?: 'portrait' | 'landscape'
  fit?: boolean
}
```

`margin` is all four page margins in points, or each side named. The target
refuses a paper name it doesn’t know and a margin that leaves the page no room.
Each key applies when the document
doesn’t declare its own `page.size`, `page.orientation` or `page.margin`, and
declaring the same key in both places is a render error. `fit` scales a
worksheet to one page wide, and as many pages tall as it takes. It’s a
different key from the `fit` an image item carries. This target withdraws a
`[width, height]` size, because a worksheet prints on named stock.

## `XlsxMeta`

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

Never includes dates, so the document model stays deterministic.

This target takes no font mapping. An unmapped `family` name passes through for
the spreadsheet application to resolve.

```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/xlsx","item":"https://getquario.com/docs/reference/xlsx"}]}
```