UI components

Worker UI extensions (blocks, modal/fullscreen actions, render: "worker" pages) build their UI only from the pos-* elements below. POS renders each element with its own components, so the UI always matches POS.

Iframe pages do not use this list; they use free-form HTML/React and can add @pancake-pos/ui to look like POS.

#General rules

• Only use elements from this list. Plain HTML tags (div, span, img, table, script…) and unknown elements are not rendered; the extension logs an error in the app's error log.
• Text is only displayed inside pos-text, pos-heading, pos-badge, pos-link, pos-button, pos-banner.
• No style, className or raw HTML. Colors, spacing and fonts follow POS.
• URLs (href, src) must be https://.
• Events pass values through event.detail. In JSX use onClick, onChange… as with regular components. In plain JS, the event name is the part after on in lowercase: onPageChange → addEventListener('pagechange', …).
• Limits: 2,000 elements per extension; pos-table renders at most 500 rows at a time (use pagination).
• Array/object properties (options, columns, rows, pagination) are passed directly in JSX; no JSON.stringify needed.

<pos-stack gap="small">
  <pos-text-field label="Ticket code" value={code} onChange={(e) => setCode(e.detail)} />
  <pos-button variant="primary" loading={saving} onClick={save}>Save</pos-button>
</pos-stack>

Without a framework, build the tree with the runtime's DOM API (see Worker environment):

let code = '';

const field = document.createElement('pos-text-field');
field.label = 'Ticket code';
field.addEventListener('change', (e) => { code = e.detail; });

const button = document.createElement('pos-button');
button.variant = 'primary';
button.textContent = 'Save';
button.addEventListener('click', () => save(code));

const stack = document.createElement('pos-stack');
stack.gap = 'small';
stack.append(field, button);
document.body.append(stack);

#Layout

#pos-stack

Stacks children vertically or horizontally.

#pos-grid

A grid of equal columns; collapses to one column on narrow screens.

#pos-section

A titled container, typically the outer shell of a block.

Slot actions: buttons shown at the right of the title.

<pos-section heading="Customer debt">
  <pos-button slot="actions" variant="tertiary" onClick={reload}>Reload</pos-button>
  <pos-text>...</pos-text>
</pos-section>

#pos-divider

A horizontal rule. No properties.

#Display

#pos-text

#pos-heading

#pos-badge

A short status label.

#pos-money

Displays an amount using the shop's currency and number format.

#pos-link

onClick event: use it when the link performs an action in the app instead of opening a URL (omit href).

#pos-image

POS loads images through a proxy on the sandbox: image types only, up to 5 MB. Images from undeclared domains are not shown (development mode logs a warning).

#Inputs

Properties shared by every input:

Shared events: onChange (event.detail is the new value), onBlur.

POS shows what the user types immediately and then sends onChange to the app, so inputs never lag while the app is busy. If the app sets a value different from what the user just entered (for example uppercasing it or clearing the field), POS shows the app's value. Set value directly in onChange; changing it after an await may overwrite what the user is typing.

#pos-text-field

#pos-number-field

#pos-select

#pos-checkbox

onChange: event.detail is a boolean.

#pos-date-picker

#Feedback

#pos-banner

A prominent message inside the extension.

onDismiss event.

#pos-spinner

#Data and actions

#pos-button

onClick event.

#pos-table

A data table. Cells only hold values (strings, numbers); POS formats them according to the column format.

type Column = {
  key: string;                       // field name in the row
  title: string;
  align?: 'left' | 'center' | 'right';
  width?: number;                    // px
  format?: 'text' | 'number' | 'money' | 'date' | 'datetime';
};

Events:

• onPageChange: event.detail is { page, pageSize }.
• onRowClick: event.detail is the clicked row.

<pos-table
  columns={[
    { key: 'system_id', title: 'Order' },
    { key: 'total_price', title: 'Total', format: 'money', align: 'right' },
  ]}
  rows={orders}
  rowKey="system_id"
  pagination={{ page, pageSize: 20, total }}
  onPageChange={(e) => setPage(e.detail.page)}
/>

#pos-modal

A dialog opened from inside an extension (for example from a button in a block).

Slot footer for the dialog buttons. The onClose event fires when the user closes it or clicks outside.

<pos-modal open={open} heading="Confirm" onClose={() => setOpen(false)}>
  <pos-text>Push this order to the ERP?</pos-text>
  <pos-button slot="footer" onClick={() => setOpen(false)}>Cancel</pos-button>
  <pos-button slot="footer" variant="primary" onClick={push}>Push</pos-button>
</pos-modal>

Actions with presentation: "modal" already get a POS modal; do not wrap them in pos-modal.

#Planned additions

pos-page, pos-tabs, pos-filter-bar, pos-chart (POS draws the chart, the app only passes data), for full-screen Worker UI pages.