Bar Chart

Tips & examples

A dynamic 2D bar chart visualizing categorical data along X and Y axes, with support for multiple Y-value series (grouped/stacked), custom legend mappings, theme palettes, interactive toolbox features (zoom, image export, data view, magic type switch to line chart), and dynamic filter expressions.

When to use

Visualizing categorical data, discrete value distributions, or multi-metric side-by-side performance comparisons.
Comparing dynamic query metrics across categories (X-axis) against numerical ranges (Y-axis), with support for grouped or stacked bars.

What you need

Requires an active Source Query. Select a valid column property for Label (X coordinate) and one or more numerical columns for Value (Y coordinate). Multiple value mappings generate multi-bar comparisons or stacked views.

Categorical database query datasets containing discrete string labels (X coordinate) and numerical aggregation values (Y coordinate).

Examples

A stacked annual revenue comparison bar chart grouping yearly sales values by product category across a 12x6 dashboard area.
An operations bar chart showing regional delivery volume (X-axis) against target metrics (Y-axis) with custom legend aliases and toolbox utilities enabled.

Avoid

Squeezing bar chart displays into tiny layout boxes (e.g., under 6x6 grid units), allocate at least 6x6 grid units, expanding up to 12x12 for high-density category data.
Mapping X and Y coordinates with mismatched data types (e.g. mapping string properties to Y value ranges), which prevents mathematical rendering of bars.
Attempting to display unconstrained query datasets with hundreds of raw rows, use the Data Display Limit configuration to cap categories cleanly.

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 for X-axis categorical labels.
Default: none
Value Column NamesrequiredList of TextInside `dataSource.columns`: Selects one or more numerical query columns for Y-axis bar heights. Adding multiple values generates side-by-side comparison bars or stacked bars.
Default: []
Hide LabeloptionalYes / no: When true, hides numeric value labels on bars.
Default: false
Is StackedoptionalYes / no: Boolean switch stacking multiple Y-value series vertically on a single bar instead of placing them side-by-side.
Default: false

Legend Setup

PlacementoptionalOne of: top, end, bottom, start, hiddenInside `legend`

Label position relative to the input control.

Choices

top
end
bottom
start
hidden

Default: none

OrientoptionalOne of: vertical, horizontalInside `legend`

Controls the layout alignment direction of legend items.

Choices

vertical
horizontal

Default: none

Sort

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

Data Display Limit

LimitoptionalNumber: Caps the maximum number of category items rendered on the bar chart.
Default: none
X IntervaloptionalNumber or Text: Configures axis label step intervals using ‘auto’ or explicit numbers like 100 to control axis tick marks.
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

Toolbox

ToolboxoptionalKey-value map: Toolbox buttons shown on the chart: save as image, restore, data view, area zoom, and magic type (switch to line).
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: {"valueColumnNames":[],"labelColumnName":""}

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

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

Sizing

Minimum size: 3 × 3 grid cells (width × height).

Translatable labels

title — Header title text displayed prominently above the bar 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.myBarChart.<property>

loading boolean True while data is loading from the server. elements.myBarChart.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.myBarChart.data

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

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

When The record behind the bar 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.myBarChart.selected

Replace myBarChart 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
12
13
{
  "config": {
    "dataSource": {
      "viewName": "contacts",
      "columns": {
        "labelColumnName": "labelColumnName",
        "valueColumnNames": [
          "valueColumnNames"
        ]
      }
    }
  }
}

 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
{
  "config": {
    "dataSource": {
      "viewName": "contacts",
      "columns": {
        "labelColumnName": "labelColumnName",
        "valueColumnNames": [
          "valueColumnNames"
        ]
      }
    },
    "showBackground": false,
    "isStacked": 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
  }
}

Ready-made setups

Multi-Series Comparative Sales Bar Chart ↕

Configures a 12x6 bar chart visualizing regional revenue trends across two distinct year series, complete with custom legend aliases, auto limits, and interactive toolbox tools.

 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": {
    "setup": {
      "sourceQuery": "getRegionalSalesQuery",
      "labelProperty": "region_name",
      "valueProperties": [
        "sales_2025",
        "sales_2026"
      ],
      "showValueLabels": true,
      "isStacked": false
    },
    "legend_labels": {
      "legendLabelAliases": {
        "sales_2025": "Sales 2025",
        "sales_2026": "Sales 2026"
      }
    },
    "legend_setup": {
      "legendPlacement": "Top",
      "legendOrientation": "Horizontal"
    },
    "translation": {
      "title": "Regional Annual Revenue Comparison"
    },
    "data_display_limit": {
      "dataLimit": "20",
      "labelInterval": "auto"
    },
    "toolbox": {
      "enableSaveAsImage": true,
      "enableClearSelection": true,
      "enableDataView": true,
      "enableAreaZooming": true,
      "enableMagicType": true
    },
    "filter": {
      "filterExpression": "{\n  \"combinator\": \"AND\",\n  \"filters\": []\n}"
    }
  }
}