Dashboard Blocks¶
Overview¶
Dashboard pages support a set of block types designed for metrics, charts, status displays, and activity tracking. These blocks connect to your collections via data sources and render aggregated or filtered data.
Metric Card¶
Displays a single KPI value with optional formatting and color thresholds.
| Property | Required | Description |
|---|---|---|
label | Yes | Metric title (e.g., "Total Orders") |
aggregation | Yes | count, sum, average, min, or max |
valueField | For sum/average/min/max | Field to aggregate |
format | No | number (localized, e.g., "1,234"), currency (USD, e.g., "$1,234"), or percentage (e.g., "56.7%") |
trend | No | { enabled: true, comparison: "previous-period" } — shows trend arrow and percentage change |
thresholds | No | Color ranges: { green: [min, max], amber: [min, max], red: [min, max] } |
Stat Group¶
Displays multiple metrics in a responsive grid. Each item has its own data source and aggregation, so you can show metrics from different collections in one block.
| Property | Required | Description |
|---|---|---|
items | Yes | Array of stat items |
Each item has:
| Property | Required | Description |
|---|---|---|
id | Yes | Unique identifier |
label | Yes | Metric title |
dataSource | Yes | Collection or query reference |
aggregation | Yes | count, sum, average, min, or max |
valueField | For sum/average/min/max | Field to aggregate |
format | No | number, currency, or percentage |
The grid layout adjusts automatically based on item count — 2 items get 2 columns, 3 items get 3 columns, and so on up to 6 columns.
Chart¶
Displays data as bar, line, area, or pie charts. Chart configuration is covered in the main Pages overview.
Kanban¶
Displays records as cards grouped into columns by a field value. Useful for status-based workflows (e.g., "To Do", "In Progress", "Done").
| Property | Required | Description |
|---|---|---|
groupByField | Yes | Field to group cards into columns |
columnOrder | No | Explicit column ordering (array of values). If omitted, columns sort alphabetically. |
cardTitleField | Yes | Field displayed as the card title |
cardSubtitleField | No | Secondary text on each card |
cardBadgeField | No | Small badge label on each card |
Records with an empty value for the group field appear in an "Uncategorized" column.
Drag-and-Drop¶
On authenticated pages, users can drag cards between columns. When a card is dropped in a new column, the record is updated with the new field value. The UI updates optimistically and reverts if the update fails.
Kanban boards on public pages are read-only.
Calendar¶
Displays records as events on a calendar. Uses date fields to position events and supports month, week, and day views.
| Property | Required | Description |
|---|---|---|
dateField | Yes | Event start date field |
endDateField | No | Event end date (for multi-day events) |
titleField | Yes | Field displayed as the event title |
colorField | No | Field used to assign colors to events (auto-assigned from an 8-color palette) |
defaultView | No | month (default), week, or day |
eventClickAction | No | Action to execute when an event is clicked |
The calendar header includes previous/next navigation, a "today" button, and a view switcher for month/week/day.
Filter Bar¶
Adds page-level filter controls that apply to all data sources on the page.
| Property | Required | Description |
|---|---|---|
datePresets | No | Array of date range presets: today, 7d, 30d, 90d, custom |
dropdownFilters | No | Array of { field, label } for text-based filters |
Date presets filter on the createdAt system field. Dropdown filters apply to the specified field names. All filters merge into every data source's query before fetching data.
Progress Indicator¶
Displays progress or status in one of three visual modes.
| Property | Required | Description |
|---|---|---|
mode | Yes | bar, ring, or badge |
label | Yes | Display label |
value | No | Static numeric value |
valueField | No | Field to bind value to (for aggregation) |
aggregation | No | count, sum, average, or percentage |
target | No | Denominator for percentage (default: 100) |
thresholds | No | Color ranges: { green: [min, max], amber: [min, max], red: [min, max] } |
Modes¶
Bar — horizontal progress bar with percentage label.
Ring — circular progress indicator with percentage in the center.
Badge — text status indicator that auto-colors based on keywords:
- Green: operational, healthy, up, ok, active, online
- Amber: degraded, warning, slow, partial
- Red: down, critical, error, offline, failed
Activity Feed¶
Displays a chronological timeline of events, sorted newest first.
| Property | Required | Description |
|---|---|---|
titleField | Yes | Main activity title |
descriptionField | No | Secondary text (2-line clamp) |
timestampField | Yes | ISO date field for sorting and display |
maxItems | No | Maximum entries shown (default: 10) |
Timestamps display as relative time: "Just now" (under 1 minute), "5m ago", "2h ago", "3d ago", or a full date for entries older than a week.
Auto-Refresh¶
Dashboard pages can automatically refresh their data on a configurable interval.
Set refreshInterval (in seconds) on the page definition to enable auto-refresh. The minimum enforced interval is 10 seconds. Set to 0 or omit to disable.
When auto-refresh is active:
- Data is re-fetched at the configured interval
- The dashboard header shows an "Updated HH:MM:SS" timestamp
- Refresh pauses automatically when the browser tab is hidden and resumes when it becomes visible