data_visualization block puts a chart in a Slack message. Slack draws the chart. LithoBlocks builds the structure Slack draws from, either from a chart you write out yourself or from an array in your data, and keeps it inside Slack’s limits so the message sends.
Prerequisites
- Understanding of Blocks
- Familiarity with Placeholders
- Sample data with an array of objects, for dynamic charts
What Slack draws
Four chart types:bar, line, area and pie. Bar, line and area charts have one or more series plotted over a shared set of categories on the x-axis. A pie chart has segments. Colours, the legend, number formatting and axis ranges are Slack’s; there is nothing to configure for them.
Charts appear in messages only. Slack does not draw them in modals, and the modal builder does not offer the block.
Two modes
Static. You write the chart in Slack’s own shape underchart. Strings may carry placeholders. This suits a fixed comparison, or a chart imported from existing Slack JSON.
arrayPath at an array in your data and name the fields to read. The engine builds series, data and categories (or segments for a pie) when the message compiles. This is the mode to use when a system sends you rows.
chart_type defaults to bar. The builder keys (arrayPath, label_key, series[].value_key, axis, overflow and the rest) never reach Slack; the export replaces them with chart.
The three array shapes
All three read onearrayPath. Which fields you name tells the engine which shape the array has.
One series, one row per category
label_key names the field that becomes the x-axis label; each series[] entry names a field to read the value from. The example above is this shape: { day, messages } becomes one series called Messages.
Several series, one row per category
Giveseries one entry per numeric field. Each row supplies one point to every series.
name, its value_key is used as the name.
Long format, one row per series and category
Some systems send one row per combination: a platform and a day, a region and a month. Name the field that identifies the series withseries_key and the numeric field with value_key. The engine groups the rows into one series per distinct value of series_key, in the order it first sees them.
Pie charts
A pie is the first shape withchart_type: "pie". label_key names the segment and value_key its size. Slack requires every segment to be positive, so a segment whose value is zero or negative is dropped and reported as a warning. The Trial tier below does not appear in the chart.
axis is ignored. A pie with no positive segment at all is a compile error rather than an empty chart.
Templates instead of keys
label_key, value_key and series[].value_key read a field as it is. When the label or value has to be assembled, use label_template, value_template or series[].value_template with {{this.field}}, the same escape hatch valueTemplate gives table columns. A template wins over a key when both are present.
Axis and category order
axis takes three optional keys for bar, line and area charts:
x_labelandy_labelname the axes (up to 50 characters each).categoriesfixes the x-axis order. Without it, categories are the distinct labels in the order they first appear in the array.
categories is given.
What the engine normalises, and what it tells you
Slack’s rules leave no room for partial data, so the engine repairs the chart and reports what it did. Both modes go through the same steps. The report comes back aswarnings on compile, send and validate responses over the API and MCP, and the builder’s preview shows it beside the chart.
Truncation keeps the chart sending rather than refusing it, because a digest over a long array must still go out.
overflow decides which end survives: "last" (the default) keeps the most recent entries, "first" keeps the earliest.
daily, the chart shows the last 20 and the compile reports truncated to 20 categories, 5 dropped.
Text limits are applied the way they are for every block: a title over 50 characters, or a label or series name over 20, is truncated and counted.
Limits
A third
data_visualization block in one compiled message is a compile error, not a truncation. Dropping a chart silently would misrepresent the message, so the compile refuses instead and reports how many charts it found. The count is taken after directives run, so blocks produced by an #each count too.
Some inputs are errors rather than warnings: a missing title, an unknown chart type, an arrayPath that does not point at an array, a dynamic chart without label_key or label_template, a wide chart without series, a long-format chart without value_key, and a chart that ends up with no points.
In the builder
Add the block from the picker, choose the chart type and title, then either switch to dynamic and pick the array from your sample data, or edit the series and points in place. Picking an array suggests a mapping from its keys; the numeric ones are marked. The preview is the engine’s own compile of the block over the sample data, with the same warnings a send would carry. The preview is an approximation. Slack draws the final chart with its own colours, spacing and number formatting, and that is what the recipient sees.Common issues
Every point is 0. Thevalue_key does not match a field in the items, or the field holds text that is not a number. Check the item shape in your sample data and look at the warnings.
Categories come out in the wrong order. Without axis.categories the order is first-seen order in the array. Either sort the array before sending it or list the categories.
A series is missing. In long format, series_key must name a field that is present on every row. In wide format, each series needs its own series[] entry.
The message is refused for a third chart. Two per message is Slack’s limit. Split the message or drop a chart.
Nothing draws in the modal. Slack does not support the block in modals. Charts go in messages.
Next steps
Table blocks
Show the same rows as a table next to the chart.
Sample data
Structure the arrays a chart reads from.
Directives
Include a chart only when there is data for it.
Blocks
Other block types and layout options.