---
title: Charts, tables and KPI components
description: The data components an agent fills with numbers instead of drawing anything, the one data contract they share, the shapes Venom also reads, and how to place them in a page, a deck slide or an html page.
section: studio
order: 25
audience: [user, builder, agent]
sources: [services/nodejs-cloud/lib/studio/blocks.ts, services/nodejs-cloud/lib/studio/charts.ts, services/nodejs-cloud/lib/studio/normalize.ts, services/nodejs-cloud/lib/studio/html-kit.ts, services/nodejs-cloud/lib/studio/gallery.ts, services/nodejs-cloud/app/(studio)/studio/gallery/route.ts]
features: []
---

Studio's components are data. An agent sends the numbers and Venom draws the chart: an SVG in the artifact's theme, readable in
light and dark, with a layout of its own on a phone, a table of every value for screen readers, and the same picture in print
and in PowerPoint. Nobody writes SVG, chart code or CSS for them.

To see every component drawn in your organisation's theme, open **`/studio/gallery`** while signed in (add `?scheme=dark` or
`?scheme=light`). Each one is shown with the JSON that drew it, which is the example an agent gets from `studio_catalog_get`.

## The components

| Type | What it shows | Its own fields (besides the shared ones below) |
|---|---|---|
| `bar` | bars, vertical or horizontal, grouped or stacked | `data`, `series`, `stacked`, `horizontal` |
| `line` | one line per series | `data`, `series` |
| `area` | filled lines, optionally stacked | `data`, `series`, `stacked` |
| `combo` | bars plus lines, optionally on a second axis | `data`, `series`, `lines`, `y2`, `y2format` |
| `waterfall` | how steps add up from a starting level: gains green, losses red, the start and totals in the accent | `data`, `total` |
| `pie`, `donut` | shares of a whole (the donut prints the total) | `data` |
| `scatter` | points on two number axes, coloured by group | `data`, `series` |
| `histogram` | how values are distributed | `data` (raw values or binned rows), `bins` |
| `heatmap` | a grid shaded by value; two hues when values cross zero | `data`, `columns` |
| `funnel` | stages that narrow, with the conversion between them | `data` |
| `gauge` | one reading on a scale, with a target mark | `value`, `min`, `max`, `target` |
| `progress` | bars toward a goal | `data` (`[label, value, max?]`), `max` |
| `sparkline` | a small trend with its last value | `data`, `area`, `good` |
| `stats` | KPI tiles: a big number, its change and a note | `items`, `good` |
| `table` | a data table | `columns`, `rows`, `formats`, `align`, `totals`, `highlight`, `zebra` |
| `comparison` | options across, features down: yes, no, partial or text | `columns`, `rows`, `highlight` |
| `timeline`, `callout`, `quote` | milestones, a highlighted note, a pull quote | see [Blocks and charts](/docs/studio/blocks.md) |

## One data contract

- **Rows.** Category charts take rows: a label, then one number per series: `[["Q1", 120, 150], ["Q2", 135, 170]]`, with the
  series named in `series`. `null` leaves a gap.
- **Formats.** `format` is one of `num`, `compact`, `pct`, `usd`, `eur`, `gbp`, `int`, `dec1`, `dec2`, for the values and the axis.
  A table takes `formats`, one per column, and shows numbers in full (`$1,200,000`, not `$1.2M`).
- **Axes.** `xTitle` and `yTitle`; `labels` prints each value on its mark; `legend` shows or hides the legend.
- **Where the numbers come from.** Every chart, table, comparison and set of tiles takes `source` (a name, or a markdown link),
  `asOf` (the date of the figures), `unit`, `note` and `unverified`. They print in one line under the component. `unverified: true`
  adds an **Unverified** badge and `"estimate"` an **Estimate** badge: use them for any figure that does not come from a checked
  source.

```json
{"type":"bar","title":"Revenue by quarter","series":["2025","2026"],"format":"usd",
 "data":[["Q1",120,150],["Q2",135,170],["Q3",160,190]],
 "source":"Finance ledger","asOf":"2026-09-30","unit":"USD thousands"}
```

### Tables

A table's numbers align right and text left unless `align` says otherwise. `totals: true` (or a label such as `"Total 2026"`)
adds a row that sums each numeric column; a percentage column is left blank, because shares and rates do not add up.
`highlight` takes row numbers (0 is the first) or the text of a row's first cell. `zebra` shades every other row. A table holds up
to 12 columns and 300 rows; printed, it breaks across pages with its header repeated on each one.

### Comparison

```json
{"type":"comparison","columns":["Venom","Vendor A"],"highlight":"Venom",
 "rows":[["Self-hosted",true,false],["SSO",true,"partial"],["Price per seat","$12","$20"]]}
```

`true`, `false` and `"partial"` are drawn as a tick, a cross and a half circle, with the words for screen readers. `highlight`
marks the recommended option; it is stored as the column's number, so renaming the option keeps it.

## Shapes Venom also reads

Models on every gear guess. Venom rewrites the guesses that have one plain meaning into the form above before it checks a block,
and stores the rewritten form:

- rows of objects: `[{"quarter":"Q1","revenue":10,"cost":8}]` (the series are named after the keys);
- Chart.js: `{"labels":["Jan","Feb"],"datasets":[{"label":"Web","data":[3,5]}]}`;
- `labels` or `categories` beside a list of numbers, or `series` as `[{"name","data"}]`;
- an object of label to value: `{"EU":60,"US":40}`;
- numbers as text: `"1,234"`, `"$4.2M"`, `"12%"`, `"(45)"`;
- type names such as `bar_chart`, `kpi`, `doughnut`, `horizontal_bar`, or `{"type":"chart","chartType":"pie"}`;
- field names such as `as_of`, `sources`, `x_label`, `number_format: "percent"`, `"true"` for `true`;
- a block wrapped in another key: `{"type":"chart","chart":{"type":"line",...}}` (a slide's chart slot copied into a page) or `{"type":"table","table":{...}}`;
- a comparison whose `columns` start with a header for the feature column, and a list of lines where one text goes;
- a waterfall total written as `["Q3", null, 4800000]` or with `"subtotal"`, and `legend` given as the series' names.

Anything else is refused with the path of what is wrong, what was expected, and a working example of that component, so the next
attempt is right.

## Placing them

- **Page:** a block in the page's `blocks`.
- **Deck:** the `chart` slot of the `chart` layout, the `table` slot of the `table` layout, or a `two_column` side.
- **html page:** a script with the block as JSON, where the component goes:

```html
<script type="application/venom+json">
{"type":"line","title":"Weekly users","data":[["W1",1200],["W2",1350],["W3",1500]],"source":"Product analytics"}
</script>
```

The script may hold one block, a list, or `{"blocks":[...]}`. When the page is served, Venom checks it like a page's block and
draws it in place in the org theme; no script runs and nothing is fetched. A block that does not check is reported when the page
is saved (the tool's answer names the path and the fix) and drawn as a visible error.

## PowerPoint

Charts, including the histogram, heatmap, gauge and progress bars, export as grouped native shapes and text you can restyle.
Tables and comparisons export as native PowerPoint tables (a comparison writes "✓ Yes", "✗ No" and "◐ Partial"); the source line
goes under each one. None of them are PowerPoint chart objects with a datasheet.

## For agents

`studio_catalog_get` with group `components` lists every component with its fields and one example, and says the shared fields
once. `studio_component_get` gives one component's full JSON Schema.
