Percentage KPI
A Percentage KPI is a widget that displays a key metric as a percentage, emphasizing critical performance indicators.
The value’s starting point is at the top, similar to a clock face.
The Percentage KPI can:
- Display both positive and negative values
- Display values exceeding 100% (if the value doesn’t fit within the circular scale, an ellipsis appears)
In Browse mode, click-based filtering and hover tooltips are not available for the Percentage KPI.
Widget Settings
In addition to the common settings, this widget has unique configuration options.
Data Settings
The widget supports the general data settings.
Additionally, the following settings are available for each measure:
- Font size
- Font weight
- Title (toggle to show/hide the measure name)
- Position (display the measure name above or below the indicator)
- Title size
- Color:
- Auto
- Solid
- Gradient (if the value exceeds 100%, the indicator bar uses the final gradient color; the number of gradient classes does not affect this behavior)
- By rule (supports rules in Solid, By measure, and Custom modes)
- Custom
- Display (display condition)
You can add an unlimited number of measures, but only one is displayed—the first in the list or the first that satisfies a display condition.
By default, the widget uses Percentage format, where the measure value is automatically multiplied by 100. The Number format is also available.
Display Settings
Standard display settings apply. Additionally, you can align the indicator to the left, center, or right.
If any column in the same row has a height greater than the Percentage KPI, the widget’s height expands to match the tallest column. If all other columns are shorter, the widget retains its original height.
Filtering Settings
The widget supports general filtering settings, except for filter mode selection.
Widget Configuration in YAML
You can edit the widget not only in the visual editor but also in the YAML editor. The table below lists the keys and values available for configuration. For details on working with the value key, see Dimension and measure values in YAML. Supported data formats are described on the relevant page. General widget parameters are covered in Widget configuration in YAML.
Data Settings in YAML
| Key | Type | Definition |
|---|---|---|
| title | string | Title |
| showMarkdown | boolean | Description |
| markdownText | string | Description text |
| markdownMeasures | — | Measures in description |
| measures | — | Measures |
| key | string | Widget key |
Measures in YAML (key: measures)
| Key | Type | Definition |
|---|---|---|
| name | string | Measure name |
| value | — | Measure formula |
| dbDataType | enum | Formula data type |
| format | enum | Format |
| formatting | enum | Formatting |
| showTitle | boolean | Show measure title |
| position | enum | Measure title position: - TOP — above- BOTTOM — below |
| fontSize | number | Font size To enable automatic sizing, set to null |
| fontWeight | enum | Measure font weight: - NORMAL — normal- BOLD — bold |
| color | — | Color Modes: - DISABLED — disabled- AUTO — auto- GRADIENT — gradient- FORMULA — by formula- RULE — by rule |
| displayCondition | — | Display condition |
Display Settings in YAML
| Key | Type | Definition |
|---|---|---|
| paddings | string | Side paddings |
| width | number | Width |
| height | number | Height |
| titleSize | number | Title size |
| titleColor | — | Title color: - AUTO — auto- BASE — solid |
| titleWeight | enum | Font weight: - NORMAL — normal- BOLD — bold |
| alignment | enum | Alignment: - LEFT — left- CENTER — center- RIGHT — right |
| markdownTextSize | number | Markdown description text size Available only if Description is enabled |
Filtering Settings in YAML
| Key | Type | Definition |
|---|---|---|
| ignoreFilters | boolean | Ignore filters |
| filters | — | Filters |
| stateName | string | State |
Example of a Configured Widget in the YAML Editor
widgets:
- key: percentage-kpi
apiVersion: "16"
type: PERCENTAGE_KPI
settings:
appearance:
enabled: false
titleSize: 14
titleColor:
mode: AUTO
titleWeight: NORMAL
ignoreFilters: false
stateName: null
title: ""
showMarkdown: false
markdownMeasures: []
markdownText: ""
filters: []
alignment: CENTER
measures:
- name: Quantity
value:
mode: FORMULA
formula: count()
dbDataType: UInt64
format: NUMBER
formatting: AUTO
showTitle: true
position: BOTTOM
fontWeight: BOLD
titleSize: 14
color:
mode: AUTO
displayCondition:
mode: DISABLED
Was the article helpful?