Pie Chart

Tips & examples

A dynamic circular pie or donut chart visualizing categorical proportional shares, complete with slice value labels, customizable empty state colors, theme palettes, and interactive toolbox utilities (image export, clear selection, data view table).

When to use

Visualizing proportional distributions, parts-of-a-whole relationships, or percentage share compositions.
Displaying dynamic categorical datasets where each slice’s volume contributes to a total 100% sum.

What you need

Requires an active Source Query. Select a valid column property for Label (defines pie slices) and a numerical column for Value (defines slice volume). Every label field must map to a valid numeric value.

Categorical database query records where each category label maps to a positive numerical value contributing to a whole sum.

Examples

A market share breakdown pie chart displaying product revenue proportions across a 6x6 grid panel.
An operational budget distribution donut chart showing departmental expenditure shares with custom empty state background colors and image export tools enabled.

Avoid

Squeezing pie charts into small layout containers (under 6x6 grid units) — allocate at least 6x6 grid units, expanding up to 12x12 for high-density slice categories.
Attempting to display datasets with a massive number of small slices — use the Data Display Limit configuration to cap categories cleanly.
Using pie charts for multi-series trend comparisons over time — use line_chart or bar_chart instead.

Properties

Editor properties

Configure these in the Application Designer property panel. Group headings mirror the editor where possible. Data Source is where the element gets its rows or field binding (a view/query, a connector operation, or a parent form field). References appear only for view-backed sources and map foreign-key ID columns to readable labels from another view.

Setup

View NamerequiredTextInside `dataSource`: Database view that supplies rows or form data.
Default: none
Label Column NamerequiredTextInside `dataSource.columns`: Selects the query column property used to define individual pie slices.
Default: none
Value Column NamerequiredTextInside `dataSource.columns`: Selects the numerical query column property defining the proportional volume of each slice.
Default: none
Hide LabeloptionalYes / no: When true, hides slice value labels on the pie.
Default: false

Sort

SortoptionalList of Settings group: Configuration for sort.
Default: none

Data Display Limit

LimitoptionalNumber: Caps the maximum number of slice categories rendered on the pie chart.
Default: none
X IntervaloptionalNumber or Text: Configures label step intervals using ‘auto’ or explicit numbers to control label tick frequency.
Example auto
Default: none

Theme

Theme NameoptionalText: Selects predefined visual color palettes or unlocks custom color hex picker settings.
Default: none
ThemeoptionalKey-value map: Custom theme object for background, title, and legend colors when not using a named preset.
Default: none

No Data Styles

ColorrequiredTextInside `noDataStyles`: Fill colour used when the chart has no data to display.
Default: none
Border ColorrequiredTextInside `noDataStyles`: Border colour used when the chart has no data to display.
Default: none

Toolbox

ToolboxoptionalKey-value map: Toolbox buttons shown on the chart: save as image, restore, and data view.
Default: none
Is DonutoptionalYes / no: When true, renders a donut (hollow centre) instead of a filled pie.
Default: none

Filter

FilteroptionalCustom expression: Row filter applied when loading data.
Example { "combinator": "AND", "filters": [] }
Default: defaultExpressionValue

Inside dataSource: (dataSource)

ColumnsrequiredSettings group: Configuration for columns.
Default: {"valueColumnName":"","labelColumnName":""}

Inside `sort.$item`: (Each list item) ↕

AscrequiredYes / no: Configuration for asc.
Default: none
Field NamerequiredText: Configuration for field Name.
Default: none

Inside legend: (legend)

OrientoptionalOne of: vertical, horizontal

Configuration for orient.

Choices

vertical
horizontal

Default: none

PlacementoptionalOne of: top, end, bottom, start, hidden

Label position relative to the input control.

Choices

top
end
bottom
start
hidden

Default: none

Sizing

Default size when dropped on a page: 4 × 4.

Translatable labels

title — Header title text displayed prominently above the pie chart container.

Accessibility

Renders canvas visual graphics with fallback ARIA chart roles (role='img') and accessible text descriptions. Turning on Data View allows screen reader users to consume underlying metric data in tabular format.

Expressions

Values you can read in expressions

Other parts of your app can read live values from this element in custom expressions:

elements.myPieChart.<property>

loading boolean True while data is loading from the server. elements.myPieChart.loading

When True while the chart is fetching. Use it to hold back a summary figure that would otherwise flash the wrong number.

data null Current payload rows or record object. elements.myPieChart.data

error string Error message when the last operation failed. elements.myPieChart.error

selected object Currently selected row(s) in the table. elements.myPieChart.selected

When The record behind the slice the user clicked. This is how you make a chart drive the rest of the page — point a table or detail panel at it to drill down. Empty until something is clicked.

To use one of these, open the property you want to drive on the other element, switch it to expression mode in the Expression Editor, and enter:

1
elements.myPieChart.selected

Replace myPieChart with this element’s unique id. Select the element in Application Designer and copy the id chip at the top of the right-hand property panel.

Composition

Where you can place it

Drag this element into one of these containers:

Sample configuration

Minimal example — required fields only ↕

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "config": {
    "dataSource": {
      "viewName": "contacts",
      "columns": {
        "labelColumnName": "labelColumnName",
        "valueColumnName": "valueColumnName"
      }
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
  "config": {
    "dataSource": {
      "viewName": "contacts",
      "columns": {
        "labelColumnName": "labelColumnName",
        "valueColumnName": "valueColumnName"
      }
    },
    "showBackground": false,
    "filter": "@@expression:'value'",
    "sort": [
      {
        "fieldName": "fieldName",
        "asc": false
      }
    ],
    "limit": 0,
    "xInterval": 0,
    "toolbox": {
      "exampleKey": {
        "exampleKey": {}
      }
    },
    "themeName": "themeName",
    "theme": {
      "exampleKey": {}
    },
    "legend": {
      "placement": "top",
      "orient": "vertical"
    },
    "hideLabel": false,
    "hideLegend": false,
    "isDonut": false,
    "noDataStyles": {
      "color": "color",
      "borderColor": "borderColor"
    }
  }
}

Ready-made setups

Proportional Revenue Share Donut Chart ↕

Configures a 6x6 donut chart displaying departmental revenue proportions with value labels, image export tools, and custom empty state styling.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "config": {
    "setup": {
      "sourceQuery": "getDepartmentRevenueShare",
      "labelProperty": "department_name",
      "valueProperty": "total_revenue",
      "showValueLabels": true
    },
    "translation": {
      "title": "Department Revenue Share"
    },
    "data_display_limit": {
      "dataLimit": "10",
      "labelInterval": "auto"
    },
    "toolbox": {
      "enableSaveAsImage": true,
      "enableClearSelection": true,
      "enableDataView": true,
      "chartMode": "Donut"
    },
    "filter": {
      "filterExpression": "{\n  \"combinator\": \"AND\",\n  \"filters\": []\n}"
    }
  }
}