Applies to api_version: "2026-01".
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 use free-form HTML/React. To look like POS, every element here has a React component with the capitalized name (pos-stat → PosStat, pos-table → PosTable), the same properties and { detail } events, in @pancake-pos/ui (see Iframe page UI); slots become properties (slot="actions" → actions={…}).
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,classNameor raw HTML. Colors, spacing and fonts follow POS. - URLs (
href,src) must behttps://. - Events pass values through
event.detail. In JSX useonClick,onChange… as with regular components. In plain JS, the event name is the part afteronin lowercase:onPageChange→addEventListener('pagechange', …). - Limits: 2,000 elements per extension;
pos-tablerenders 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);Standard screens
POS lays elements out like other POS pages; the app only picks the right elements and their order, never colors or spacing.
app.pagepages:pos-pageis the POS page frame.headinganddescriptiongo on the title row at the top, theactionsslot sits on the right next to the primary button (pos.page.setPrimaryAction); content is stacked on the gray background.- Blocks: a
pos-sectiondirectly inpos-pageis a white card; apos-sectioninside anotherpos-sectionis a flat group; in blocks and modals,pos-sectionis a white card with a thin border.pos-tableandpos-chartplaced directly inpos-pageget a white card automatically. - Numbers:
pos-statin a 3–5 columnpos-grid; do not combinepos-sectionandpos-headinginto metric cards. - Filters: put filter inputs in one
pos-filter-barat the top of the page or of a section; usepos-date-rangefor periods. For status filters usepos-tabswithbadge: chips with counts like the status bar of POS list pages. - Buttons: tool buttons (reload, filter, settings) are icon-only buttons with a
tooltip; group secondary actions in apos-menu-button. Per-row actions (Edit, Skip) go in the table'srowActionscolumn, not in a form below the table. Show statuses in tables with aformat: 'badge'column; open a row's details in apos-drawerorpos-modalwithpos-description-listandpos-timeline. - Settings: one
pos-switchrow (applies at once) orpos-radio-groupper option, grouped inpos-section; times usepos-time-picker. - Do not repeat the page title in the content, use emoji or decorative characters in labels (use the
toneofpos-statandpos-badge), nestpos-sectionmore than two levels deep, or wrap every element in its ownpos-section. - Drop all-zero or empty rows from charts and tables; show names instead of ids (look names up through the Open API).
Report page
<pos-page description="Actual delivery times against the carriers' committed SLA" width="full">
<pos-button slot="actions" icon="download" onClick={exportCsv}>Export</pos-button>
<pos-filter-bar>
<pos-date-range label="Order created" value={range} onChange={(e) => e.detail && setRange(e.detail)} />
<pos-button icon="refresh" tooltip="Reload" onClick={load} />
</pos-filter-bar>
<pos-grid columns={4}>
<pos-stat label="On-time rate" value={58.3} format="percent" help="12 delivered orders" />
<pos-stat label="On time" value={7} tone="success" selected={state === 'on_time'} onClick={() => setState('on_time')} />
<pos-stat label="Late" value={5} tone="critical" selected={state === 'late'} onClick={() => setState('late')} />
<pos-stat label="Shipping fees" value={2450000} format="money" />
</pos-grid>
<pos-section heading="By carrier">
<pos-chart type="bar" xKey="carrier" data={byCarrier} series={[{ key: 'rate', label: 'On-time rate (%)' }]} onSelect={(e) => setCarrier(e.detail.x)} />
</pos-section>
</pos-page>List page
<pos-page width="full">
<pos-button slot="actions" icon="upload" onClick={importFile}>Import</pos-button>
<pos-menu-button slot="actions" items={[{ id: 'csv', label: 'Export CSV' }]} onSelect={exportAs} />
<pos-section>
<pos-filter-bar>
<pos-text-field label="Search order code" value={search} onChange={(e) => setSearch(e.detail)} />
<pos-select label="Warehouse" options={warehouses} value={warehouse} onChange={(e) => setWarehouse(e.detail)} />
</pos-filter-bar>
<pos-tabs tabs={[{ id: 'all', label: 'All', badge: 169 }, { id: 'late', label: 'Late', badge: 12 }]} selected={status} onChange={(e) => setStatus(e.detail)}>
<pos-table
columns={[
{ key: 'code', title: 'Order', format: 'link' },
{ key: 'customer', title: 'Customer', subtitle: 'phone' },
{ key: 'state', title: 'SLA', format: 'badge', tones: { Late: 'critical', 'On time': 'success' } },
{ key: 'fee', title: 'Shipping fee', format: 'money', align: 'right', sortable: true },
]}
rows={rows}
sort={sort}
pagination={{ page, pageSize: 30, total }}
onSortChange={(e) => setSort(e.detail)}
onPageChange={(e) => setPage(e.detail.page)}
onCellClick={(e) => setDetail(e.detail.row)}
/>
</pos-tabs>
</pos-section>
</pos-page><pos-drawer open={!!detail} heading={detail?.code} onClose={() => setDetail(null)}>
<pos-description-list items={[{ label: 'Carrier', value: detail?.carrier }, { label: 'Shipping fee', value: detail?.fee, format: 'money' }]} />
<pos-timeline items={detail?.events ?? []} />
</pos-drawer>The page's primary button (for example "Sync") is set with pos.page.setPrimaryAction and always comes last on the title row. Export Excel from the table's own columns and rows with pos.download({ sheet }); open an order in POS with pos.navigate({ resource: 'order', id }). Complete report and list pages: the get_example tool of the MCP.
Layout
pos-stack
Stacks children vertically or horizontally.
| Property | Type | Default | Description |
|---|---|---|---|
direction |
'vertical' | 'horizontal' |
'vertical' |
Stacking direction |
gap |
'none' | 'small' | 'medium' | 'large' |
'medium' |
Space between children |
align |
'start' | 'center' | 'end' | 'stretch' |
'stretch' |
Cross-axis alignment |
justify |
'start' | 'center' | 'end' | 'space-between' |
'start' |
Main-axis alignment |
wrap |
boolean |
false |
Allow wrapping (with horizontal) |
pos-grid
A grid of equal columns; cells narrower than 180 px wrap to the next row (one column on narrow screens).
| Property | Type | Default | Description |
|---|---|---|---|
columns |
1–6 |
2 |
Number of columns |
gap |
'none' | 'small' | 'medium' | 'large' |
'medium' |
Spacing |
pos-section
A titled block. Directly in pos-page it is a white card; inside another pos-section it is a flat group; in blocks and modals it is a white card with a thin border (see Standard screens).
| Property | Type | Description |
|---|---|---|
heading |
string |
Title |
description |
string |
Short text below the title |
Slot actions: pos-button, pos-link and pos-menu-button 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
| Property | Type | Default |
|---|---|---|
tone |
'default' | 'subdued' | 'success' | 'warning' | 'critical' |
'default' |
size |
'small' | 'medium' | 'large' |
'medium' |
weight |
'regular' | 'semibold' | 'bold' |
'regular' |
pos-heading
| Property | Type | Default |
|---|---|---|
level |
1–4 |
3 |
Font size: 1 20 px (same as the page title), 2 18 px, 3 16 px (same as section titles), 4 14 px.
pos-badge
A short status label.
| Property | Type | Default |
|---|---|---|
tone |
'default' | 'info' | 'success' | 'warning' | 'critical' |
'default' |
pos-money
Displays an amount using the shop's currency and number format.
| Property | Type | Description |
|---|---|---|
value |
number |
Amount |
currency |
string |
Currency code like shop.currency (ISO 4217, or VND100, PHP100); defaults to the shop currency |
tone |
same as pos-text |
Text color |
pos-link
| Property | Type | Description |
|---|---|---|
href |
string |
https:// URL, always opens in a new tab |
onClick event: use it when the link performs an action in the app instead of opening a URL (omit href).
pos-image
| Property | Type | Default | Description |
|---|---|---|---|
src |
string |
An https:// URL on a domain listed in network.allowed_origins, or public/<file name> for a file in the project's public/ folder |
|
alt |
string |
Alternative text | |
width, height |
number |
Size (px) | |
fit |
'cover' | 'contain' |
'cover' |
How the image fits |
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).
pos-description-list
Label – value pairs like the order info blocks of POS (gray label on the left, value on the right); for modals, panels and detail blocks.
| Property | Type | Default | Description |
|---|---|---|---|
items |
Item[] |
[] |
Up to 50 rows |
columns |
1–4 |
1 |
Number of columns; cells narrower than 220 px wrap |
type Item = {
label: string;
value: string | number | null; // null or empty shows "—"
format?: 'text' | 'number' | 'money' | 'percent' | 'date' | 'datetime' | 'badge';
tone?: 'default' | 'info' | 'success' | 'warning' | 'critical'; // color when format is badge
};<pos-description-list columns={2} items={[
{ label: 'Carrier', value: 'GHN' },
{ label: 'Shipping fee', value: 25000, format: 'money' },
{ label: 'SLA', value: '2 days late', format: 'badge', tone: 'critical' },
]} />pos-timeline
A timeline: order journey, change history.
| Property | Type | Description |
|---|---|---|
items |
{ title: string; time?: string; description?: string; tone?: Tone }[] |
Up to 100 steps; an ISO 8601 time is formatted like POS, other text is shown as is; tone is the dot color |
Inputs
Properties shared by every input:
| Property | Type | Description |
|---|---|---|
label |
string |
Label |
value |
depends on the component | Current value (controlled component) |
disabled |
boolean |
Disable the input |
required |
boolean |
Show the required marker (does not validate) |
error |
string |
Error message below the input |
help |
string |
Hint below the 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
| Property | Type | Description |
|---|---|---|
value |
string |
|
placeholder |
string |
|
multiline |
boolean | number |
Multi-line input; a number sets the visible rows |
maxLength |
number |
Character limit |
pos-number-field
| Property | Type | Description |
|---|---|---|
value |
number | null |
|
min, max, step |
number |
|
suffix |
string |
Unit shown after the number, for example "%" |
pos-select
| Property | Type | Description |
|---|---|---|
options |
{ label: string; value: string; disabled?: boolean }[] |
Choices |
value |
string | string[] |
An array with multiple |
multiple |
boolean |
Multiple selection |
placeholder |
string |
|
searchable |
boolean |
Allow typing to filter |
loading |
boolean |
Searching (when searching through the API) |
Searching through the API: when the app listens to onSearch, POS does not filter options itself; it sends what the user types (after 0.3 seconds without typing) in event.detail, and the app calls the Open API and sets new options. Use it for large lists such as products or customers (options holds up to 500 items). The selected value keeps its label when options change.
const [options, setOptions] = useState([]);
const [loading, setLoading] = useState(false);
<pos-select
label="Product"
value={variationId}
options={options}
loading={loading}
onSearch={async (e) => {
setLoading(true);
const res = await pos.api.get(`/shops/${pos.shop.id}/products/variations`, { query: { search: e.detail, page_size: 20 } });
setOptions(res.data.map((v) => ({ value: v.id, label: `${v.product?.name ?? ''} ${v.display_id ?? ''}`.trim() })));
setLoading(false);
}}
onChange={(e) => setVariationId(e.detail)}
/>pos-checkbox
| Property | Type | Description |
|---|---|---|
checked |
boolean |
|
label |
string |
onChange: event.detail is a boolean.
pos-date-picker
| Property | Type | Description |
|---|---|---|
value |
string | null |
Date as YYYY-MM-DD; with time, YYYY-MM-DDTHH:mm |
min, max |
string |
Selectable range, as YYYY-MM-DD |
time |
boolean |
Pick a time as well (false by default) |
Dates and times follow the shop's calendar with no time zone: 2026-10-01T08:30 is 8:30 in the morning as the user picked it.
pos-time-picker
Picks a time of day, for example an order cut-off or "deliver before 12:00".
| Property | Type | Default | Description |
|---|---|---|---|
value |
string | null |
Time as HH:mm |
|
minuteStep |
number |
5 |
Minute step, 1–30 |
placeholder |
string |
pos-switch
An on/off switch like the POS Settings pages: label and description (help) on the left, the switch on the right. Use it for settings that apply as soon as they change; for choices saved with a Save button use pos-checkbox.
| Property | Type | Description |
|---|---|---|
checked |
boolean |
|
loading |
boolean |
Saving the change |
onChange: event.detail is a boolean. Inside pos-filter-bar it is drawn compactly: a small switch with its label.
<pos-switch label="Push orders to ERP automatically" help="Orders moving to Confirmed are pushed right away" checked={on} loading={saving} onChange={(e) => save(e.detail)} />pos-radio-group
Picks one of a few choices (up to 20).
| Property | Type | Default | Description |
|---|---|---|---|
options |
{ label: string; value: string; description?: string; disabled?: boolean }[] |
description is shown in gray under the label (list only) |
|
value |
string | null |
||
variant |
'list' | 'buttons' |
'list' |
list: radio buttons stacked vertically; buttons: joined buttons, for 2–5 short choices |
<pos-radio-group label="Count deadlines in" variant="buttons" value={mode} options={[{ label: 'Calendar days', value: 'calendar' }, { label: 'Working days', value: 'workday' }]} onChange={(e) => setMode(e.detail)} />pos-file-input
Picks a CSV or Excel file on the computer: POS reads it in the browser into a table and sends it to the app. The app needs no file library, and the file is not uploaded anywhere unless the app sends it.
| Property | Type | Default | Description |
|---|---|---|---|
accept |
('csv' | 'xlsx')[] |
both | Accepted file types |
buttonLabel |
string |
"Choose file" | Button text |
loading |
boolean |
false |
The app is processing the file |
onChange: event.detail is { name, size, sheet?, rows, truncated }, or null when the user removes the file. rows is an array of rows, each an array of cells (strings, numbers, true/false, null); the first row is usually the header. Only the first sheet is read; formula cells give their result and date cells become ISO strings.
- Up to 5 MB, 10,000 rows and 50 columns; beyond that
truncated: true. A wrong or damaged file is reported under the field andonChangeis not sent.
<pos-file-input
label="Carrier tracking file"
accept={['xlsx', 'csv']}
onChange={(e) => {
if (!e.detail) return setRows([]);
const [header, ...rows] = e.detail.rows;
const code = header.indexOf('Order');
setRows(rows.map((row) => ({ order: row[code], tracking: row[header.indexOf('Tracking code')] })));
}}
/>pos-date-range
A date range like the period picker of the Statistics pages, with quick choices: Today, Yesterday, Last 7 days, Last 30 days, Start of week to now, Start of month to now, Last month.
| Property | Type | Default | Description |
|---|---|---|---|
value |
{ from: string; to: string } | null |
Dates as YYYY-MM-DD |
|
min, max |
string |
Selectable date limits | |
presets |
boolean |
true |
Show the quick choices |
Plus the common input properties (label, disabled, required, error, help). Event onChange: event.detail is { from, to }, or null when cleared.
<pos-date-range label="Order created" value={range} onChange={(e) => e.detail && setRange(e.detail)} />Feedback
pos-banner
A prominent message inside the extension.
| Property | Type | Default | Description |
|---|---|---|---|
tone |
'info' | 'success' | 'warning' | 'critical' |
'info' |
|
heading |
string |
Title | |
dismissible |
boolean |
false |
Show a close button |
onDismiss event.
pos-spinner
| Property | Type | Default |
|---|---|---|
size |
'small' | 'medium' | 'large' |
'medium' |
pos-progress
A progress bar for rates (on time, target reached).
| Property | Type | Default | Description |
|---|---|---|---|
value |
number |
0 |
Percentage 0–100 |
label |
string |
Label on the left, percentage on the right | |
tone |
'default' | 'info' | 'success' | 'warning' | 'critical' |
'default' |
Bar color |
showValue |
boolean |
true |
Show the percentage |
pos-empty
An empty state like POS pages: a small illustration, a title, a description and action buttons.
| Property | Type | Description |
|---|---|---|
heading |
string |
Title |
description |
string |
Description |
Slot actions for pos-button and pos-link.
<pos-empty heading="No late orders" description="Change the dates to see more">
<pos-button slot="actions" onClick={reset}>Reset filters</pos-button>
</pos-empty>Data and actions
pos-button
| Property | Type | Default | Description |
|---|---|---|---|
variant |
'primary' | 'secondary' | 'tertiary' | 'danger' |
'secondary' |
Button style |
size |
'small' | 'medium' |
'medium' |
|
loading |
boolean |
false |
Shows a busy state and blocks clicks |
disabled |
boolean |
false |
|
icon |
see below | Icon before the text; a button without text is an icon-only button | |
tooltip |
string |
Hover text; required for icon-only buttons (also their name for screen readers) |
onClick event.
Icons (the POS icon set): plus, edit, delete, download, upload, refresh, filter, search, settings, print, copy, link, external, view, send, check, close, more, calendar, info, warning.
<pos-button icon="download" onClick={exportCsv}>Export</pos-button>
<pos-button icon="refresh" tooltip="Reload" onClick={reload} />pos-menu-button
A button that opens a list of actions. Without label it is a "⋯" button.
| Property | Type | Default | Description |
|---|---|---|---|
items |
{ id: string; label: string; danger?: boolean; disabled?: boolean }[] |
[] |
Up to 30 items |
label |
string |
Button text | |
icon |
as pos-button |
more without label |
|
variant |
'primary' | 'secondary' | 'tertiary' |
'secondary' |
|
size |
'small' | 'medium' |
'medium' |
|
disabled |
boolean |
false |
|
tooltip |
string |
Hover text |
Event onSelect: event.detail is the id of the clicked item.
<pos-menu-button slot="actions" items={[{ id: 'csv', label: 'Export CSV' }, { id: 'delete', label: 'Delete', danger: true }]} onSelect={(e) => run(e.detail)} />pos-table
A data table like the POS list tables. rows takes Open API records as they are (nested objects included): each column reads its field by key, which may be a path such as customer.name or partner.extend_code; only the column fields are sent to POS. How cells show (format, badge, link, secondary line) is set on the column.
| Property | Type | Default | Description |
|---|---|---|---|
columns |
Column[] |
Column definitions | |
rows |
object[] |
[] |
Records, up to 500 rows shown at once |
rowKey |
string |
'id' |
Field used as the row key |
loading |
boolean |
false |
|
pagination |
{ page: number; pageSize: number; total: number } | null |
null |
App-side pagination |
emptyText |
string |
Content when there are no rows | |
sort |
{ key: string; order: 'asc' | 'desc' } | null |
null |
Sorted column (the app sorts the data or calls the API again) |
summary |
object | null |
null |
Totals row at the bottom, values by column key, formatted like the column |
selectable |
boolean |
false |
A checkbox at the start of each row |
selected |
(string | number)[] |
[] |
Keys of the selected rows |
rowActions |
{ id: string; label: string; icon?: Icon; danger?: boolean }[] |
An "Actions" column at the end, fixed on the right: up to 2 items show as buttons, more go into a "⋯" button; up to 10 items |
type Column = {
key: string; // field of the row, may be a path: customer.name, items.0.sku
title: string;
align?: 'left' | 'center' | 'right';
width?: number; // px
format?: 'text' | 'number' | 'money' | 'percent' | 'date' | 'datetime' | 'badge' | 'link';
tones?: Record<string, 'default' | 'info' | 'success' | 'warning' | 'critical'>; // badge color by cell value
subtitle?: string; // field shown as a gray secondary line (for example the SKU under the name)
sortable?: boolean;
fixed?: 'left' | 'right'; // keep the column visible when scrolling sideways
ellipsis?: boolean; // cut long text to one line
copyable?: boolean; // copy button on hover (tracking codes, order codes); POS copies and confirms
};percent: the number is a percentage (12.5 → 12.5%).badge: the cell value becomes a colored label usingtones.link: link-styled text that firesonCellClick.- Cells show single values (text, numbers, true/false); a
Datebecomes an ISO time. An object or array field leaves the cell empty with a warning: point the column at a field inside it, for examplecustomer.name.
Events:
onPageChange:event.detailis{ page, pageSize }.onRowClick:event.detailis the original record the app passed inrows(found byrowKey).onSortChange:event.detailis{ key, order }, ornullwhen sorting is cleared.onSelectionChange:event.detailis the array of selected row keys (rows on other pages stay selected).onCellClick:event.detailis{ key, row }when aformat: 'link'cell is clicked;rowis the original record.onRowAction:event.detailis{ action, row }when arowActionsitem is clicked;rowis the original record. When an item does not apply to that row, tell the user withpos.toast.show.
<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-table
columns={[
{ key: 'name', title: 'Product', subtitle: 'sku', sortable: true, fixed: 'left' },
{ key: 'state', title: 'SLA', format: 'badge', tones: { Late: 'critical', 'On time': 'success' } },
{ key: 'code', title: 'Order', format: 'link' },
{ key: 'rate', title: 'Rate', format: 'percent', align: 'right' },
]}
rows={rows}
sort={sort}
summary={{ name: 'Total', rate: 62.5 }}
selectable
selected={selected}
onSortChange={(e) => setSort(e.detail)}
onSelectionChange={(e) => setSelected(e.detail)}
onCellClick={(e) => openOrder(e.detail.row)}
/>pos-modal
A dialog opened from inside an extension (for example from a button in a block).
| Property | Type | Description |
|---|---|---|
open |
boolean |
Open state |
heading |
string |
Title |
width |
'small' | 'medium' | 'large' |
520 (default), 720 or 1000 px; use medium or large for tables and two-column forms |
Slot footer for pos-button, pos-menu-button and pos-link at the bottom of the dialog. 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.
pos-drawer
A panel that slides in from the right, like Settings on the Statistics pages: view a row's details without leaving the list.
| Property | Type | Default | Description |
|---|---|---|---|
open |
boolean |
Open state | |
heading |
string |
Title | |
width |
'small' | 'medium' | 'large' |
'medium' |
400, 560 or 800 px |
Slot footer for pos-button, pos-menu-button and pos-link at the bottom. Event onClose when the user clicks close or outside.
In an iframe page, PosModal and PosDrawer only cover the iframe and POS dims everything around it; for a full-height detail panel use pos.ui.drawer (see Iframe page UI).
Worker UI pages
The elements below build render: "worker" pages and report screens (see Extension points › app.page); they also work in blocks and modals.
pos-page
Page frame. On app.page pages, heading and description show on the POS title row (without heading, the title set with pos.page.setTitle or the extension title is used), the actions slot sits on the right next to the primary button, and content is stacked on the gray background. In blocks and modals, pos-page is a titled block.
| Property | Type | Default | Description |
|---|---|---|---|
heading |
string |
Page title | |
description |
string |
Text below the heading | |
width |
'narrow' | 'default' | 'full' |
'default' |
Content width: 720 px, up to 1,800 px or the full screen |
Slot actions for pos-button, pos-link and pos-menu-button; on app.page pages it comes before the primary button.
pos-tabs
A bar of chips with counts (badge), like the status bar of POS list pages. The app keeps the selected tab and renders that tab's content as children.
| Property | Type | Description |
|---|---|---|
tabs |
{ id: string; label: string; badge?: number; disabled?: boolean }[] |
Up to 20 tabs; badge is a count next to the label |
selected |
string |
id of the selected tab |
The onChange event: event.detail is the selected tab's id. POS switches the tab as soon as it is clicked, without waiting for the app.
pos-filter-bar
A row of filters above a table or chart. Children: pos-text-field, pos-number-field, pos-select, pos-checkbox, pos-date-picker, pos-date-range, pos-time-picker, pos-switch, pos-radio-group, pos-button, pos-menu-button. Inputs are drawn compactly on one row, label becomes the hint when there is no placeholder, and the row wraps when space runs out.
<pos-filter-bar>
<pos-text-field label="Order code" value={search} onChange={(e) => setSearch(e.detail)} />
<pos-select label="Order source" options={sources} value={source} onChange={(e) => setSource(e.detail)} />
<pos-date-picker label="From" value={from} onChange={(e) => setFrom(e.detail)} />
<pos-button onClick={reset}>Reset</pos-button>
</pos-filter-bar>pos-chart
A chart drawn by POS; the app only passes data. Colors follow the POS palette.
| Property | Type | Default | Description |
|---|---|---|---|
type |
'line' | 'bar' | 'area' | 'pie' |
'line' |
Chart type |
data |
object[] |
[] |
One object per point, string or number values; up to 500 points and 21 fields |
xKey |
string |
Field for the horizontal axis (slice names for pie) |
|
series |
{ key: string; label: string; format?: 'number' | 'money' | 'percent'; type?: 'bar' | 'line' }[] |
[] |
Up to 10 series; pie uses the first one. A series type (bar, line charts) combines bars and lines |
selected |
string | number | null |
Selected horizontal-axis value: other bars and slices fade; line and area charts show a marker | |
stacked |
boolean |
false |
Stack bars/areas |
horizontal |
boolean |
false |
Horizontal bars (bar only): good for long labels or many groups; the height grows with the number of groups |
height |
number |
300 |
120–600 px |
loading |
boolean |
false |
|
emptyText |
string |
Text when there is no data |
- Event
onSelect: when the app listens, bars, slices and points are clickable;event.detailis{ x, series }:xis the clickedxKeyvalue,seriesthekeyof the clicked bar (nullforline,area,pie). format: 'percent': values are percentages; when every series is a percentage the value axis shows "%". All series share one value axis, so only combine series of similar size (orders and late orders, not orders and revenue).- Long horizontal-axis labels are shortened to fit, with the full text on hover; when each group gets too narrow, labels are tilted. Drop all-zero groups and merge small ones into "Other" before passing
data.
<pos-chart
type="bar"
xKey="day"
data={[{ day: '01/10', revenue: 12500000, cost: 8000000 }, { day: '02/10', revenue: 9800000, cost: 7100000 }]}
series={[{ key: 'revenue', label: 'Revenue', format: 'money' }, { key: 'cost', label: 'Cost', format: 'money' }]}
/>pos-stat
A metric card for report screens: label, large value, a secondary line and the change from the previous period. Put several cards in a pos-grid. On the page background it is a white card; inside a white block (pos-section, modal, block) it is a light gray tile.
| Property | Type | Default | Description |
|---|---|---|---|
label |
string |
Metric name | |
value |
number | string | null |
Numbers are formatted by format; strings show as is; null shows — |
|
format |
'number' | 'money' | 'percent' |
'number' |
percent: value is a percentage (58.3 → 58.3%) |
currency |
string |
the shop's currency | Code as in pos-money, used with money |
tone |
'default' | 'info' | 'success' | 'warning' | 'critical' |
'default' |
Color of the value |
help |
string |
Secondary line below the value, for example "12 delivered orders" | |
change |
number |
Change in %, shown with an arrow; up is good (green), down is bad (red) | |
changeLabel |
string |
Note next to the change, for example "vs last week" | |
inverse |
boolean |
false |
Flip the colors of change for metrics where lower is better (late orders, costs) |
selected |
boolean |
false |
Highlighted border, for a card that acts as a filter |
loading |
boolean |
false |
Shows a placeholder instead of the value |
Event onClick: when the app listens, the card is clickable (Enter works too), for example clicking "Late" to filter the table below.
<pos-grid columns={4}>
<pos-stat label="On-time rate" value={58.3} format="percent" help="12 delivered orders" change={4.2} changeLabel="vs last week" />
<pos-stat label="Late" value={5} tone="critical" change={12.5} inverse selected={filter === 'late'} onClick={() => setFilter('late')} />
<pos-stat label="Return fees" value={2450000} format="money" />
</pos-grid>