# Widgets overview

> Source: https://docs.clonepartner.com/reference/widgets/

<!-- sources: src/dashboard/register-widget-types.ts, src/dashboard-parser.ts, ui/src/api/client.ts, references/envoy/dashboards.md -->

# Widgets overview

A widget is one block on a dashboard page: a heading, a number, a chart, a data browser, an editable form, or an action button. Every widget is declared in dashboard YAML with a `type` from the built-in registry (`src/dashboard/register-widget-types.ts`); the parser dispatches each entry to its type-specific handler. Data widgets execute read-only connector calls server-side through the Job's connector mapping — the browser never holds connector credentials.

The 14 registered types match the `DashboardWidgetType` union in the UI API client:

| Type | Purpose |
|---|---|
| [`heading`](/reference/widgets/display/) | Section label or instructional callout. |
| [`stat`](/reference/widgets/display/) | Single numeric result with optional unit and comparison. |
| [`progress`](/reference/widgets/display/) | Current/total ratio bar. |
| [`steps`](/reference/widgets/display/) | Horizontal process stepper. |
| [`people`](/reference/widgets/display/) | Contact cards. |
| [`bar_chart`](/reference/widgets/charts-and-table/) | Bar chart over an array of records. |
| [`line_chart`](/reference/widgets/charts-and-table/) | Line chart over an array of records. |
| [`pie_chart`](/reference/widgets/charts-and-table/) | Pie chart over an array of records. |
| [`table`](/reference/widgets/charts-and-table/) | Bounded rows with declared columns. |
| [`form`](/reference/widgets/inputs-and-actions/) | Typed fields that write a `job_config` object. |
| [`field_mapping`](/reference/widgets/inputs-and-actions/) | Source-to-target mapping editor that writes a `job_config` array. |
| [`action`](/reference/widgets/inputs-and-actions/) | Declarative button that runs a task, job run, or connector method server-side. |
| [`task_progress`](/reference/widgets/inputs-and-actions/) | Latest run status for one job task key. |
| [`explorer`](/reference/widgets/inputs-and-actions/) | Curated pageable, filterable data browser. |

The registry groups behavior three ways: `form` and `field_mapping` are input widgets (they persist a value onto the Job's configuration), `action` is the action widget, and everything else is read-only display.

## Common keys

Every widget accepts these base keys in addition to its type-specific configuration:

| Key | Type | Required | Description |
|---|---|---|---|
| `id` | string | Yes | Stable identity, unique across the whole dashboard. Used for data fetches, refresh targets, and `row_action` references. |
| `type` | string | Yes | One of the 14 registered types. |
| `title` | string | No | Display title. |
| `description` | string | No | Display description. |
| `width` | number | No | Relative span in the responsive grid. |
| `scope` | string or null | No | Named scope profile to inject into this widget's connector calls, or `null` to opt out. Omit to use the dashboard's `default_scope`. |
| `refresh_interval_seconds` | number | No | Per-widget polling interval, overriding the dashboard-level value. |

## Data binding

Data widgets name a connector call in their `data` (or `current`/`total`/`compare_to`) key:

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

- The call shape is `{ connector, method, args? }`. `connector` is a template connector name resolved through the Job's connector mapping; `method` must be a read-only method — writes are rejected at widget execution time.
- Leaf values and whole `data` blocks may be JSONata strings, evaluated with the dashboard context: `arguments`, `job`, `job_config`, and `shared`.
- Widgets that support `shared_query` reuse a named entry from the dashboard's `shared_queries` instead of calling the connector directly; the cached result is bound as `data` in the widget's expressions. Prefer shared queries when several widgets need the same expensive call.

## Public share behavior

On the public share surface each widget is sanitized by its registry handler: connector call configs, option sources, and action dispatch internals are stripped, and only display-safe keys (titles, columns, form field labels, and similar) reach the anonymous viewer. See [Dashboard YAML](/reference/dashboards/) for page-level `public` flags and `allow_public_input`.

## Related

- [Dashboard YAML](/reference/dashboards/) — the document structure widgets live in
- [Display widgets](/reference/widgets/display/) — heading, stat, progress, steps, people
- [Chart and table widgets](/reference/widgets/charts-and-table/) — bar_chart, line_chart, pie_chart, table
- [Input and action widgets](/reference/widgets/inputs-and-actions/) — form, field_mapping, action, task_progress, explorer