# Preview a receipt in the browser with @tillcast/preview

> Draw a receipt in the browser with @tillcast/preview: blocks or ReceiptLine in, a picture of 80 mm or 58 mm paper out, with no API key and no request to draw.

- Published: 2026-10-21
- Tags: preview, react, npm, receipts, templates, editor
- Author: Tillcast
- Canonical URL: https://tillcast.com/blog/design-receipt-preview-browser/
- Blog: https://tillcast.com/blog/

You can see a receipt before it prints. `@tillcast/preview` is a React component, and a plain function for any other page, that draws a picture of a receipt on 80 mm paper, in the browser, with the renderer Tillcast uses on the server compiled to WebAssembly. It needs no API key and makes no request to draw. The renderer itself, `@tillcast/html-render`, is a second package that also runs in Node. Both are on npm, version 0.x, under Apache-2.0.

## What a receipt document is

A Tillcast job carries a **document**: an array of blocks in print order. Each block is one visible unit and says its `type`: `text`, `row`, `table`, `rule`, `image`, `barcode`, `qr`, `cut` or `feed`. A job can also carry the receipt as `receiptline` text instead: ReceiptLine is a markup language for receipt printers. Both are supported today; other formats may follow, none is decided. Here is one receipt as blocks, drawn on 80 mm and on 58 mm paper. The box has three tabs: Preview, JSON (the document you send in a job) and Text:

**Receipt: One document of four blocks on 80 mm paper (48 characters a line) and on 58 mm paper (32).**

A receipt headed Harbour Cafe in large letters, then Order 1042, two lines Tea 2.10 and Scone 3.20, a rule, a bold total of 5.30 and a QR code.

```json
[
  {"type":"text","text":"Harbour Cafe","align":"center","bold":true,"size":2},
  {"type":"text","text":"Order 1042","align":"center"},
  {"type":"table","columns":["*",{"width":9,"align":"right"}],"rows":[["Tea","2.10"],["Scone","3.20"],{"type":"rule"},[{"text":"Total","bold":true},{"text":"5.30","bold":true}]]},
  {"type":"qr","data":"https://example.com/orders/1042","cell":4,"align":"center"}
]
```

As text, at 48 characters a line:

```text
            H a r b o u r   C a f e 
                   Order 1042
Tea                                         2.10
Scone                                       3.20
------------------------------------------------
Total                                       5.30
```

Drawn at 80 mm (48 characters a line), 58 mm (32 characters a line).

The preview draws either form. Here is a receipt written as ReceiptLine text (its middle tab shows the ReceiptLine source):

**Receipt: A receipt written as ReceiptLine text.**

A receipt headed Harbour Cafe, then Order 1042, Tea, Scone, a rule, the total of 5.30 and a QR code.

```receiptline
"^^^Harbour Cafe
Order 1042
{width:*,9}
|Tea | 2.10|
|Scone | 3.20|
-
|"Total | "5.30|
| {option:qrcode,4,l;code:https://example.com/orders/1042} |
```

As text, at 48 characters a line:

```text
            H a r b o u r   C a f e 
                   Order 1042
Tea                                         2.10
Scone                                       3.20
------------------------------------------------
Total                                       5.30
```

Drawn at 80 mm (48 characters a line).

Blocks are the way to start. The text of a block prints as it is written, so a `|`, a brace or an underscore in a name needs no escaping. In ReceiptLine text those characters are markup, and you escape them yourself. Use ReceiptLine when you already have documents written for other ReceiptLine tools.

## Put the preview in your page

Install it. The renderer comes with it as a dependency.

```sh
npm install @tillcast/preview
```

React 19 is needed for the component only: it is an optional peer dependency, and the plain function does not import React. The package asks for Node `^20.19.0 || >=22.12.0` to install.

### React

```tsx
import { ReceiptPreview, type Block } from "@tillcast/preview";

const blocks: Block[] = [
  { type: "text", text: "Harbour Cafe", align: "center", bold: true, size: 2 },
  { type: "text", text: "Order 1042", align: "center" },
  {
    type: "table",
    columns: ["*", { width: 9, align: "right" }],
    rows: [["Tea", "2.10"], ["Scone", "3.20"], { type: "rule" }, [{ text: "Total", bold: true }, { text: "5.30", bold: true }]],
  },
];

export function Order() {
  return <ReceiptPreview source={{ blocks }} label="Receipt 1042" />;
}
```

### Plain page

```ts
import { mountReceiptPreview, type Block } from "@tillcast/preview/mount";

const blocks: Block[] = [
  { type: "text", text: "Harbour Cafe", align: "center", bold: true, size: 2 },
  { type: "text", text: "Order 1042", align: "center" },
  {
    type: "table",
    columns: ["*", { width: 9, align: "right" }],
    rows: [["Tea", "2.10"], ["Scone", "3.20"], { type: "rule" }, [{ text: "Total", bold: true }, { text: "5.30", bold: true }]],
  },
];

const view = mountReceiptPreview(document.getElementById("receipt")!, { source: { blocks }, label: "Receipt 1042" });

// later: draw another receipt, or remove the preview and its stylesheets
view.update({ source: { receiptline: "Tea|2.10" } });
view.destroy();
```

The preview never throws. A document it cannot draw, or a page whose policy blocks WebAssembly, shows a visible message and calls `onError`. Under Next.js, `ReceiptPreview` itself starts with `"use client"` and renders an empty element on the server, so import it from a client component (a file that starts with `"use client"`) when you pass it callbacks.

