KPI

A value indicator (progress bar or tile) with color thresholds based on value.

Widget description: kpi

The KPI widget displays the value of a single field as a progress bar (with percentage) or as a tile with a large number. The color can change based on thresholds: for example, green above 80%, orange above 40%, otherwise red. It is ideal for budget utilization, completion progress, or days remaining until a deadline. It is a virtual widget and is not saved to the item.

Adding to the form

1. On the Widgets tab, select Indicator / KPI tile and drag it into a section.
2. In the inspector, choose the Source value field. All fields except widgets are listed.
3. Configure the mode, target value, unit, and optionally color thresholds.

A new widget defaults to a progress bar with a target of 100, title “Completion status”, unit “%”, and 50% width.

Inspector settings

Additional schema properties not shown in the inspector can be set in the raw JSON editor:

Color thresholds

Thresholds are added with the Add color threshold button. Each has an operator (gte ≥, gt >, lte ≤, lt <), a value, and a color. Two buttons insert ready-made presets: Traffic light ↑ (higher = better) and Traffic light ↓ (lower = better). The Clear button removes all thresholds.

Evaluation order:

1. Among thresholds with ≥ or >, the matched threshold with the highest value is chosen.
2. If none of those match, among thresholds with ≤ or <, the matched threshold with the lowest value is chosen.
3. If nothing matches, the default color accent is used.

For a progress bar set to By % completion, thresholds are compared against the percentage (0 to 100). Otherwise, they are compared against the source field value (for tiles, always against the value).

Runtime behavior

• Progress bar: title, percentage in a colored badge, value with unit and target (“12 / 20 pcs”), and bar. Percentages are rounded and clamped to 0–100%.
• Tile: title, large number (colored by thresholds), unit, and subtitle. A colored accent strip appears on the left edge.
• Numbers are formatted according to the form language (thousands separators, decimal separator). Text values that cannot be parsed as numbers are displayed as text and treated as 0 for percentage calculations.
• The widget reacts live to changes in the source field, target field, and any fields referenced in the subtitle. It behaves identically in all modes (New, Edit, View).

Text translations

customLabel, kpiTitle, kpiSubtitle, and kpiUnit can be translated. See Translations and multilingual forms.

Rules and scripts

• setVisible: shows or hides the indicator.
• You control the indicator’s value through its source field. This is often a calculated field or a field populated by setExpression, such as [Spent] / [Budget] * 100.
• Color is determined by thresholds; rules do not set it directly.

Configuration example (JSON)

{
  "internalName": "widget_kpi_budget",
  "customLabel": "Budget utilization",
  "fieldType": "kpi",
  "colSpan": 6,
  "defaultVisible": true,
  "kpiConfig": {
    "mode": "progress",
    "sourceField": "Spent",
    "targetSource": "field",
    "targetField": "Budget",
    "title": "Budget utilization",
    "unit": "USD",
    "subtitle": "Project [Title]",
    "color": "danger",
    "thresholdBy": "percent",
    "thresholds": [
      { "id": "t1", "operator": "lt", "value": 70, "color": "success" },
      { "id": "t2", "operator": "gte", "value": 70, "color": "warning" },
      { "id": "t3", "operator": "gte", "value": 90, "color": "danger" }
    ]
  }
}

Limitations and tips

• The source is always a single field. Compute sums and ratios beforehand in a calculated field.
• Percentages are calculated from the target, so a target of 0 falls back to 100. For “lower is better” metrics, use lt and lte thresholds (Traffic light ↓ preset).
• Tiles do not display the target or percentage, only the value. Choose progress bar if you want to show them.
• An empty field is displayed as 0.