Widget Reference
Complete reference for all 6 widget types and 13 chart types. Every property the AI agent can set.
Chart Widget
The most versatile widget. Supports 13 chart types using Recharts under the hood.
Chart Types
AI Agent Usage
KPI Widget
Single-metric card for executive dashboards. Shows a primary value with trend indicator, target progress bar, and optional sparkline — inspired by Power BI KPI tiles.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | number | string | — | The primary metric value |
| format | string | — | d3 format string, e.g. '$,.0f' |
| unit | string | — | Unit suffix: '%', 'users', 'ms' |
| trend | 'up' | 'down' | 'flat' | 'flat' | Trend direction indicator |
| trendValue | string | — | Change label, e.g. '+8.2%' |
| trendPositive | boolean | true | Whether up = good (green) or bad (red) |
| comparisonLabel | string | — | Context: 'vs last month', 'YoY' |
| target | number | — | Renders a progress bar when set |
| sparkline | number[] | — | Mini line chart data points |
| icon | string | — | Emoji or icon shown above value |
| accent | color enum | 'indigo' | Visual accent color |
Gauge Widget
Semicircular gauge for progress, utilization, and SLA metrics. Supports colored zones and a target marker — like Power BI gauge visuals.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | number | 0 | Current gauge value |
| min | number | 0 | Minimum (left edge) |
| max | number | 100 | Maximum (right edge) |
| target | number | — | Target tick mark on the arc |
| format | string | — | d3 format for center label |
| unit | string | — | Unit suffix |
| zones | Zone[] | — | Color segments: [{limit, color, label}] |
| variant | 'semicircle' | 'full' | 'linear' | 'semicircle' | Visual style |
Filter Widget (Slicer)
Interactive filter control for dashboard slicing. The AI agent creates these to add user-controlled filtering — similar to Power BI slicers and Tableau filters. Filters can target other widgets via targetWidgetIds.
| Prop | Type | Default | Description |
|---|---|---|---|
| filterType | 'dropdown' | 'checkbox' | 'range' | 'date' | 'search' | 'dropdown' | Control type |
| field | string | — | Data field this filter applies to |
| label | string | — | Display label |
| options | string[] | [] | Available options (dropdown/checkbox) |
| selectedValues | string[] | [] | Currently active selections |
| rangeMin / rangeMax | number | — | Bounds for range/date filters |
| multiSelect | boolean | true | Allow multiple selections |
| targetWidgetIds | string[] | [] | Widget IDs to cross-filter |
Table Widget
Data table with virtual scrolling, sparklines, conditional formatting, sorting, and search. Handles thousands of rows via @tanstack/react-virtual.
| Prop | Type | Default | Description |
|---|---|---|---|
| columns | ColumnDef[] | [] | Column definitions |
| autoColumns | boolean | true | Auto-infer columns from data |
| pagination | {mode, pageSize} | — | 'virtual' | 'paginated' | 'none' |
| sort | {field, direction} | — | Active sort column |
| searchQuery | string | — | Client-side text filter |
| stickyHeader | boolean | true | Freeze header row |
| showSummaryRow | boolean | false | Footer totals row |
| selectionMode | 'none' | 'single' | 'multi' | 'none' | Row selection |
Column Features
- Sparklines —
sparkline: { type: "line", valuesField: "trend" } - Conditional formatting — JS expressions:
{ condition: "value >= 15000", style: { color: "#10b981" } } - Pinning —
pin: "left" | "right" - Alignment —
align: "left" | "center" | "right" - d3 formatting —
format: "$,.0f"
Note Widget
Free-form Markdown note for analysis commentary, summaries, and agent-generated insights. Supports accent colors, tags, and cross-references to other widgets via mentions.
| Prop | Type | Default | Description |
|---|---|---|---|
| content | string | '' | Markdown content |
| accent | color enum | 'neutral' | Card accent color |
| mentions | string[] | [] | Referenced widget IDs |
| fontSize | 'sm' | 'md' | 'lg' | 'md' | Text size |
| tags | string[] | [] | Semantic tags for search |
| authorType | 'human' | 'agent' | 'human' | Attribution |
| agentModel | string | — | Model ID if agent-authored |
Base Properties (All Widgets)
Every widget inherits these properties from BaseWidgetSchema.
| Prop | Type | Default | Description |
|---|---|---|---|
| id | string | — | Stable unique ID (use generateWidgetId()) |
| type | string | — | Widget type discriminant |
| x, y | number | — | Canvas position |
| width | number | 600 | Widget width in px |
| height | number | 400 | Widget height in px |
| title | string | 'Untitled' | Header title |
| dataBinding | DataBinding | null | null | JSON or Arrow data source |
| locked | boolean | false | Prevent agent mutations |
| lastModifiedBy | string | 'human' | Agent attribution |
| zIndex | number | 0 | Layer ordering |
AI-First Design
Every widget type is designed for LLM agents to create and modify seamlessly. The agent sees a summarized view of the canvas and produces AgentPatchmutations validated against Zod schemas.
How the Agent Decides Which Widget to Use
- Single metric → KPI card
- Progress / utilization → Gauge
- Time-series trends → Line / Area chart
- Categorical comparison → Bar chart
- Composition / share → Pie / Donut / Treemap
- Multi-dimension comparison → Radar chart
- Conversion pipeline → Funnel chart
- Dual metric overlay → Combo chart
- Running totals → Waterfall chart
- Activity patterns → Heatmap
- Goal tracking → Radial bar
- Raw data exploration → Table widget
- Analysis narrative → Note widget
- User-controlled slicing → Filter widget