> ## Documentation Index
> Fetch the complete documentation index at: https://docs-slidekit.theduomi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Chart Blocks
> Author bar and column chart slides with categories, series, axes, legends, labels, and data rows.
# Chart Blocks
Use a chart block when the template slide contains a bar or column chart region and your request needs to provide chart data. The template supplies placement and default styling. The payload supplies categories, series, chart type, and optional formatting overrides.
## Basic Shape
Inside `slide_data.content.blocks`, a chart block looks like this:
```json theme={"dark"}
{
"type": "chart",
"chart": {
"chart_type": "stacked_column",
"categories": ["Q2", "Q3", "Q4"],
"series": [
{ "name": "Committed", "values": [18.2, 21.4, 24.1] },
{ "name": "Upside", "values": [4.5, 3.9, 5.2] }
]
}
}
```
Each series must have one value per category.
## Supported Chart Types
Chart blocks support bar and column charts only.
| Type | Use when |
| ------------------------ | ----------------------------------------------------------- |
| `clustered_column` | Compare series side by side with vertical columns |
| `stacked_column` | Show stacked contribution by category with vertical columns |
| `percent_stacked_column` | Show each category as 100% with vertical columns |
| `clustered_bar` | Compare series side by side with horizontal bars |
| `stacked_bar` | Show stacked contribution by category with horizontal bars |
| `percent_stacked_bar` | Show each category as 100% with horizontal bars |
If you omit `chart_type`, generation preserves the template chart type where supported.
Pie, line, area, scatter, combo, and other arbitrary PowerPoint chart types are not part of the supported chart block API.
## Categories and Series
`categories` defines the labels along the category axis. For column charts, categories appear on the X-axis. For bar charts, categories appear on the Y-axis.
`series` defines the plotted values. Each series has a `name`, a `values` array, and an optional `color`.
```json theme={"dark"}
{
"categories": ["Q2", "Q3", "Q4"],
"series": [
{ "name": "Committed", "values": [18.2, 21.4, 24.1], "color": "#0F766E" },
{ "name": "Upside", "values": [4.5, 3.9, 5.2], "color": "#2563EB" },
{ "name": "At risk", "values": [2.1, 3.4, 2.8], "color": "#DC2626" }
]
}
```
If a series color is omitted, the renderer uses the template or default chart colors.
## Titles, Legends, and Axes
Chart blocks can specify the chart title, legend, value axis, and category axis.
```json theme={"dark"}
{
"title": "Renewal Outlook by Cohort",
"title_format": {
"font_size": 14,
"bold": true,
"color": "#111827"
},
"legend": {
"show": true,
"position": "bottom",
"text_format": { "font_size": 8 }
},
"value_axis": {
"title": "ARR",
"number_format": "#,##0",
"label_format": { "font_size": 8 }
},
"value_axis_unit": "$M",
"category_axis": {
"label_rotation": -45,
"label_format": { "font_size": 8 }
}
}
```
Legend positions are `bottom`, `left`, `right`, `top`, and `top_right`.
Axis fields include `visible`, `title`, `title_format`, `label_format`, `label_rotation`, `number_format`, `min_value`, and `max_value`.
## Bar Labels
Set `show_bar_labels: true` to add total labels to stacked bars or columns.
```json theme={"dark"}
{
"chart_type": "stacked_column",
"show_bar_labels": true
}
```
This is most useful for `stacked_column`, `stacked_bar`, `percent_stacked_column`, and `percent_stacked_bar`.
Bar labels are calculated automatically from the chart `series` values.
## Data Rows
Use `data_rows` to add a small data table beneath the chart. These values are part of the input payload; the API positions and formats the rows, but it does not derive values like `n=` or `NPS` from the chart series.
```json theme={"dark"}
{
"data_rows": [
["Total ARR", "$24.8M", "$28.7M", "$32.1M"],
["At-risk %", "8%", "12%", "9%"]
],
"data_table_header_column": true,
"data_table_format": {
"font_name": "Arial",
"font_size": 8,
"color": "#333333"
}
}
```
Providing `data_rows` automatically enables the chart data table. If `data_table_header_column` is `true`, the first value in each row is treated as a row label.
## Complete Example
```json theme={"dark"}
{
"title": "Customer NPS Scores by Company",
"footnote": "Source: Q4 2024 Customer Satisfaction Survey",
"content": {
"blocks": [
{
"type": "chart",
"chart": {
"chart_type": "percent_stacked_column",
"categories": [
"Acme Corp",
"TechFlow Inc",
"DataSync Ltd",
"CloudFirst",
"Innovate Labs",
"SecureNet",
"GrowthMetrics",
"Nexus Digital"
],
"series": [
{
"name": "Promoters (9-10)",
"values": [
45,
38,
12,
28,
52,
31,
8,
42
]
},
{
"name": "Passives (7-8)",
"values": [
32,
35,
25,
38,
28,
42,
22,
33
]
},
{
"name": "Detractors (0-6)",
"values": [
23,
27,
63,
34,
20,
27,
70,
25
]
}
],
"legend": {
"position": "top"
},
"show_bar_labels": true,
"data_rows": [
[
"n=",
"156",
"142",
"89",
"178",
"201",
"134",
"67",
"188"
],
[
"NPS",
"+22",
"+11",
"-51",
"-6",
"+32",
"+4",
"-62",
"+17"
]
],
"data_table_header_column": true,
"data_table_format": {
"font_name": "Arial",
"color": "#000000",
"bold": false,
"italic": false,
"underline": false
}
}
},
{
"type": "text",
"text": {
"text": "Question: What is driving the significant detractor rates at DataSync Ltd and GrowthMetrics?"
}
}
]
}
}
```
The visual example below is generated from the complete payload above. It shows the API-added total labels above each stacked column and the aligned data rows beneath the chart.
## Updating Charts Later
Use chart blocks when you are generating a supported bar or column chart slide from a template. Use [Chart Updates](/guides/chart-updates) when a `.pptx` already exists and you only need to refresh the chart data.
Chart updates are useful when:
* New data arrives after the deck was generated
* A user manually edited the deck in PowerPoint and you want to preserve those edits
* You want to keep chart formatting, colors, legends, axes, bar labels, and data-row positioning while replacing the underlying numbers
For updates, send data fields such as `categories`, `series`, `data_rows`, and `data_table_header_column`. Omit styling fields such as `chart_type`, `title`, `legend`, and axes when you want the existing chart formatting preserved.
## Related Guides
Generate one slide or a full deck.
Author table rows and formatting.
Author slide text and text sections.