# UI components

> 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](/developers/apps/en/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](/developers/apps/en/runtime-api#worker-environment)):

```js
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 })`](/developers/apps/en/runtime-api#pos-download); open an order in POS with [`pos.navigate({ resource: 'order', id })`](/developers/apps/en/runtime-api#pos-navigate). Complete report and list pages: the `get_example` tool of the [MCP](/developers/apps/en/ai-guide#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](#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 |

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

```ts
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 |

```ts
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](/developers/apps/en/page-ui#modals-and-drawers-over-the-whole-pos)).

## Worker UI pages

The elements below build `render: "worker"` pages and report screens (see [Extension points › app.page](/developers/apps/en/targets#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>
```
