Bar Chart
The Bar Chart component displays data as vertical bars, making it easy to compare values across categories. Use it when you want to show how a numeric value differs across a set of groups, for example the number of active cases per region or total revenue per product category. You can connect it to any Shesha entity or a custom API endpoint, and switch between a simple single-series view and a pivot view that breaks data down by a second grouping dimension.
Properties
The following properties are available to configure the Bar Chart component from the form designer. These are in addition to the common properties shared by all Shesha components.
General
Data Source Type object
Controls where the chart fetches its data.
| Option | When to use |
|---|---|
Entity Type | Pull data directly from a Shesha entity using the built-in API. This is the right choice for most charts. |
URL | Pull data from a custom API endpoint. Use this when your data comes from a non-standard source or a custom backend action. |
Height number
The height of the chart in pixels. The minimum value is 200. Setting a height adjusts the width proportionally for responsiveness. Only visible when Width is not set.
Width number
The width of the chart in pixels. The minimum value is 300. Setting a width adjusts the height proportionally for responsiveness. Only visible when Height is not set.
Show Border boolean
When enabled, a border is drawn around the chart container. Enabled by default.
Chart Settings
Simple / Pivot object
Controls whether the chart displays one data series or multiple.
| Option | When to use |
|---|---|
Simple | Show one bar per category. Use this for straightforward comparisons. |
Pivot | Split each category into multiple bars, one per group. Use this to compare across two dimensions at once. |
Stacked boolean
When enabled, each bar group is rendered as a single stacked bar with coloured segments for each group value, rather than side-by-side bars. Only appears when Simple / Pivot is set to Pivot.
Show Title boolean
When enabled, a title appears above the chart.
Title string
The text displayed as the chart heading. Only appears when Show Title is enabled.
Show Legend boolean
When enabled, a legend appears on the chart that maps each bar colour to a data series. This is most useful in Pivot mode when the chart displays multiple series.
Legend Position object
Controls where the legend appears relative to the chart. Only appears when Show Legend is enabled.
| Option | Description |
|---|---|
Top | Legend appears above the chart. |
Bottom | Legend appears below the chart. |
Left | Legend appears to the left of the chart. |
Right | Legend appears to the right of the chart. |
Show X Axis boolean
Controls whether tick marks and labels are shown on the X-axis. Enabled by default.
Show X Axis Title boolean
When enabled, a title label appears along the X-axis. Only appears when Show X Axis is enabled.
Show Y Axis boolean
Controls whether tick marks and labels are shown on the Y-axis. Enabled by default.
Show Y Axis Title boolean
When enabled, a title label appears along the Y-axis. Only appears when Show Y Axis is enabled.
Stroke Width number
The thickness of the border drawn around each bar, in pixels. Range is 0 to 10. Set to 0 to remove bar borders entirely.
Stroke Color string
The colour of the border drawn around each bar. Use a hex colour code or the colour picker.
Data Settings
The settings available in this section depend on the Data Source Type selected in the General panel.
URL string
The API endpoint Shesha calls to fetch chart data. Appears when Data Source Type is URL.
Axis Label string
A text label identifying the category axis in the chart. Appears when Data Source Type is URL.
Value Axis Label string
A text label identifying the value axis in the chart. Appears when Data Source Type is URL.
Entity Type object
The Shesha entity to pull data from. Appears when Data Source Type is Entity Type. Use the autocomplete to select a known entity, for example Shesha.Domain.Person.
Axis Property object
The entity field whose values appear as categories on the X-axis. Each distinct value in this field becomes one bar group on the chart. Appears when Data Source Type is Entity Type.
Is Axis Property Time Series? boolean
When enabled, Shesha treats the Axis Property as a date or time value and groups bars by the selected Time Series Format.
Time Series Format object
Controls how dates on the axis are grouped. Only appears when Is Axis Property Time Series? is enabled.
| Option | Example |
|---|---|
Day | 01 |
Month | Jan |
Year | 2024 |
Day-Month | 01 Jan |
Day-Month-Year | 01 Jan 2024 |
Month-Year | Jan 2024 |
Value Property object
The entity field whose values are aggregated and plotted on the Y-axis. Appears when Data Source Type is Entity Type.
Legend Property object
The entity field used to split data into separate series in Pivot mode. Each distinct value in this field becomes a separate coloured bar group. Only appears when Simple / Pivot is set to Pivot.
Aggregation Method object
Defines how the Value Property is calculated for each category.
| Option | What it calculates |
|---|---|
Count | The number of records in each category. |
Sum | The total of the Value Property across all records in each category. |
Average | The mean of the Value Property across all records in each category. |
Min | The smallest Value Property value in each category. |
Max | The largest Value Property value in each category. |
Order By object
The entity field used to sort chart data before it is rendered. Select from the property autocomplete.
Order Direction object
The direction to sort the data. Only appears when Order By is set.
| Option | Description |
|---|---|
Ascending | Sort from smallest to largest (A to Z, oldest to newest). |
Descending | Sort from largest to smallest (Z to A, newest to oldest). |
Allow Chart Filter boolean
When enabled, users can filter the chart data directly from the chart interface without editing the form. Disabled by default.
Filter Property List object
The entity fields that users can filter by. Only appears when Allow Chart Filter is enabled. Select one or more properties from the autocomplete.
Entity Filter object
A query builder where you define filter conditions to restrict which records are included in the chart. Use this to scope the chart to a specific subset of data, for example only records where status is Active. Appears when Data Source Type is Entity Type.