Widget reference

KPI widget: volledige instelling reference

KPI is de single-value widget met aggregation, formatting, icon styling en meerdere comparison-bronnen (filter sets, static, field, view).

Waarde Formattering Comparison Voorbeeld

1. Waarde en aggregatie

KPI widget settings — KPI editor met value, comparison en formatting opties.

Defaults

agg=sum, valueFormat=number, digitsInfo=1.0-1.
Comparison staat standaard aan met comparisonSource=filterSets.
comparisonMode=difference, comparisonValueAgg=sum.

Key	Type	Beschrijving
`valueField`	string	Bronveld voor KPI (verplicht).
`agg`	sum/avg/min/max/count/countDistinct	Aggregatie op `valueField`.
`filter`	object	Widget filter JSON; moet object zijn.
`kpiLabel`	string	Label onder/naast waarde.
`icon`, `iconColor`	string	PrimeIcon class en kleur.

2. Formattering en styling

Instelling	Waarden	Uitleg
`valueFormat`	string/number/decimal/currency/percent/date/datetime/time	Outputformaat van KPI waarde.
`digitsInfo`	string	Numerieke precisie voor number/decimal/currency/percent.
`currencyCode`, `currencyDisplay`	string	Valuta instelling voor currency format.
`dateFormat`	string	Datumweergave bij date/datetime/time format.
`prefix`, `suffix`	string	Tekst voor/na KPI waarde.

3. Comparison settings (alle bronnen)

Key	Beschrijving	Wanneer verplicht
`comparisonEnabled`	Master toggle voor compare badge.	Niet verplicht.
`comparisonSource`	`filterSets`, `static`, `field`, `view`.	Als comparison aan staat.
`comparisonMode`	`difference`, `percent`, `both`.	Optioneel, default difference.
`comparisonStaticValue`	Vaste baseline.	Bij `comparisonSource=static`.
`comparisonValueField`	Veld voor vergelijking.	Bij `field` of `view`.
`comparisonValueAgg`	sum/avg/min/max/count/countDistinct	Bij `field` of `view`.
`comparisonViewUid`	View identifier als baseline bron.	Bij `comparisonSource=view`.
`comparisonDateFilterKey`	Date-range filterkey fallback.	Alleen bij `filterSets`.
`comparisonShowFilters`	Toont actieve filterwaarden in compare tag.	Optioneel.
`comparisonLabelBefore`, `comparisonLabelAfter`	Tekst voor/na delta.	Optioneel.
`comparisonReverseColors`	Wisselt groen/rood logica om.	Optioneel.

Validatiegedrag

Zonder valueField kan de widget niet opgeslagen worden.
Bij comparisonSource=static is een numerieke static value vereist.
Bij comparisonSource=view is comparisonViewUid verplicht.
Bij comparisonSource=field/view valt comparisonValueField terug op valueField als leeg.

4. Voorbeeld KPI options JSON

{
  "valueField": "revenue",
  "agg": "sum",
  "valueFormat": "currency",
  "currencyCode": "EUR",
  "currencyDisplay": "symbol",
  "digitsInfo": "1.0-0",
  "kpiLabel": "Omzet",
  "icon": "pi pi-chart-line",
  "iconColor": "#0ea5e9",
  "comparisonSource": "view",
  "comparisonViewUid": "revenue_previous_period",
  "comparisonValueField": "revenue",
  "comparisonValueAgg": "sum",
  "comparisonMode": "both",
  "comparisonLabelBefore": "vs",
  "comparisonLabelAfter": "vorige periode"
}