---
title: "@quario/editor — API reference"
description: "The embeddable banded document designer for quario: the quario-editor custom element, its properties, its change event and its boxes method."
url: "https://getquario.com/docs/reference/editor"
---

# @quario/editor

The banded document designer. It takes your `quario()` instance as a property
and reports the edited definition on every change. Its design surface is the
same layout the viewer paints. 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-editor'
```

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

## `QuarioEditor`

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

| Property | Type | Meaning |
| --- | --- | --- |
| `schema` | `ReportSchema` | The definition under edit. |
| `instance` | `Quario` | The instance it plans and renders through. |
| `functions` | `Record<string, (...args: never[]) => unknown>` | The registry the definition may call. |
| `data` | `unknown` | Sample data for the preview. |
| `page` | `EditorPage` | Page geometry. |
| `fonts` | `EditorFonts` | TrueType families for measurement. |
| `colorScheme` | `'light'`, `'dark'`, `'auto'` | Chrome only. |
| `strings` | `EditorStrings` | Replaces the chrome’s English, key by key. |

```ts title="signature"
get renderComplete(): Promise<boolean>
boxes(path: string): DOMRect[]
```

Since 0.8.0 the element returns every hit box the render reported for `path`,
in document order, as client rectangles. It returns boxes for every page,
whether or not that page has an element yet. Use it to anchor your own UI to a node,
such as a badge, a comment marker, or a step in a tour. Await
`renderComplete` first.

The array is empty for a node that drew nothing, for a group, and for a path
the schema doesn’t have. It’s empty before any render lands.

## Styling the surface

Chrome styles live on `--qe-*` custom properties under `qe-*` class names. The
tokens are the theming surface. The class names are a reference seam, not a
frozen vocabulary, and 0.8.0 renames four of them. If you style the design
surface directly, rename as follows.

| Was | Is now |
| --- | --- |
| `.qe-hit` | `.qe-selection` |
| `.qe-boxes`, the layer over the sheet | `.qe-overlay` |
| `.qe-overlay`, the layer that holds grips, carets, and placeholders | `.qe-furniture` |

0.8.0 drops `.qe-box`. No element represents a hit box any more, so call
`boxes(path)` to find where the render drew a node. The `--qe-*` tokens,
`.qe-peek` and `.qe-lifted` stay as they were.

0.10.0 adds `--qe-icon-active` and `--qe-active`, matching the viewer’s
`--qv-icon-active` and `--qv-active`.

## Events

```ts title="signature"
interface QuarioEditorEventMap {
  change: CustomEvent<EditorChangeDetail>
  error: CustomEvent<EditorErrorDetail>
}

interface EditorChangeDetail {
  schema: ReportSchema
  problems: readonly Problem[]
  warnings: readonly Warning[]
}

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

Every change carries the edited definition alongside the problems and the
warnings the same traversal found. Nothing that gates on `problems` should gate
on `warnings`: a document carrying only warnings compiles and renders.

## Types

```ts title="signature"
type EditorPage = LayoutPage
type EditorFonts = LayoutFonts
```

### `EditorStrings`

Every key is optional, and a key left out stays English, as in the viewer’s
`ViewerStrings`. The record doesn’t reach the Issues list, an error’s own
message, the marking, or the schema’s field names.

| Key | The function gets | English |
| --- | --- | --- |
| `hidden` | The template of a hidden item | `hidden: {{ @.sku }}` |
| `asText` | The name of a colour style | `color as text` |
| `showGroup` | The name of a style group | `Show every Border name` |
| `hideGroup` | The name of a style group | `Show only what Border declares` |
| `pageName` | The page number and the number of pages | `Page 3 of 120` |

The other keys take a string.

| Key | English |
| --- | --- |
| `undo` | `Undo` |
| `redo` | `Redo` |
| `reveal` | `Reveal` |
| `revealHint` | `Reveal what the render leaves out` |
| `dismiss` | `Dismiss` |
| `renderFailed` | `The report could not be displayed.` |
| `updateFailed` | `The report could not be updated.` |
| `misconfigured` | `This editor is misconfigured — the report itself was not the problem.` |
| `addItemAfter` | `Add a text item after this one` |
| `duplicate` | `Duplicate` |
| `delete` | `Delete` |
| `emptyBandPlaceholder` | `empty band` |
| `emptyText` | `(empty)` |
| `document` | `Document` |
| `documentNote` | `The default every band inherits.` |
| `offPage` | `Bands off the page` |
| `pageHeader` | `Page header` |
| `pageFooter` | `Page footer` |
| `empty` | `Empty` |
| `properties` | `Properties` |
| `selectPrompt` | `Select something in the preview.` |
| `offPageNote` | `Nothing on the sheet is this band. Its items are here.` |
| `noItems` | `No items.` |
| `addTextItem` | `Add a text item` |
| `moveUp` | `Move up` |
| `moveDown` | `Move down` |
| `remove` | `Remove` |
| `addColumn` | `Add column` |
| `addTotalRow` | `Add total row` |
| `merge` | `Merge` |
| `unmerge` | `Unmerge` |
| `addHeaderBand` | `Add a header band` |
| `removeHeaderBand` | `Remove the header band` |
| `addFooterBand` | `Add a footer band` |
| `removeFooterBand` | `Remove the footer band` |
| `spliceGroup` | `Remove the group, keeping its items` |
| `discardGroup` | `Remove the group and its bands` |
| `groups` | `Groups` |
| `noGroups` | `No groups.` |
| `issues` | `Issues` |
| `noIssues` | `None.` |
| `switchExpression` | `Switch between a value and an expression` |
| `clear` | `Clear` |
| `noChoice` | `(none)` |
| `defaultFamily` | `(default)` |
| `noColour` | `none` |
| `linkHint` | `https://… or #label` |
| `alignLeft` | `Align left` |
| `alignCentre` | `Align centre` |
| `alignRight` | `Align right` |
| `alignTop` | `Align top` |
| `alignMiddle` | `Align middle` |
| `alignBottom` | `Align bottom` |
| `runs` | `runs` |
| `deleteRun` | `Delete this run` |
| `textGroup` | `Text` |
| `alignmentGroup` | `Alignment` |
| `fillGroup` | `Fill` |
| `formatGroup` | `Format` |
| `linkGroup` | `Link` |
| `spacingGroup` | `Spacing` |
| `paddingGroup` | `Padding` |
| `borderGroup` | `Border` |
| `otherGroup` | `Other` |
| `before` | `Before` |
| `after` | `After` |
| `top` | `T` |
| `right` | `R` |
| `bottom` | `B` |
| `left` | `L` |
| `width` | `Width` |
| `line` | `Line` |
| `colour` | `Colour` |

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