Chart

Unified Chart Type Taxonomy

Shared by Dashboard and Report widgets. Provides a comprehensive set of chart types for data visualization.

Source: packages/spec/src/ui/chart.zod.ts

TypeScript Usage

import { ChartAggregateSchema, ChartAggregateFunctionSchema, ChartAnnotationSchema, ChartAxisSchema, ChartConfigSchema, ChartDrillDownSchema, ChartGroupBySchema, ChartInteractionSchema, ChartSeriesSchema, ChartTypeSchema } from '@objectstack/spec/ui';
import type { ChartAggregate, ChartAggregateFunction, ChartAnnotation, ChartAxis, ChartConfig, ChartDrillDown, ChartGroupBy, ChartInteraction, ChartSeries, ChartType } from '@objectstack/spec/ui';

// Validate data
const result = ChartAggregateSchema.parse(data);

ChartAggregate

Inline aggregation for an object-bound chart

Properties

Property	Type	Required	Description
field	`string`	optional	Field to aggregate — required for sum/avg/min/max, optional for count
function	`Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max'>`	✅	Aggregation function
groupBy	`string \| { field: string; dateGranularity?: Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>; alias?: string }`	✅	Field the rows are grouped by — the chart category axis

ChartAggregateFunction

Allowed Values

count
sum
avg
min
max

ChartAnnotation

Properties

Property	Type	Required	Description
type	`Enum<'line' \| 'region'>`	✅
axis	`Enum<'x' \| 'y'>`	✅
value	`number \| string`	✅	Start value
endValue	`number \| string`	optional	End value for regions
color	`string`	optional
label	`string \| Record<string, string>`	optional	Display label — the default-language string, or an inline locale map (`{ en, "zh-CN" }`) resolved at render time
style	`Enum<'solid' \| 'dashed' \| 'dotted'>`	✅

ChartAxis

Properties

Property	Type	Required	Description
field	`string`	✅	Data field key
title	`string \| Record<string, string>`	optional	Axis display title
format	`string`	optional	Value format string (e.g., "$0,0.00")
min	`number`	optional	Minimum value
max	`number`	optional	Maximum value
stepSize	`number`	optional	Step size for ticks
showGridLines	`boolean`	✅
position	`Enum<'left' \| 'right' \| 'top' \| 'bottom'>`	optional	Axis position
logarithmic	`boolean`	✅

ChartConfig

Properties

Property	Type	Required	Description
type	`Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'treemap' \| 'sankey' \| 'combo' \| 'gauge' \| 'solid-gauge' \| … +6 more>`	✅
title	`string \| Record<string, string>`	optional	Chart title
subtitle	`string \| Record<string, string>`	optional	Chart subtitle
description	`string \| Record<string, string>`	optional	Accessibility description — announced to screen readers as the chart’s label
xAxis	`{ field: string; title?: string \| Record<string, string>; format?: string; min?: number; … }`	optional	X-Axis configuration
yAxis	`{ field: string; title?: string \| Record<string, string>; format?: string; min?: number; … }[]`	optional	Y-Axis configuration (support dual axis)
series	`{ name: string; label?: string \| Record<string, string>; type?: Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| … +13 more>; color?: string; … }[]`	optional	Defined series configuration
colors	`string[] \| Record<string, string>`	optional	Color palette (string[]) or value→color map (`{ value: color }`)
height	`number`	optional	Fixed plot height in pixels (overrides the container default)
showLegend	`boolean`	✅	Display legend
showDataLabels	`boolean`	✅	Display data labels
annotations	`{ type: Enum<'line' \| 'region'>; axis: Enum<'x' \| 'y'>; value: number \| string; endValue?: number \| string; … }[]`	optional	Reference lines/bands drawn over the plot: `{ type: "line" \| "region", axis: "x" \| "y", value, endValue?, color?, label?, style? }`
interaction	`{ tooltips: boolean; brush: boolean }`	optional	Interaction toggles: `{ tooltips?, brush? }`
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Allowed Values: `ChartConfig.type`

bar
horizontal-bar
column
line
area
pie
donut
funnel
scatter
treemap
sankey
combo
gauge
solid-gauge
metric
kpi
bullet
radar
table
pivot

ChartDrillDown

Properties

Property	Type	Required	Description
enabled	`boolean`	optional	Turn the segment drill on/off; the block being present already means on, so this is only needed to force it off
filter	`Record<string, any>`	optional	Filter for the drilled list; values support $`{event.*}`. Omit to derive it from the clicked category
title	`string`	optional	Drill drawer/dialog heading; supports $`{event.*}` interpolation
target	`Enum<'drawer' \| 'dialog' \| 'navigate'>`	optional	Where the drilled list opens: 'drawer' (default, side sheet), 'dialog' (centered modal), or 'navigate' (skip the in-place view and open the object's full list page; needs host drill navigation, else falls back to 'drawer')
columns	`string[]`	optional	Field names to show as columns in the drilled list (default: the table's own columns)
maxRows	`integer`	optional	Rows per page in the drilled list

ChartGroupBy

Union Options

This schema accepts one of the following structures:

Option 1

Field to group by

Type: string

Option 2

Properties

Property	Type	Required	Description
field	`string`	✅	Field to group by
dateGranularity	`Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>`	optional	Bucket date values into uniform periods
alias	`string`	optional	Alias for the projected group value (defaults to `field`) — this becomes the category column

ChartInteraction

Properties

Property	Type	Required	Description
tooltips	`boolean`	✅	Show the hover tooltip
brush	`boolean`	✅	Show the range selector under the plot

ChartSeries

Properties

Property	Type	Required	Description
name	`string`	✅	Field name or series identifier
label	`string \| Record<string, string>`	optional	Series display label
type	`Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'treemap' \| 'sankey' \| 'combo' \| 'gauge' \| 'solid-gauge' \| … +6 more>`	optional	Override chart type for this series
color	`string`	optional	Series color (hex/rgb/token)
stack	`string`	optional	Stack identifier to group series
yAxis	`Enum<'left' \| 'right'>`	✅	Bind to specific Y-Axis
variant	`Enum<'primary' \| 'comparison'>`	optional	Series visual role
dashArray	`string`	optional	SVG stroke-dasharray override
opacity	`number`	optional	Series opacity override

Allowed Values: `ChartSeries.type`

bar
horizontal-bar
column
line
area
pie
donut
funnel
scatter
treemap
sankey
combo
gauge
solid-gauge
metric
kpi
bullet
radar
table
pivot

ChartType

Allowed Values

bar
horizontal-bar
column
line
area
pie
donut
funnel
scatter
treemap
sankey
combo
gauge
solid-gauge
metric
kpi
bullet
radar
table
pivot

On this page