# Widgets

## What is a widget?

A widget is one tile on a dashboard. A data widget has two halves. Its pipeline gets the data, and
its configuration draws the data as a chart or table. A dashboard holds up to 100 live widgets, and
removed widgets do not count ([Limits](/docs/reference/limits)).

## Where does a widget's data come from?

From its pipeline, the recipe for its data. Each stage in it is one call to a tool on a connected
data source. The transform is a short piece of code that takes what the stages returned and shapes it
into the rows the chart draws. A widget that combines several calls has one stage for each.

Take a chart of the US unemployment rate by year:

| Part | In this chart |
|---|---|
| Stage | Calls `economy__series_observations` for the series `UNRATE` |
| What comes back | One row per month, such as `{ date: "2024-01-01", UNRATE: 3.7 }` |
| Transform | Averages the months of each year into one row, such as `{ year: 2024, rate: 4.0 }` |
| Configuration | Draws `year` along the bottom and `rate` as a line |

A refresh runs the stages and the transform again. A restyle changes only
the configuration, so recoloring a chart never fetches anything.

## What are the different types of widgets?

| Type | What it shows |
|---|---|
| Chart | Line, bar, area, scatter, pie and the other Apache ECharts types |
| KPI | A single headline number |
| Table | Rows and columns |
| Pivot | Values summarised by row groups and column groups |
| Progress | A value measured against a target |
| Library visualization | A custom chart, such as a marimekko or a circle pack, drawn by code saved in the workspace |
| Markdown | Text, headings and images, with no data behind it |
| File | One uploaded image or PDF, with an optional caption |

The chart type lives in the widget's configuration. Turning a line chart into a bar chart is a
restyle of the same widget.

A library visualization points at an entry on the workspace's
[Widgets](/docs/workspace/theme-and-library) page and never carries the code itself. The code draws
SVG and runs sealed off in a sandbox.

## How do you put an image or PDF on a dashboard?

Attach it to a chat and ask the built-in assistant to put it on the dashboard. There is no add button
for a file, and the assistant only places files attached to the conversation you are in. Your agent
uploads a file with `upload_file` and places it with `add_widget`.

A file widget shows one image or PDF as it is, with a caption of up to 280 characters. A PDF tile
shows the first page, and the expanded widget scrolls through every page. Click the tile to open the
file full size.

A markdown widget can show an uploaded image inline:

```
![Site photo](attachment:FILE_ID)
```

`FILE_ID` is the id `upload_file` returned. Only this workspace's uploads display there, and images
from other websites stay blocked.

A chart built from an uploaded file names it under **Sourced from**. Click the name to open an image
or PDF, or to download a spreadsheet or text file.

When an uploaded file is deleted, the widgets that use it stay in place. A file widget, or an image
in a markdown widget, reads **Source removed**. A chart drawn from a table in the file keeps showing
its last data until that data expires. Its next refresh fails, and the expanded chart reads
**Source file deleted** with who deleted it and when. Editors also get **Fix with assistant**, which
opens the built-in assistant to point the chart at new data. Scheduled refreshes skip the chart until
then.

> [!WARNING]
> Everyone who can view a dashboard can open the files it shows or charts, guests included. On a
> public dashboard that means anyone with the address, and on an embed anyone who can open the page
> around it. Remove the last widget that uses a file and the dashboard stops sharing it.

## How do you add headings, dividers and spacers?

With a markdown widget that drops its card frame. Without the frame it reads as part of the page
rather than as another tile.

| Write this | Get this |
|---|---|
| `## Customers` and a sentence | A section heading |
| `---` | A divider |
| *(nothing)* | A spacer |

The grid closes up empty cells, so a spacer is the only way to leave deliberate whitespace.

Data widgets always keep their frame. It holds the title, the expand button and the
**Discussions** button.

## How do you discuss a widget with your team?

Open **Discussions** in the widget's header. Every framed widget has its own thread there. A dot on the button marks an open thread. `@mention` a colleague in the thread and Vistazo
notifies them.

## How do you change a widget?

Ask. Once a widget is on a dashboard, you edit it in place. There is no properties form and no
Save button, on the canvas or in the expanded widget. Ask the built-in assistant on the dashboard, or
your agent:

> Drop the 2019 bar, label this in millions, and make it a line chart.

The title, description, appearance and data source are all reachable this way.

When an edit brings a new transform, Vistazo runs it before saving
anything. A transform that fails is refused, so the widget keeps working. An edit that supplies rows
directly, or only changes styling, skips that check.