Widgets

Widgets are visual components that display data as charts or tables on your dashboard. They appear below the Stats section and provide richer data visualization capabilities.

Go to Areas, select an Area, then open the Dashboard tab.

In the Dashboard tab, locate the Dashboard Widgets section
Click Add New Widget
Set the basic settings (Title, Collection, Width)
Select the Widget Type: Chart or Table
Set the type-specific settings
Optionally add Sorting, Where Clause, or Having Clause
Click Done to add the widget

Common settings

These settings apply to both Chart and Table widgets.

Setting	Description
Title	Display name shown in the widget header.
Collection	The collection to query data from.
Widget Width	Layout width: `Full Width (1/1)`, `Half Width (1/2)`, or `One Third (1/3)`.
Description	Optional explanation of what the widget displays.
Widget Type	Toggle between `Chart` and `Table` visualization modes.
Access Visibility	Restrict visibility to specific auth collections and roles.

Access visibility

You can restrict who can see this specific widget (chart or table) on the dashboard. This is useful for showing different data visualizations to different user roles.

Click the Customize Access Control toggle to turn it on.
Select the Auth Collection (for example, Users).
Select the Roles that are allowed to see this widget.

Chart widgets

Chart widgets visualize data graphically. Set the data source, chart type, axis mappings, and display options.

Query settings

Setting	Description
Query Source	`Query Builder` for visual configuration, or `Raw SQL Query` for custom SQL.
Chart Type	The visualization type: `Area`, `Bar`, `Line`, `Pie / Donut`, `Radar`, or `Radial`.
Aggregation	Aggregation function: `Count`, `Sum`, `Average`, `Minimum`, `Maximum`. Only for Query Builder.
Raw SQL Query	Custom SQL query. Available when Query Source is Raw SQL.

Axis configuration

Setting	Description
X-axis field	The field used for the horizontal axis (or category/slice for Pie charts).
X-axis Label	Display label for the X-axis (or center label for Pie charts).
Y-axis Fields	One or more fields for the vertical axis. Each field can have a custom label and color. Not shown when Aggregation is Count.

Y-axis field configuration

When using non-Count aggregations, set each Y-axis field:

Property	Description
Field	The collection field to aggregate.
Label	Display name in the legend and tooltips.
Color	Hex color code for this data series (for example, `#5200ff`).

Display settings

Setting	Description
Variant	Chart style variant. Options vary by chart type (see Variants section below).
Layout	Bar chart orientation: `Horizontal` or `Vertical`. Only for Bar charts.
Legend	`Show` or `Hide` the chart legend.
Tooltip Indicator	Style of the tooltip marker: `Dot`, `Line`, or `Dashed`.
Interactive Target	For Pie Interactive variant: highlight `Minimum Value` or `Maximum Value`.

Chart variants

Each chart type supports different variants:

Chart Type	Available Variants
Area	Default, Stacked, Stacked Expanded, Step, Linear, Dot
Bar	Default, Stacked, Label
Line	Default, Dot, Step, Linear, Label
Pie / Donut	Default, Label, Label List, Stacked, Donut, Donut with Text, Donut Active, Interactive
Radar	Default, Dots, Lines, Grid (Circle), Grid (Filled), Grid (None)
Radial	Default, Label, Grid (Radial lines), Text (Donut), Shape (Gauge), Stacked

Table widgets

Table widgets display data in a tabular format with selectable columns.

Query builder mode

When using Query Builder:

Setting	Description
Query Source	Set to `Query Builder`.
Columns	Select which collection fields appear as table columns. Check the fields you want to display.

Raw SQL mode

When using Raw SQL:

Setting	Description
Query Source	Set to `Raw SQL Query`.
Raw SQL Query	Write a SELECT statement. Columns are auto-detected from the query.

For Raw SQL tables, each detected column can be configured:

Property	Description
Field Name	The column name from the query (read-only).
Label	Display header for the column.
Type	Data type: `String`, `Number`, `Boolean`, `Date`, or `Enum`.
Is Array	Whether the field contains an array of values.
Alias	Column alias if specified in the query (read-only).

Advanced options

These options are available for both Chart and Table widgets when using Query Builder.

Limit and offset

Setting	Description
Limit	Maximum number of records to return. Leave empty for no limit.
Offset	Number of records to skip from the beginning. Leave empty for no offset.

Sorting

Enable custom sorting to control the order of results:

Click the Sorting toggle to enable it.
Click Add Sort Condition.
For each condition, specify:
- Field: The field to sort by
- Order: Ascending or Descending

Multiple sort conditions are applied in order.

Where clause

Filter records before they are processed:

Click the Where Clause toggle to enable it.
Click Add Condition.

Field	Description
Required	Check to make this condition mandatory.
Conjunction	`WHERE` (first condition), `AND`, or `OR`.
Field	The field to filter on.
Operator	`is equal to`, `is not equal to`, `is greater than`, `is less than`, `is greater than or equal to`, `is less than or equal to`, `contains`, `does not contain`, `starts with`, `ends with`, `is in`, `is not in`.
Value	The value to compare against. Supports static Default values, Session Fields , and Dashboard Filters .

Having clause

Filter results after aggregation:

Click the Having Clause toggle to enable it.
Click Add Condition.

Field	Description
Conjunction	`HAVING` (first condition) or `AND`.
Aggregator	The aggregation function (`Count`, `Sum`, `Avg`, `Min`, `Max`).
Field	The field to aggregate.
Operator	Comparison operator (same as Where Clause).
Value	The threshold value. Supports static values, Session Fields , and Dashboard Filters .

note

Where and Having clauses are hidden when using Raw SQL Query source. Include filtering logic directly in your SQL statement instead.

Examples

Order status distribution (pie chart)

Show the breakdown of orders by status:

Title: Order Status Distribution
Collection: Customer Orders
Widget Type: Chart
Chart Type: Pie / Donut
Variant: Donut with Text
X-axis field: status
X-axis Label: Orders
Aggregation: Count

Recent stock movements (table)

Display the latest inventory transactions:

Title: Recent Stock Movements
Collection: Stock Movements
Widget Type: Table
Query Source: Query Builder
Columns: date, item_name, quantity, movement_type
Sorting: date Descending
Limit: 10

Revenue trend (line chart)

Track revenue over time:

Title: Monthly Revenue
Collection: Orders
Widget Type: Chart
Chart Type: Line
Variant: Default
X-axis field: created_at
X-axis Label: Month
Aggregation: Sum
Y-axis Fields:
- Field: total_amount, Label: Revenue, Color: #5200ff
Legend: Show

See these pages for related dashboard configuration:

Dashboard overview — Getting started with dashboards
Stats — KPI card configuration

Creating a widget​

Common settings​

Access visibility​

Chart widgets​

Query settings​

Axis configuration​

Y-axis field configuration​

Display settings​

Chart variants​

Table widgets​

Query builder mode​

Raw SQL mode​

Advanced options​

Limit and offset​

Sorting​

Where clause​

Having clause​

Examples​

Order status distribution (pie chart)​

Recent stock movements (table)​

Revenue trend (line chart)​

Related​

Creating a widget