Creating Custom Dashboard Elements

When the built-in tile types (metric card, chart, table and so on) do not show your data the way you want, write your own as a library template: a reusable HTML or React element in the element library. Agents can then put it on any dashboard by name and feed it data, and you can bind it to a data source like any other tile.

For background, see Elements and Dashboards.

Step 1: Create the element

1. Go to Platform → Elements and choose Add element above the library.

2. Fill in the identity fields so the platform treats the element as a dashboard template:

   Field	Value
   Element ID	dashboard-lib- followed by a slug, for example dashboard-lib-sla-gauge. Element IDs are unique across the whole platform, so choose something specific to you
   Element Name	A readable name, for example SLA Gauge. Agents can ask for the template by this name
   Type	dashboard
   Subtype	custom
   Technology	html for an HTML template, or react for a React component
   Description	What it shows and what data it needs. Agents read this when choosing a template

3. Write the Template (see below).

4. Check it in the Live Preview: choose the render mode (HTML or React) and enter Sample props (JSON).

5. Add Examples (see Step 2) and any Tags (comma-separated).

6. Choose Create.

An HTML template

The tile's live data is in window.data when the template loads, and window.__ELEMENT__.onUpdate calls you back with { props, data } whenever new data arrives:

<div style="font: 600 2.5rem system-ui; text-align: center" id="value">—</div>
<div style="text-align: center; opacity: 0.7" id="label"></div>
<script>
  function render(state) {
    var d = state.data || {};
    document.getElementById('value').textContent = d.value == null ? '—' : d.value + '%';
    document.getElementById('label').textContent = d.label || 'SLA met';
  }
  render(window.__ELEMENT__.state);
  window.__ELEMENT__.onUpdate(render);
</script>

A React template

Define a component called Element. It receives the tile's static props plus a data prop with the live payload, and re-renders when new data arrives. React is provided; you do not import it.

function Element({ data }) {
  const value = data?.value;
  const ok = value != null && value >= (data?.target ?? 95);
  return (
    <div style={{ textAlign: 'center', padding: 8 }}>
      <div style={{ fontSize: '2.5rem', fontWeight: 600, color: ok ? 'green' : 'crimson' }}>
        {value == null ? '—' : `${value}%`}
      </div>
      <div style={{ opacity: 0.7 }}>{data?.label ?? 'SLA met'}</div>
    </div>
  );
}

Rules every template runs under

• Templates render in a sandboxed frame with no network access: no fetch, no external scripts in HTML mode. Images and fonts may load from https: addresses. Get data through the tile's payload, not by calling an API.
• The tile's height follows what the template renders.
• Errors in your template are caught and shown in the tile rather than breaking the dashboard.
• Links to https: addresses open in a new browser tab.

Step 2: Add an example payload

Give the element at least one example, in this shape, in Examples:

[
  { "data": { "payload": { "value": 97.4, "label": "Tickets inside SLA", "target": 95 } } }
]

The first example's payload documents the data the template expects. When an agent adds a custom tile without naming a template, the platform compares the agent's data fields with each template's example and uses the closest match, so a clear example makes your template easy to pick.

Step 3: Put it on a dashboard

With an agent that has the dashboard functions, name the template:

Add the SLA Gauge template to my Operations dashboard, a third wide, with value 97.4 and the label "Tickets inside SLA".

The agent calls add_dashboard_element with template_id set to sla-gauge (or SLA Gauge); the platform copies your template into a custom tile and passes the data as its live payload. If the name does not match, the error lists the templates that do exist.

Through the API, add a custom tile that carries the template and its payload in data:

POST /dashboards/{dashboard_id}/elements
{
  "element_type": "custom",
  "title": "SLA",
  "size": "third",
  "data": {
    "template": "function Element({ data }) { return <div>{data?.value}%</div>; }",
    "technology": "react",
    "props": {},
    "payload": { "value": 97.4 }
  }
}

Step 4: Feed it live data

Bind the tile to a data source with a mapping that produces the payload fields, for example {"value": "$.rows[0].sla_pct", "label": "Tickets inside SLA"}. For a custom tile, the mapped data is delivered to the template as its payload and the template itself is left alone. See Binding Data Sources to Dashboard Elements.

Updating a template

Editing the element changes the library template. Tiles already on dashboards keep the copy of the code they were created with, so ask the agent to replace those tiles to pick up the new version.

Related

• Elements
• Dashboards
• Building Dashboards