Configure heading, stat, progress, steps, and people widgets with every key, shared-query expressions, and complete YAML examples.

Display widgets

Read-only widgets that present copy, numbers, and status: heading, stat, progress, steps, and people. Keys shared by every widget (id, title, width, scope, refresh_interval_seconds) are documented on the Widgets overview.

`heading`

Non-data copy between widgets: a compact section label or an instructional panel. No connector call.

Key	Type	Required	Description
`markdown`	string	No	Content; supports `##` headings, paragraphs, lists, and bold.
`variant`	string	No	`section` (default) — compact uppercase label; `callout` — tinted instructional panel. Any other value is rejected.

Set variant explicitly; there is no content-based auto-detection. Use callout for instructions customers should read before interacting (for example above field_mapping editors), and section to divide widget groups.

- id: intro
  type: heading
  variant: callout
  width: 4
  markdown: |
    ## How it works
    Pick a field on the **left** and its match on the **right**, then click **Save mapping**.

`stat`

A single numeric result, from a direct connector call or a shared query.

Key	Type	Required	Description
`data`	object or JSONata string	Yes, unless `shared_query` is set	Read-only call config `{ connector, method, args? }`.
`shared_query`	string	No	Name of a `shared_queries` entry to reuse instead of `data`.
`value_expr`	string	Yes, when `shared_query` is set	JSONata over the shared result (bound as `data`) producing the scalar.
`unit`	string	No	Display suffix.
`compare_to`	object or JSONata string	No	Comparison call config.

When the result is not already a number, the renderer picks count, value, or n from the first row of an array result (or from an object result), and falls back to an array's length.

- id: tickets_total
  type: stat
  title: Tickets
  unit: tickets
  data:
    connector: mongo
    method: count
    args:
      collection: zendesk_tickets

Missing data without a shared_query fails with <path>.data is required for stat; a shared_query without value_expr fails with <path>.value_expr is required when shared_query is set.

`progress`

A current/total ratio bar.

Key	Type	Required	Description
`current`	object or JSONata string	Yes, unless `shared_query` is set	Call config producing the numerator.
`total`	object or JSONata string	Yes, unless `shared_query` is set	Call config producing the denominator.
`shared_query`	string	No	Reuse a `shared_queries` entry instead of two calls.
`current_expr`	string	Yes, when `shared_query` is set	JSONata producing the numerator from the shared result.
`total_expr`	string	Yes, when `shared_query` is set	JSONata producing the denominator from the shared result.

Like stat, non-numeric results resolve through count or value on the first row.

- id: ticket_progress
  type: progress
  title: Ticket migration
  current:
    connector: mongo
    method: count
    args:
      collection: zendesk_tickets
      filter: { status: migrated }
  total:
    connector: mongo
    method: count
    args:
      collection: zendesk_tickets

`steps`

A horizontal process stepper driven by one steps value.

Key	Type	Required	Description
`steps`	array or JSONata string	Yes	Literal array of step items, or an expression returning one.
`shared_query`	string	No	Expose a cached query to the expression as `data`/`result`.

Each step item supports:

Field	Required	Description
`label`	Yes	Display text. Steps with empty labels are ignored.
`subtext`	No	Small helper text.
`current`	No	Marks the active step; steps before it render as completed. When more than one step sets it, the first wins.
`completed`	No	Explicit override. A step may set both `current: true` and `completed: true` to render the final step as done while keeping the active ring.

The expression is evaluated over the dashboard context (arguments, job, job_config, shared) and must return an array:

- id: migration_steps
  type: steps
  title: Migration plan
  width: 4
  steps: |
    (
      $current := job_config.migration_step.stage ? job_config.migration_step.stage : "connect_accounts";
      [
        { "label": "Connect accounts", "current": $current = "connect_accounts" },
        { "label": "Checklist completion", "current": $current = "checklist_completion" },
        { "label": "Sample migration", "current": $current = "sample_migration" }
      ]
    )

Prefer a job template job_config entry as the stage source when Envoy owns the state; use a shared_query to external storage only when another system owns the status.

`people`

Compact contact cards driven by one people value.

Key	Type	Required	Description
`people`	array or JSONata string	Yes	Literal array of person items, or an expression returning one.
`shared_query`	string	No	Expose a cached query to the expression as `data`/`result`.

Each person item supports:

Field	Required	Description
`label`	Yes	Role or label. People with empty labels or names are ignored.
`name`	Yes	Display name.
`email`	No	Rendered as a `mailto:` link.
`phone`	No	Rendered as a `tel:` link.
`placeholder`	No	Short bio, ownership note, or when-to-reach-out instructions.
`icon`	No	Lucide icon name such as `user-round`, `briefcase-business`, `mail`, `phone`, or `life-buoy`.
`gravatar`	No	When `true` and `email` is present, the backend returns a Gravatar URL.
`gravatar_url`	No	Explicit avatar URL; overrides the generated Gravatar URL.

- id: migration_people
  type: people
  title: Migration team
  width: 4
  people: |
    (
      $people := job_config.migration_people;
      [
        {
          "label": "Gorgias IM",
          "name": $people.gorgias_im_name,
          "email": $people.gorgias_im_email,
          "placeholder": "Reach out for Gorgias-side approvals.",
          "icon": "briefcase-business",
          "gravatar": true
        }
      ]
    )

heading passes through with its markdown. stat and progress keep only display keys — connector call configs are stripped. For steps and people, literal arrays pass through, but JSONata expression strings are stripped (they would leak author logic), so expression-driven steppers render empty on the public surface. See Authoring dashboards.

Widgets overview — shared keys and data binding
Chart and table widgets — the other read-only group
Dashboard YAML — shared_queries and scope profiles