---
title: "@quario/viewer — API reference"
description: "The embeddable report viewer for quario, covering the quario-viewer custom element, its properties, events and export targets."
url: "https://getquario.com/docs/reference/viewer"
---

# @quario/viewer

The embeddable viewer. It lays a compiled report out on your page geometry, paints
the pages, and wires the export menu. It compiles nothing and never touches the
event stream. It sits on `@quario/landing`, the package the two surface
elements share, which a host never imports.

## Registering the element

```ts title="signature"
const TAG: 'quario-viewer'
```

Import `@quario/viewer/register` to define the element, or import
`QuarioViewer` and define it yourself.

## `QuarioViewer`

A `LitElement`. Set properties as element properties, not attributes.

| Property | Type | Meaning |
| --- | --- | --- |
| `report` | `ViewableReport` | The compiled report to show. |
| `data` | `unknown` | The dataset to render it against. |
| `params` | `ViewerParams` | Parameter values, passed to the preview’s render and to every export’s. |
| `targets` | `readonly Target[]` | Export targets, listed in array order under one Export button. |
| `page` | `ViewerPage` | Page geometry, the same shape the PDF target takes. |
| `fonts` | `ViewerFonts` | TrueType families, so preview and document break lines alike. |
| `zoom` | `'width'`, `'page'` or number | The zoom it opens at. `'width'` by default. A number runs from 25 to 200. The viewer refuses `'fit'`. |
| `view` | `'continuous'`, `'single'` | The view it opens at. `'continuous'` by default. |
| `filename` | `string` | Base name for a downloaded export. |
| `colorScheme` | `'light'`, `'dark'`, `'auto'` | Chrome only. The sheet stays the document’s. |
| `outline` | `boolean` | Adds a bar control opening an outline panel beside the sheet. Off by default. |
| `bar` | `boolean` | `false` removes the bar and its `bar` slot. On by default. |
| `print` | `boolean` | Adds Print to the export menu. Needs a `pdf` target and `frame-src blob:`. Off by default. |
| `strings` | `ViewerStrings` | Replaces the chrome’s English, key by key. |

Children with `slot="bar"` sit in the bar. They follow the page controls and
come before the search, view, and export controls.

```ts title="signature"
get renderComplete(): Promise<boolean>
```

It resolves once a pending render settles.

```ts title="signature"
get pageNumber(): number
set pageNumber(value: number)
get pageCount(): number
get query(): string
set query(value: string)
```

`pageNumber` counts from 1, and `pageCount` is the length. Both read `0` until
a render lands. A page number past the end goes to the last page, and one
written before a render lands waits for it. `query` searches the whole report,
and `""` searches for nothing. A value of the wrong shape for either is a
`host-option` error and goes nowhere.

The viewer hides each page’s canvas from assistive technology. It lays the
page’s text over the canvas as a group named “Page n of N”. A screen reader
reads that text, and a reader selects and copies it. A run’s `href` is a link
in that layer, `.qv-link` as before, and the layer itself is `.qv-mirror`,
formerly `.qv-links`. A table reads as a table, and restates its headings on
each page it continues onto. `--qv-focus` also tints selected text, and
`--qv-match` colours the current search match.

## Types

```ts title="signature"
type ViewableReport = CompiledReport
type ViewerPage = LayoutPage
type ViewerFonts = LayoutFonts
type ViewerParams = Readonly<Record<string, JsonValue>>
```

### `ViewerStrings`

Every key is optional, and a key left out stays English. A function’s result
goes through `String()`. A function that throws draws the English text, and
the viewer reports it once per record as a `host-option` error. The marking and
an error’s own message aren’t the viewer’s wording, so neither is here.

| Key | The function gets | English |
| --- | --- | --- |
| `view` | The zoom percentage on screen | `View, 62%` |
| `percent` | The percentage of one view-menu row | `50%` |
| `pageCount` | The number of pages | `of 120` |
| `download` | The export format | `Download PDF` |
| `exportFailed` | The export format | `Could not export PDF` |
| `pageName` | The page number and the number of pages | `Page 3 of 120` |
| `matchCount` | The current match and the number of matches, both `0` with none | `3 of 41`, `No matches` |

The other keys take a string.

| Key | English |
| --- | --- |
| `rendering` | `Rendering report` |
| `firstPage` | `First page` |
| `previousPage` | `Previous page` |
| `pageNumber` | `Page number` |
| `nextPage` | `Next page` |
| `lastPage` | `Last page` |
| `viewMenu` | `View` |
| `fitWidth` | `Fit width` |
| `fitPage` | `Fit page` |
| `continuous` | `Continuous` |
| `singlePage` | `Single page` |
| `export` | `Export` |
| `print` | `Print` |
| `search` | `Search` |
| `findField` | `Find in report` |
| `previousMatch` | `Previous match` |
| `nextMatch` | `Next match` |
| `showOutline` | `Show outline` |
| `hideOutline` | `Hide outline` |
| `outline` | `Outline` |
| `noGroups` | `This report has no groups.` |
| `renderFailed` | `Could not render the report` |
| `updateFailed` | `Could not update the report — showing the previous version` |
| `misconfigured` | `This viewer is misconfigured — the report itself was not the problem.` |
| `printFailed` | `Could not print` |
| `dismiss` | `Dismiss` |

Pass the same `fonts` record here and to `pdf({ fonts })`, and hold it across
renders. It’s the identity the viewer remembers a face by.

## Events

```ts title="signature"
interface QuarioViewerEventMap {
  rendered: CustomEvent<undefined>
  error: CustomEvent<ViewerErrorDetail>
  pagechange: CustomEvent<ViewerPageChangeDetail>
  searchchange: CustomEvent<ViewerSearchChangeDetail>
  link: CustomEvent<ViewerLinkDetail>
}

interface ViewerPageChangeDetail {
  pageNumber: number
  pageCount: number
}

interface ViewerSearchChangeDetail {
  query: string
  match: number
  matches: number
}

interface ViewerLinkDetail {
  href: string
}

interface ViewerErrorDetail {
  error: unknown
  kind: 'mount-render' | 'update-render' | 'export' | 'host-option'
}
```

`host-option` names a property the viewer rejected, which reached no render at
all. `mount-render` covers a failure before any render lands on the sheet, and
`update-render` covers one after. `export` covers a download or a print the
viewer couldn’t produce.

`pagechange` and `searchchange` fire only when their values change, the first
render included. `link` fires before a click or a middle click opens a URL link,
and `preventDefault()` keeps the tab from opening. A `#label` link
never fires it.

`addEventListener` and `removeEventListener` take their types from
that map.

An unlicensed report carries the marking on the sheet the viewer paints,
just as it does in an export.

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