Tally UI

ReceiptSheet

ReceiptSheet is WCPOS v2's receipt print sheet, a right-edge sheet with a close icon in its header, the template choice, the printer, the app's preview and Close, Email Receipt, Download PDF and Print.

Import

import { ReceiptSheet, ReceiptPreview } from '@tallyui/components';

Usage

import { useState } from 'react';

const templates = [
  { id: 'receipt', title: 'Receipt' },
  { id: 'gift', title: 'Gift receipt' },
  { id: 'kitchen', title: 'Kitchen ticket', disabled: true },
];

function ReceiptButton() {
  const [open, setOpen] = useState(false);
  const [templateId, setTemplateId] = useState('receipt');
  const [printing, setPrinting] = useState(false);

  return (
    <ReceiptSheet
      open={open}
      onOpenChange={setOpen}
      templates={templates}
      templateId={templateId}
      onTemplateChange={setTemplateId}
      printing={printing}
      onPrint={() => setPrinting(true)}
    >
      <ReceiptPreview items={[{ name: 'Espresso', quantity: 2, total: '$9.00' }]} subtotal="$9.00" tax="$0.72" total="$9.72" />
    </ReceiptSheet>
  );
}

This is the layout of WCPOS v2's receipt print sheet: the title, a Template row and a Printer row, the preview filling the rest of the sheet, and Close, Email Receipt, Download PDF and Print on the right of the footer, in that order. The sheet is props-only: it renders no receipt and prints nothing. Pass the preview as children (Receipt, ReceiptPreview or a rendered template) and do the printing in onPrint.

The Template row shows a picker when there is more than one template, the template's title when there is one, and is left out when there are none. A disabled template is listed but cannot be chosen. The Printer row shows printerLabel, or, when printers is given, WCPOS v2's printer switcher: Auto first, reading Auto — <name> with autoPrinterName, then each printer by name or id. The app keeps the pick and resets it on a template change, as v2 does. Email Receipt appears only when onEmail or email is given; with onEmail alone, open your own email form from it. Download PDF appears only when onDownloadPdf is given; the sheet makes no PDF, so the app makes and saves it in onDownloadPdf, and passes downloadingPdf while it works. Close calls onOpenChange(false).

Email form

Pass email and Email Receipt opens WCPOS v2's email form inside the sheet, between the preview and the footer: an "Email Address" field prefilled from defaultAddress, a "Save email to the customer" switch (off) when saveToCustomer is set, v2's offline notice when offline is set, and Send, which reads "Send when online" when offline. Each opening starts from defaultAddress with the switch off; closing the sheet closes the form.

Send refuses an address that is not name@domain (one @, no spaces) inline ("Enter an email address."). Otherwise it calls onSend({ address, saveToCustomer }) with the trimmed address. The sheet sends nothing: the app sends or queues the receipt in onSend and returns null to close the form, or a message to show in it. While a returned promise is pending, Send shows a spinner and cannot be pressed; an Error that onSend throws or rejects with shows its message (anything else thrown or rejected, an empty string and an empty message show "Could not send the receipt."). When email is given it takes the place of onEmail, which is then not called. After null, the sheet shows "Email sent" in the form's place, or "Receipt email queued" when offline is set (keys receipt.email_sent and receipt.email_queued, testID receipt-email-sent), until the form opens again or the sheet closes. The same form is exported as ReceiptEmailForm for apps that draw the receipt inline.

<ReceiptSheet
  open={open}
  onOpenChange={setOpen}
  templates={templates}
  onPrint={print}
  email={{
    defaultAddress: order.billing.email,
    offline: !online,
    saveToCustomer: Boolean(order.customerId),
    onSend: ({ address, saveToCustomer }) => sendReceipt(order.id, address, saveToCustomer),
  }}
>
  {preview}
</ReceiptSheet>

Props

PropTypeDefaultDescription
openbooleanrequiredWhether the sheet is open
onOpenChange(open: boolean) => voidrequiredCalled when the sheet asks to open or close; Close calls it with false
titlestring'Receipt'The sheet's title
templatesreadonly ReceiptSheetTemplate[]requiredThe templates to choose from
templateIdstring—The chosen template's id; without one the picker reads "Select template"
onTemplateChange(id: string) => void—Called with the id of a newly chosen template
printerLabelstring'Browser print dialog'The Printer row's text
printersreadonly { id: string; name?: string }[]—The device's printers; when given and not empty, the Printer row is a picker
printerIdstring | null—The pick for this print; null or none is Auto, as is an id not in printers
autoPrinterNamestring—The name Auto resolves to, shown after "Auto —"
onPrinterChange(id: string | null) => void—Called with a newly picked printer's id, or null for Auto
onPrint() => voidrequiredCalled when Print is pressed
printingbooleanfalsePrint shows a spinner and cannot be pressed
printedbooleanfalsePrint reads "Print again" instead of "Print receipt"
onEmail() => void—Draws Email Receipt, which calls it
emailReceiptSheetEmail—Draws Email Receipt, which opens the sheet's email form; takes the place of onEmail
onDownloadPdf() => void—Draws Download PDF, which calls it
downloadingPdfbooleanfalseDownload PDF shows a spinner and cannot be pressed
childrenReactNoderequiredThe preview

ReceiptSheetTemplate

interface ReceiptSheetTemplate {
  id: string;
  title: string;
  /** Shown but not choosable. */
  disabled?: boolean;
}

ReceiptSheetEmail

interface ReceiptSheetEmail {
  /** Prefills "Email Address" (v2: the order's billing email). */
  defaultAddress?: string;
  /** Draws v2's offline notice; Send reads "Send when online". */
  offline?: boolean;
  /** Draws "Save email to the customer" (default off). */
  saveToCustomer?: boolean;
  /** Sends or queues the receipt. Returns a refusal to show, or null once sent or queued; the form then shows "Email sent", or "Receipt email queued" when offline. */
  onSend: (input: { address: string; saveToCustomer: boolean }) => Promise<string | null> | string | null;
}