> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexalytica.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Dashboard Widgets: Add and Configure Visualisations
> Add any of 26 chart types to a dashboard, configure data and field mappings, and manage widgets with edit, reload, and change-type actions.
Widgets are the individual visualisation tiles that make up a dashboard. Each widget runs its own query against an attached data source and displays the result as a chart, table, indicator, or other visual form. Data is always live — widgets re-run their queries every time the dashboard loads, so you never have to refresh manually. This page explains how to add, configure, and manage widgets from start to finish.
## Visualisation types
Nexalytica offers **26 visualisation types** organised into families. When you open the widget gallery, types that are not yet applicable to your configuration are shown in grey with a note explaining what they need (for example, a minimum number of data columns).
| Family | What it covers |
| ---------------- | ------------------------------------------------------- |
| **Cartesian** | Bar, line, area, scatter, and other axis-based charts |
| **Distribution** | Histogram, box plot, and similar statistical charts |
| **Hierarchy** | Tree map, sunburst, and other part-of-whole hierarchies |
| **Matrix** | Heatmap and correlation grid |
| **Indicator** | Single-value KPI tiles and gauges |
| **Table** | Data grid and pivot table |
| **Content** | Text blocks, images, and embedded content |
***
## Adding a widget
Adding a widget is a two-step process: first you pick a visualisation type, then you configure it.
Click **Add Widget** in the dashboard editor header. The gallery opens showing all 26 visualisation types. Greyed-out types display a requirement note explaining what data setup they need.
Click the chart type you want to use. This closes the gallery and opens the four-step configuration panel.
Work through the four numbered steps described in the next section. Click **Save** when you are done to place the widget on the dashboard.
***
## Widget configuration
The configuration panel has four numbered steps. Use the **Back** and **Next** buttons to move between them, or click a step number directly.
### Step 1 — Data
Set up the data query that feeds the widget.
| Control | What it does |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title** | Sets the widget heading displayed on the dashboard |
| **Data source** | Choose from the sources currently attached to the dashboard |
| **Advanced mode toggle** | Off = simple column picker; On = manual query editor. Both modes are saved independently so you can switch between them without losing your work. |
Use the column picker to build your query without writing code.
| Option | What it does |
| ----------------- | ----------------------------------------------------- |
| **Table picker** | Select which table to query |
| **Column picker** | Choose which columns to include |
| **Aggregation** | Apply SUM, COUNT, AVG, MIN, MAX, or similar functions |
| **Grouping** | Group results by one or more columns |
| **Joins** | Add joins to bring in related tables |
| **Row limit** | Cap the number of rows returned |
Write your query directly in the editor.
| Option | What it does |
| ---------------- | ---------------------------------------- |
| **Query editor** | Free-text area for your query |
| **Query type** | Choose **SQL**, **Table**, or **Metric** |
Click **Preview** at the bottom of the Data step to run the query immediately (without applying filter values) and inspect sample rows before moving on.
### Step 2 — Visualization
The full gallery appears again so you can confirm or change the chart type. Greyed-out types show what additional data setup they require. Switching type here keeps your data configuration intact.
### Step 3 — Field Mapping
Map the columns returned by your query to the parts of the chosen chart.
The available mapping slots depend on the visualisation type you selected. Common examples:
| Slot | Typical use |
| ------------------ | ------------------------------------------------- |
| **X axis** | Category or time dimension |
| **Value / Y axis** | Numeric measure |
| **Series** | Dimension used to split data into multiple series |
| **Size** | Numeric measure controlling bubble or marker size |
If a required mapping slot is empty, the **Save** button remains disabled and the slot is highlighted in red. Fill all required slots before saving.
### Step 4 — Filters
Connect dashboard-level filters to this widget so that when a viewer adjusts a filter, the widget re-runs its query with the new filter value applied.
* Select one or more dashboard filters from the list.
* Each connected filter maps to a column in the widget's query result.
***
## On-widget actions
Once a widget is on the dashboard, hover over it to reveal the action controls.
| Action | How to access | What it does |
| ------------------------ | --------------------------------- | --------------------------------------------------------------------------------- |
| **Reposition** | Drag the **drag handle** | Moves the widget to a new position on the dashboard grid |
| **Edit** | ⋮ menu → **Edit** | Reopens the full four-step configuration panel |
| **Reload** | ⋮ menu → **Reload** | Re-runs the widget's query immediately |
| **Change Visualization** | ⋮ menu → **Change Visualization** | Swaps the chart type without altering the underlying data query or field mappings |
| **Delete** | ⋮ menu → **Delete** | Removes the widget from the dashboard permanently |
***
## Widget states
Widgets communicate their current status visually so you always know what you are looking at.
A shimmer animation appears while the query is running. You do not need to do anything — the widget updates automatically.
A **No data** message is shown when the query returns zero rows. Adjust your filters or data configuration to broaden the result set.
An error card replaces the visual when the query fails. The card shows an error description and a **Retry** button to re-run the query without reopening the editor.
A greyed-out placeholder appears when the widget's data source has been toggled off by an admin. Re-attach the source to restore the live data view.
***
## Live data
Every widget queries its data source directly — there is no cached or static snapshot. Queries re-run automatically whenever:
* The dashboard is opened or the page is refreshed.
* You click **Reload** on a widget.
* A dashboard filter value changes.
You never need to manually refresh a widget to see current data.
***
## Permissions
* Add new widgets via the widget gallery
* Configure and reconfigure widgets (data, visualisation, field mapping, filters)
* Change a widget's visualisation type
* Reposition widgets on the grid
* Reload widgets
* Edit and delete widgets
* View all widgets with live, up-to-date data
* Reload widgets to force an immediate re-run
* Apply dashboard-level filters (which update widget queries in real time)
* Cannot add, edit, restyle, move, or delete any widget