Reference

UI components

The pos-* elements available to Worker UI extensions: properties, events and rules.

View Markdown

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, 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.
TSX
<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):

JavaScript
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.page pages: pos-page is the POS page frame. heading and description go on the title row at the top, the actions slot sits on the right next to the primary button (pos.page.setPrimaryAction); content is stacked on the gray background.
  • Blocks: a pos-section directly in pos-page is a white card; a pos-section inside another pos-section is a flat group; in blocks and modals, pos-section is a white card with a thin border. pos-table and pos-chart placed directly in pos-page get a white card automatically.
  • Numbers: pos-stat in a 3–5 column pos-grid; do not combine pos-section and pos-heading into metric cards.
  • Filters: put filter inputs in one pos-filter-bar at the top of the page or of a section; use pos-date-range for periods. For status filters use pos-tabs with badge: 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 a pos-menu-button. Per-row actions (Edit, Skip) go in the table's rowActions column, not in a form below the table. Show statuses in tables with a format: 'badge' column; open a row's details in a pos-drawer or pos-modal with pos-description-list and pos-timeline.
  • Settings: one pos-switch row (applies at once) or pos-radio-group per option, grouped in pos-section; times use pos-time-picker.
  • Do not repeat the page title in the content, use emoji or decorative characters in labels (use the tone of pos-stat and pos-badge), nest pos-section more than two levels deep, or wrap every element in its own pos-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

TSX
<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

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

TSX
<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
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
TypeScript
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
};
TSX
<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.

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

TSX
<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
TSX
<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 and onChange is not sent.
TSX
<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.

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

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

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

TSX
<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
TypeScript
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 using tones. link: link-styled text that fires onCellClick.
  • Cells show single values (text, numbers, true/false); a Date becomes an ISO time. An object or array field leaves the cell empty with a warning: point the column at a field inside it, for example customer.name.

Events:

  • onPageChange: event.detail is { page, pageSize }.
  • onRowClick: event.detail is the original record the app passed in rows (found by rowKey).
  • onSortChange: event.detail is { key, order }, or null when sorting is cleared.
  • onSelectionChange: event.detail is the array of selected row keys (rows on other pages stay selected).
  • onCellClick: event.detail is { key, row } when a format: 'link' cell is clicked; row is the original record.
  • onRowAction: event.detail is { action, row } when a rowActions item is clicked; row is the original record. When an item does not apply to that row, tell the user with pos.toast.show.
TSX
<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)}
/>
TSX
<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.

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

TSX
<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.detail is { x, series }: x is the clicked xKey value, series the key of the clicked bar (null for line, 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.
TSX
<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.

TSX
<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>