Elements
Elements are the reusable visual components that render inside dashboards. The element library, under Platform → Elements, holds two kinds:
| Kind | What it is | How it is recognised |
|---|---|---|
| Element type definitions | The JSON Schema that the data of one dashboard tile type must satisfy, for example the shape of a metric_card | Type dashboard, subtype is the tile type (metric_card, table, …), template is a JSON Schema |
| Library templates | Renderable HTML or React that a custom dashboard tile draws with, such as a KPI row or a donut chart | Type dashboard, subtype custom, Element ID starting dashboard-lib- |
The platform supplies the built-in type definitions and a set of library templates; they appear in your library alongside your own elements and are read-only to you. You can add your own library templates, and agents will find and use them in the same way as the platform's. See Creating Custom Dashboard Elements.
You can store other elements in the library too, with any type you like. They are kept, versioned and searchable (agents can find them with the platform's element tools), but nothing on the platform renders or applies them automatically.
How agents use library templates
When an agent adds a tile with the add_dashboard_element function, it can name a library template by its slug (the part of the Element ID after dashboard-lib-, such as kpi-stat-row) or by its Element Name. The platform copies the template's code into a custom tile and passes the agent's data to it as the live payload. If the agent supplies data without naming a template, the platform compares the data's fields with each template's first example and picks a template when they match closely.
The agent discovers what is available with list_element_types, which returns every element of type dashboard with its schema or template, examples and tags.
Element fields
| Field | Notes |
|---|---|
| Element ID | Required. A unique identifier across the whole platform, not just your project. A library template's Element ID must start with dashboard-lib- |
| Element Name | Required. Display name, also used to match a template by name |
| Type | Required. Free text; dashboard for anything that renders on a dashboard |
| Subtype | For dashboard elements, the tile type, or custom for a library template |
| Technology | Decides how a template renders: react, jsx or tsx render as React; anything else renders as HTML |
| Description | What the element is for |
| Template | The JSON Schema (for a type definition) or the HTML or React code (for a template) |
| Examples | JSON. For a library template, the first example's data.payload is the sample data agents match against |
| Tags (comma-separated) | For organising and searching |
Elements are organised into folders in the library tree. Use Add folder to create one and drag elements between folders.
The element page
Selecting an element opens four tabs:
| Tab | Shows |
|---|---|
| Overview | A summary of the element and how it is used |
| Definition | Identity (type, subtype, technology, sample props), Findings, a Preview of the template, and its properties: for a type definition, the schema tiles are validated against; for a template, the props it renders with |
| Consumers | The dashboards, and the number of tiles on each, whose tile type matches this element's subtype. For a library template (subtype custom) that is every custom tile, not only those drawn from this template |
| Details | The editable fields, with Delete, Cancel and Update |
When you create an element, a Live Preview renders the template as you type. Choose HTML or React as the render mode, and enter Sample props (JSON) to see it with data.
Findings
The Definition tab flags problems that would otherwise be silent:
| Finding | Why it matters |
|---|---|
| The schema cannot be parsed | Tiles of that type are no longer validated at all |
| The template parses but is not a valid JSON Schema | Validation of tiles of that type is skipped |
| This element has no template | Nothing will be drawn, or nothing validated |
| Inactive, but still drawn on tiles | Deactivating an element does not remove it from dashboards that already use it |
How templates render
Custom tiles and the preview render templates in a sandboxed frame:
- No network access. Templates cannot make network requests. Images and fonts can load from
https:addresses. - HTML mode. Your markup is placed in the page and inline scripts run. The tile's static props and live data are available as
window.propsandwindow.data, andwindow.__ELEMENT__.onUpdate(callback)is called each time new data arrives. - React mode. Define a component named
Element. It is rendered with the tile's props plus adataprop holding the live payload, and re-rendered whenever new data arrives. - Height is measured from what the template renders, so a tile can size itself to its content.
- Actions. A template can ask the dashboard to describe or start a workflow, describe an agent or open a chat with it, or open a run. Starting, opening a chat and opening a run only happen in response to the viewer's own click, and the viewer's permissions apply.
Published element templates
Platform administrators can publish an element as a platform template, either shared (every organisation reads the same copy) or replicated (each organisation gets its own copy). Shared templates appear in your library with an @platform suffix on their Element ID and cannot be edited or deleted from your project.
Through the API
Elements are available under /elements in the platform API (GET /elements/{id}/contract and /consumers return what the Definition and Consumers tabs show), and through the platform tools (list_elements, get_element, search_elements, create_element, update_element, delete_element, get_element_schema).