Overview of Block Outputs
Create rich visual outputs like charts, tables, KPI cards, and layouts in your tools and agents.
Overview
The Block class provides methods to create rich visual outputs in your tools and agents. Every handler function receives a block object that lets you build charts, tables, KPI cards, images, and complex layouts—all from your backend code.
handler: async ({ block }) => {
return block.barChart({
title: 'Monthly Revenue',
data: revenueData,
index: 'month',
categories: ['revenue', 'expenses'],
})
}Block outputs are returned from your handler or displayed via io.message().
Tool Forge automatically renders them as interactive visualizations in the
dashboard.
Charts
Visualize data with a variety of chart types.
Area Chart
Visualize trends over time with filled areas.
Bar Chart
Compare categorical data with horizontal or vertical bars.
Line Chart
Display trends and changes over continuous data.
Donut Chart
Show proportions and percentages in a circular format.
Combo Chart
Combine bar and line charts for multi-series data.
Heatmap Chart
Visualize matrix data with color-coded cells.
Spark Chart
Compact inline charts for quick trend visualization.
Progress & Status
Track progress and display status indicators.
Progress Bar
Horizontal bar showing progress towards a goal.
Progress Circle
Circular progress indicator.
Tracker
Status tracker with color-coded items.
Category Bar
Horizontal bar with categorical segments.
Bar List
Vertical list of horizontal bars for comparisons.
Data Display
Present data in structured formats.
KPI Card
Key metrics with optional change indicators and charts.
Table
Structured data with sorting, filtering, and custom rendering.
Object
Display key-value pairs from structured data.
Content & Layout
Display content and arrange multiple blocks.
Image
Display images from URLs or binary data.
Text
Render markdown-formatted text content.
Layout
Arrange multiple blocks in a responsive grid.
Quick Reference
| Method | Description | Category |
|---|---|---|
areaChart() | Area chart with gradient fills | Charts |
barChart() | Vertical or horizontal bar chart | Charts |
lineChart() | Line chart for trends | Charts |
donutChart() | Donut or pie chart | Charts |
comboChart() | Combined bar and line chart | Charts |
heatmapChart() | Color-coded matrix chart | Charts |
sparkChart() | Compact inline chart | Charts |
progressBar() | Horizontal progress indicator | Progress |
progressCircle() | Circular progress indicator | Progress |
tracker() | Status tracker | Progress |
categoryBar() | Segmented category bar | Progress |
barList() | List of comparison bars | Progress |
kpiCard() | Key performance indicator card | Data Display |
table() | Data table with features | Data Display |
object() | Key-value display | Data Display |
image() | Image display | Content |
text() | Markdown text | Content |
layout() | Grid layout container | Layout |
Common Patterns
Returning a Block
Return a block directly from your handler:
handler: async ({ block }) => {
const data = await fetchSalesData()
return block.barChart({
title: 'Sales by Region',
data,
index: 'region',
categories: ['sales'],
colors: ['blue'],
})
}Displaying Blocks with Messages
Use io.message() to display blocks mid-workflow:
handler: async ({ io, block }) => {
const data = await processData()
await io.message({
title: 'Processing Complete',
message: block.kpiCard({
name: 'Records Processed',
value: data.count,
change: 15,
changeType: 'positive',
}),
})
// Continue with more operations...
}Creating Dashboards with Layout
Combine multiple blocks in a grid layout:
handler: async ({ block }) => {
return block.layout({
columns: 12,
children: [
{
element: block.kpiCard({ name: 'Revenue', value: 125000 }),
colSpan: 4,
},
{
element: block.kpiCard({ name: 'Users', value: 8420 }),
colSpan: 4,
},
{
element: block.kpiCard({ name: 'Conversion', value: '3.2%' }),
colSpan: 4,
},
{
element: block.areaChart({
title: 'Revenue Trend',
data: monthlyData,
index: 'month',
categories: ['revenue'],
}),
colSpan: 8,
},
{
element: block.donutChart({
title: 'Revenue by Source',
data: sourceData,
category: 'source',
value: 'revenue',
}),
colSpan: 4,
},
],
})
}Value Formatting
Format numbers as currency, percentages, or with custom options:
block.kpiCard({
name: 'Total Revenue',
value: 125000,
valueFormat: {
type: 'currency',
currency: 'USD',
notation: 'compact', // Shows as $125K
},
})
block.barChart({
// ...chart config
valueFormat: {
type: 'percentage',
decimals: 1,
},
})Available Colors
Charts support these color options:
type ChartColor =
| 'blue'
| 'emerald'
| 'violet'
| 'amber'
| 'gray'
| 'cyan'
| 'pink'
| 'lime'
| 'fuchsia'
| 'red'
| 'green'
| 'yellow'