Skip to content

KPI Board Example

A simple board showing multiple key performance indicators (KPIs).

Complete Board

title: "Executive KPIs"

queries:
  totals:
    metrics: [total_revenue, order_count, avg_order_value, customer_count]
  trends:
    metrics: [total_revenue]
    dimensions: [month]

rows:
  - grid:
      columns: 24
      items:
        - item: revenue_kpi
          width: 6
        - item: orders_kpi
          width: 6
        - item: aov_kpi
          width: 6
        - item: customers_kpi
          width: 6

    charts:
      revenue_kpi:
        label: "Total Revenue"
        query: queries.totals
        type: kpi
        value: total_revenue

      orders_kpi:
        label: "Total Orders"
        query: queries.totals
        type: kpi
        value: order_count

      aov_kpi:
        label: "Avg Order Value"
        query: queries.totals
        type: kpi
        value: avg_order_value

      customers_kpi:
        label: "Customers"
        query: queries.totals
        type: kpi
        value: customer_count

Key Concepts Demonstrated

KPI Chart Type

The kpi chart type displays a single metric as a large number:

revenue_kpi:
  label: "Total Revenue"
  query: queries.totals
  type: kpi
  value: total_revenue
  • type: kpi: KPI chart type (Dataface-specific)
  • value: total_revenue: KPI value — column reference (string column name, required for KPI type)

Grid Layout

Using a grid layout to arrange multiple KPIs:

grid:
  columns: 24
  items:
    - item: revenue_kpi
      width: 6
    - item: orders_kpi
      width: 6
    - item: aov_kpi
      width: 6
    - item: customers_kpi
      width: 6
  • columns: 24: 24-column grid system
  • items: List of items to place
  • width: 6: Each chart takes 6 columns (4 charts × 6 columns = 24 columns total)

Multiple Metrics in One Query

A single query can return multiple metrics:

queries:
  totals:
    metrics: [total_revenue, order_count, avg_order_value, customer_count]

Each KPI chart references the same query but displays a different metric.

Layout Variants

KPI charts ship in three layouts, selected via variant::

  • variant: stacked (default) — value, label, and support on three lines. The fixed slot widths keep multi-KPI rows aligned.
  • variant: inline — value, label, and support all on one row, baseline-aligned. Good for tight summary strips.
  • variant: compact — 2-column. Big value on the left; up to two stacked lines on the right, with the bottom right line sharing baseline with the value.
revenue_kpi:
  label: "Total Revenue"
  query: queries.totals
  type: kpi
  variant: inline
  value: total_revenue
  support:
    value: revenue_delta_pct
    label: vs last month
    format: percent_delta
    glyph: ▲
    tone: positive

label: and support: are each independently optional in all three variants. In compact, a support: block authored without a label: splits across both right-column lines automatically (glyph + value on top, support label on the baseline).

variant: inline and variant: compact assume the card is wide enough to fit the value alongside its label and support. Long labels or narrow grid widths can push text past the card's right edge. The stacked default wraps its label automatically; if you're authoring KPIs at narrow widths, prefer stacked.

Variations and Extensions

Add Markdown Content

Add context above the KPIs:

rows:
  - title: "Executive Summary"
    text: |
      # Key Performance Indicators

      Real-time view of business performance.
    grid: ...
    # ... charts

Add Trend Charts

Combine KPIs with trend charts:

rows:
  - title: "Overview"
    grid:
      columns: 24
      items:
        - item: revenue_kpi
          width: 6
        # ... other KPIs
        - item: revenue_trend
          width: 24

    charts:
      revenue_kpi:
        # ... KPI definition
      revenue_trend:
        query: queries.trends
        type: line
        x: month
        y: total_revenue

Add Filters

Add variables to filter the KPIs:

variables:
  date_range:
    input: daterange
    default: "2024-01-01"

queries:
  totals:
    metrics: [total_revenue, order_count]
    filters:
      order_date: "{{ date_range }}"