• preview
  • react
  • npm
  • receipts
  • templates
  • editor

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.

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:

Views of the receipt
Paper width
Harbour Cafe
Order 1042
QR Code: https://example.com/orders/1042
Harbour Cafe
Order 1042
QR Code: https://example.com/orders/1042
[
  {
    "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"
  }
]

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.

            H a r b o u r   C a f e 
                   Order 1042
Tea                                         2.10
Scone                                       3.20
------------------------------------------------
Total                                       5.30
One document of four blocks on 80 mm paper (48 characters a line) and on 58 mm paper (32).

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

Views of the receipt
Paper width
Harbour Cafe
Order 1042
QR Code: https://example.com/orders/1042
"^^^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} |

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

            H a r b o u r   C a f e 
                   Order 1042
Tea                                         2.10
Scone                                       3.20
------------------------------------------------
Total                                       5.30
A receipt written as ReceiptLine text.

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.

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.

Choose how to embed it
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" />;
}
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

NoteThe 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.

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.Your softwareTillcast APIchecks, rendersQueue123Dashboardprinters, keysStatus pageservice health6PrinterPrinter URLprivate4asks every few seconds5
  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.
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.

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.

What @tillcast/preview adds to a pageA bar chart of KB after gzip. styles.css is 1.3, the preview JavaScript 11.0 and the renderer WebAssembly file 281.7.KB after gzip level 90.0100.0200.0300.01.311.0281.7styles.csspreviewJavaScriptrenderer .wasm
What @tillcast/preview adds to a pageSource: 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.
Data table

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

What @tillcast/preview adds to a page (KB after gzip level 9)
LabelValue (KB after gzip level 9)
styles.css1.3
preview JavaScript11.0
renderer .wasm281.7

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:

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