### What your page has to allow

> **Note: The Content-Security-Policy, in plain words**
>
> The renderer is WebAssembly. A page with a `script-src` needs one source expression in it, `'wasm-unsafe-eval'`. It lets the page compile WebAssembly. It does not allow `eval()`, `new Function()` or inline scripts. A page with no policy at all needs nothing. A strict policy needs two more things: `connect-src` must allow the origin that serves the `.wasm` file (`'self'` when it is your own), and `img-src` must allow `data:`, because a QR code, a barcode or an image on the receipt is a `data:` image. If something is missing, the preview says which expression and shows the line to add.

## Where it fits, and what it costs

The preview runs in your page, beside the path a job takes to the printer. It is not part of that path and it never calls the API.

**Diagram: The preview runs in your own page. The job goes from your server through the API to the printer.**

Your software builds a receipt as blocks. The preview draws it in the browser so a person can check it, with no request to Tillcast. Your server sends the same document to the API with an API key, the API queues the job, and the printer polls its private URL and prints it. The dashboard and the status page sit beside the API.

1. Your software sends the document to the API: POST /v1/printers/{printer}/jobs, with an API key. Beside this path, @tillcast/preview draws the same document in your own page, with no request to Tillcast.
2. The API checks the document and renders it for the printer's profile.
3. The job waits in the printer's queue.
4. The printer asks for work at its private URL.
5. The job reaches the printer and prints.
6. The dashboard is where a person makes customers, locations, printers and keys and reads the jobs, and the status page shows the state of the service.

Drawing makes no request of any kind. The one request is the renderer's `.wasm` file, fetched once from your own origin on the first receipt, or never if you hand the preview a renderer you created yourself from the file's data. The package's own tests scan the compiled code for `fetch`, `XMLHttpRequest`, `WebSocket` and the like before every release, and count the requests of a real browser.

**Chart: What @tillcast/preview adds to a page**

A bar chart of KB after gzip. styles.css is 1.3, the preview JavaScript 11.0 and the renderer WebAssembly file 281.7.

| Label | Value (KB after gzip level 9) |
| --- | ---: |
| styles.css | 1.3 |
| preview JavaScript | 11.0 |
| renderer .wasm | 281.7 |

Source: Measured on 2026-10-19 with gzip level 9 (zlib; KB are decimal kilobytes) and published in the Size section of the @tillcast/preview README: the package's own JavaScript (13 files, minified as a bundler does; the files on npm are not minified), its stylesheet and the renderer's WebAssembly file. The size gates of both packages fail the build above a ceiling. The .wasm is loaded on first use.

Most of it is the renderer, and the renderer's own JavaScript adds about 5 KB more (after gzip and minification). The renderer's file and its JavaScript load only when the first receipt is drawn: a page that imports the preview and never draws does not load the 282 KB file.

## Paper width and warnings

The default paper is 80 mm, 48 characters a line, with no printer brand. `paperWidth` takes 16 to 96 characters for another roll, and `profile` takes a profile id of `@tillcast/html-render`: `paper-58mm` for 58 mm paper, or the profile of one of the printers Tillcast supports, which adds that printer's warnings. The drawing is a picture of the receipt, not the receipt: the font and the paper differ, the preview says so by default, and the printed paper is the only exact output.

What the renderer notices comes back in `onWarnings`, with the same codes the job for a printer would give. A character that the printer's code page lacks, for example, is the warning `character_unmappable`, and on paper it prints as `?`.

## The same renderer in Node

`@tillcast/html-render` draws a document as HTML for a screen, as HTML for a mail, or as text. It does not print and it does not send mail. Following the example in its README, with the mail format:

```js
import { createRenderer, isError } from "@tillcast/html-render";

const renderer = await createRenderer();
const result = renderer.render({
  document: [{ type: "text", text: "Harbour Cafe", bold: true }],
  profile: "star-starprnt-utf8-80mm",
  format: "email_html",
});
if (isError(result)) throw new Error(`${result.error.code}: ${result.error.message}`);
// result.content is the HTML, result.attachments the pictures as cid: parts, result.warnings the notes
```

If you bundle either package, keep its notices: the renderer is a derivative of ReceiptLine, which is Apache-2.0, so ship `LICENSE`, `ATTRIBUTION.md` and `THIRD_PARTY_LICENSES.txt` of `@tillcast/html-render` with what you build.

## Templates and the editor

The dashboard has a Templates page. It offers four ready receipt templates with sample data and a form, draws each one live in the browser, and shows the blocks it expands to, as a document you can send in a job. Tillcast does not store templates: a job has no `template` field, and you send blocks. Stored templates are in development and not available: do not code against them. A visual editor for your own pages is planned, with no date.

## Next steps

- The docs page [Preview a receipt](https://docs.tillcast.com/preview-a-receipt) covers the same packages. The packages are [`@tillcast/preview`](https://www.npmjs.com/package/@tillcast/preview) and [`@tillcast/html-render`](https://www.npmjs.com/package/@tillcast/html-render), version 0.x, so pin the version you tested.
- [Print your first receipt with one API call](https://tillcast.com/blog/print-your-first-receipt/) sends the same kind of document to a printer.
- [Pricing](https://tillcast.com/pricing/) explains how production is billed.

---

Tillcast is a print API for receipt printers: your software sends a job and a printer in the venue prints it. https://tillcast.com/
