chartshot
Sign inMake a chart
Docs menu

Spec reference

Every field of the chart spec, for each chart type, with its type and default.

This page is built from the spec's JSON Schema, which GET /v1/schema returns for editors and language models. Fields the spec doesn't know are ignored and named in the X-Chart-Warnings header.

Common fields

Every chart type has these. Size presets: email 600 × 300, slack 800 × 400, og 1200 × 630, square 1080 × 1080.

type"line" | "area" | "bar" | "pie" | "donut" | "radar" | "radial" | "scatter" | "combo" | "sparkline" | "kpi"Required
The chart type, which sets the shape of data and the options it takes.
themetheme
A built-in theme name, a saved theme id (theme_…), or an inline theme.Default "default"
mode"light" | "dark"
Use the theme's light or dark colours.Default "light"
preset"email" | "slack" | "og" | "square"
email 600×300, slack 800×400, og 1200×630, square 1080×1080.
widthinteger, 1 to 5000
Width in px. Overrides the preset. Default 600, KPI 300.
heightinteger, 1 to 5000
Height in px. Overrides the preset. Default 300, KPI 150.
scale1 | 2 | 3
Pixel density.Default 2
format"png" | "svg" | "webp"
The image format.Default "png"
background"theme" | "transparent" | hex colour
theme, transparent, or a hex colour. A hex colour also picks the theme's light or dark text and series colours, whichever reads better on it.Default "theme"
altstring
Overrides the generated alt text.

Line

"type": "line"

Data

data.labelsstring[]Required
Category labels along the x axis (y when horizontal).
data.series[].namestringRequired
Shown in the legend and the alt text.
data.series[].values(number | null)[]Required
One value per label; null leaves a gap.
data.series[].colorcolour
A theme colour (chart-1 … chart-15) or a hex colour. Defaults to the next theme colour.

Options

options.titlestring
Drawn at the top of the chart.
options.subtitlestring
Drawn under the title.
options.paddinginteger, 0 to 64
Space around the chart, in px.Default 16
options.localelocale
Locale for numbers and dates.Default "en-GB"
options.legend"top" | "bottom" | "right" | "none"
Legend position. Defaults to bottom for pies, donuts and two or more series, none for one series.
options.gridboolean
Grid lines at the value axis ticks.Default true
options.xAxis.formatformat
number (1,234.5), compact (1.2k), percent (0.124 shows as 12.4%), currency:<ISO code> (currency:USD), or date:<pattern> with yyyy yy MMMM MMM MM M dd d EEEE EEE HH H mm (date:d MMM). Dates are ISO 8601 strings, read as UTC.
options.xAxis.minnumber
Value axis only.
options.xAxis.maxnumber
Value axis only.
options.xAxis.labelstring
Axis title.
options.xAxis.hiddenboolean
Leave out the axis's tick labels and title.Default false
options.yAxis.formatformat
number (1,234.5), compact (1.2k), percent (0.124 shows as 12.4%), currency:<ISO code> (currency:USD), or date:<pattern> with yyyy yy MMMM MMM MM M dd d EEEE EEE HH H mm (date:d MMM). Dates are ISO 8601 strings, read as UTC.
options.yAxis.minnumber
Value axis only.
options.yAxis.maxnumber
Value axis only.
options.yAxis.labelstring
Axis title.
options.yAxis.hiddenboolean
Leave out the axis's tick labels and title.Default false
options.curve"linear" | "monotone" | "step"
How the line joins its values: straight, smoothly, or in steps.Default "monotone"
options.pointsboolean
Draw a dot at each value.Default false

Area

"type": "area"

Data

data.labelsstring[]Required
Category labels along the x axis (y when horizontal).
data.series[].namestringRequired
Shown in the legend and the alt text.
data.series[].values(number | null)[]Required
One value per label; null leaves a gap.
data.series[].colorcolour
A theme colour (chart-1 … chart-15) or a hex colour. Defaults to the next theme colour.

Options

options.titlestring
Drawn at the top of the chart.
options.subtitlestring
Drawn under the title.
options.paddinginteger, 0 to 64
Space around the chart, in px.Default 16
options.localelocale
Locale for numbers and dates.Default "en-GB"
options.legend"top" | "bottom" | "right" | "none"
Legend position. Defaults to bottom for pies, donuts and two or more series, none for one series.
options.gridboolean
Grid lines at the value axis ticks.Default true
options.xAxis.formatformat
number (1,234.5), compact (1.2k), percent (0.124 shows as 12.4%), currency:<ISO code> (currency:USD), or date:<pattern> with yyyy yy MMMM MMM MM M dd d EEEE EEE HH H mm (date:d MMM). Dates are ISO 8601 strings, read as UTC.
options.xAxis.minnumber
Value axis only.
options.xAxis.maxnumber
Value axis only.
options.xAxis.labelstring
Axis title.
options.xAxis.hiddenboolean
Leave out the axis's tick labels and title.Default false
options.yAxis.formatformat
number (1,234.5), compact (1.2k), percent (0.124 shows as 12.4%), currency:<ISO code> (currency:USD), or date:<pattern> with yyyy yy MMMM MMM MM M dd d EEEE EEE HH H mm (date:d MMM). Dates are ISO 8601 strings, read as UTC.
options.yAxis.minnumber
Value axis only.
options.yAxis.maxnumber
Value axis only.
options.yAxis.labelstring
Axis title.
options.yAxis.hiddenboolean
Leave out the axis's tick labels and title.Default false
options.curve"linear" | "monotone" | "step"
How the line joins its values: straight, smoothly, or in steps.Default "monotone"
options.pointsboolean
Draw a dot at each value.Default false
options.stackedboolean
Stack the series on top of each other.Default false
options.fillOpacitynumber, 0 to 1
Opacity of the fill under each line.Default 0.4

Bar

"type": "bar"

Data

data.labelsstring[]Required
Category labels along the x axis (y when horizontal).
data.series[].namestringRequired
Shown in the legend and the alt text.
data.series[].values(number | null)[]Required
One value per label; null leaves a gap.
data.series[].colorcolour
A theme colour (chart-1 … chart-15) or a hex colour. Defaults to the next theme colour.

Options

options.titlestring
Drawn at the top of the chart.
options.subtitlestring
Drawn under the title.
options.paddinginteger, 0 to 64
Space around the chart, in px.Default 16
options.localelocale
Locale for numbers and dates.Default "en-GB"
options.legend"top" | "bottom" | "right" | "none"
Legend position. Defaults to bottom for pies, donuts and two or more series, none for one series.
options.gridboolean
Grid lines at the value axis ticks.Default true
options.xAxis.formatformat
number (1,234.5), compact (1.2k), percent (0.124 shows as 12.4%), currency:<ISO code> (currency:USD), or date:<pattern> with yyyy yy MMMM MMM MM M dd d EEEE EEE HH H mm (date:d MMM). Dates are ISO 8601 strings, read as UTC.
options.xAxis.minnumber
Value axis only.
options.xAxis.maxnumber
Value axis only.
options.xAxis.labelstring
Axis title.
options.xAxis.hiddenboolean
Leave out the axis's tick labels and title.Default false
options.yAxis.formatformat
number (1,234.5), compact (1.2k), percent (0.124 shows as 12.4%), currency:<ISO code> (currency:USD), or date:<pattern> with yyyy yy MMMM MMM MM M dd d EEEE EEE HH H mm (date:d MMM). Dates are ISO 8601 strings, read as UTC.
options.yAxis.minnumber
Value axis only.
options.yAxis.maxnumber
Value axis only.
options.yAxis.labelstring
Axis title.
options.yAxis.hiddenboolean
Leave out the axis's tick labels and title.Default false
options.stackedboolean
Stack the series in one bar per label.Default false
options.horizontalboolean
Bars run left to right; labels on the y axis.Default false
options.radiusnumber, 0 to 32
Corner radius in px. Defaults to the theme's.
options.valueLabelsboolean
Print each bar's value at its end.Default false

Pie

"type": "pie"

Data

data.slices[].labelstringRequired
The slice's name, in the legend.
data.slices[].valuenumberRequired
The slice's size; each is drawn as its share of the total.
data.slices[].colorcolour
A theme colour (chart-1 … chart-15) or a hex colour. Defaults to the next theme colour.

Options

options.titlestring
Drawn at the top of the chart.
options.subtitlestring
Drawn under the title.
options.paddinginteger, 0 to 64
Space around the chart, in px.Default 16
options.localelocale
Locale for numbers and dates.Default "en-GB"
options.legend"top" | "bottom" | "right" | "none"
Legend position. Defaults to bottom for pies, donuts and two or more series, none for one series.
options.sliceLabels"none" | "percent" | "value"
Text on each slice: nothing, its share of the total, or its value.Default "none"
options.valueFormatformat
Format of slice values. Defaults to number.

Donut

"type": "donut"

Data

data.slices[].labelstringRequired
The slice's name, in the legend.
data.slices[].valuenumberRequired
The slice's size; each is drawn as its share of the total.
data.slices[].colorcolour
A theme colour (chart-1 … chart-15) or a hex colour. Defaults to the next theme colour.

Options

options.titlestring
Drawn at the top of the chart.
options.subtitlestring
Drawn under the title.
options.paddinginteger, 0 to 64
Space around the chart, in px.Default 16
options.localelocale
Locale for numbers and dates.Default "en-GB"
options.legend"top" | "bottom" | "right" | "none"
Legend position. Defaults to bottom for pies, donuts and two or more series, none for one series.
options.sliceLabels"none" | "percent" | "value"
Text on each slice: nothing, its share of the total, or its value.Default "none"
options.valueFormatformat
Format of slice values. Defaults to number.
options.innerRadiusnumber, 0.3 to 0.9
Hole size as a share of the radius.Default 0.6
options.centerLabelstring
Text in the hole, such as the total.

Radar

"type": "radar"

Data

data.labelsstring[]Required
Category labels along the x axis (y when horizontal).
data.series[].namestringRequired
Shown in the legend and the alt text.
data.series[].values(number | null)[]Required
One value per label; null leaves a gap.
data.series[].colorcolour
A theme colour (chart-1 … chart-15) or a hex colour. Defaults to the next theme colour.

Options

options.titlestring
Drawn at the top of the chart.
options.subtitlestring
Drawn under the title.
options.paddinginteger, 0 to 64
Space around the chart, in px.Default 16
options.localelocale
Locale for numbers and dates.Default "en-GB"
options.legend"top" | "bottom" | "right" | "none"
Legend position. Defaults to bottom for pies, donuts and two or more series, none for one series.
options.grid"polygon" | "circle" | "none"
Shape of the grid: polygons through each label's spoke, or circles.Default "polygon"
options.fillOpacitynumber, 0 to 1
Fill of each series' shape. 0 draws outlines only.Default 0.6
options.pointsboolean
Draw a dot at each value.Default false
options.minnumber
Value at the centre. Defaults to 0, or the lowest value below it.
options.maxnumber
Value at the edge. Defaults to a round number past the highest.
options.valueFormatformat
Format of values in the alt text. Defaults to number.

Radial

"type": "radial"

Data

data.bars[].labelstringRequired
The ring's name, in the legend.
data.bars[].valuenumberRequired
How far round the ring goes, out of options.max.
data.bars[].colorcolour
A theme colour (chart-1 … chart-15) or a hex colour. Defaults to the next theme colour.

Options

options.titlestring
Drawn at the top of the chart.
options.subtitlestring
Drawn under the title.
options.paddinginteger, 0 to 64
Space around the chart, in px.Default 16
options.localelocale
Locale for numbers and dates.Default "en-GB"
options.legend"top" | "bottom" | "right" | "none"
Legend position. Defaults to bottom for pies, donuts and two or more series, none for one series.
options.maxnumber
Value of a full ring, such as 100 for a progress ring. Defaults to the largest value, or the total when stacked.
options.sweepnumber, over 0, up to 360
Degrees a full ring goes round, centred at the top: 360 a circle, 180 a half-circle gauge.Default 360
options.stackedboolean
Put every value end to end in one ring.Default false
options.trackboolean
Draw each ring's full length faintly behind it.Default true
options.innerRadiusnumber, 0 to 0.9
Where the innermost ring starts, as a share of the radius. Defaults to 0.3 for several rings, 0.6 for one ring or a stack.
options.centerLabelstring
Text in the middle, such as the value.
options.valueFormatformat
Format of values in the alt text. Defaults to number.

Scatter

"type": "scatter"

Data

data.series[].namestringRequired
Shown in the legend and the alt text.
data.series[].points[].xnumberRequired
A finite number.
data.series[].points[].ynumberRequired
A finite number.
data.series[].points[].sizenumber
Bubble size: a point's area grows with it.
data.series[].colorcolour
A theme colour (chart-1 … chart-15) or a hex colour. Defaults to the next theme colour.

Options

options.titlestring
Drawn at the top of the chart.
options.subtitlestring
Drawn under the title.
options.paddinginteger, 0 to 64
Space around the chart, in px.Default 16
options.localelocale
Locale for numbers and dates.Default "en-GB"
options.legend"top" | "bottom" | "right" | "none"
Legend position. Defaults to bottom for pies, donuts and two or more series, none for one series.
options.gridboolean
Grid lines at both axes' ticks.Default true
options.xAxis.formatformat
number (1,234.5), compact (1.2k), percent (0.124 shows as 12.4%), currency:<ISO code> (currency:USD), or date:<pattern> with yyyy yy MMMM MMM MM M dd d EEEE EEE HH H mm (date:d MMM). Dates are ISO 8601 strings, read as UTC.
options.xAxis.minnumber
Value axis only.
options.xAxis.maxnumber
Value axis only.
options.xAxis.labelstring
Axis title.
options.xAxis.hiddenboolean
Leave out the axis's tick labels and title.Default false
options.yAxis.formatformat
number (1,234.5), compact (1.2k), percent (0.124 shows as 12.4%), currency:<ISO code> (currency:USD), or date:<pattern> with yyyy yy MMMM MMM MM M dd d EEEE EEE HH H mm (date:d MMM). Dates are ISO 8601 strings, read as UTC.
options.yAxis.minnumber
Value axis only.
options.yAxis.maxnumber
Value axis only.
options.yAxis.labelstring
Axis title.
options.yAxis.hiddenboolean
Leave out the axis's tick labels and title.Default false

Combo

"type": "combo"

Data

data.labelsstring[]Required
Category labels along the x axis.
data.series[].namestringRequired
Shown in the legend and the alt text.
data.series[].values(number | null)[]Required
One value per label; null leaves a gap.
data.series[].colorcolour
A theme colour (chart-1 … chart-15) or a hex colour. Defaults to the next theme colour.
data.series[].type"bar" | "line"
Draw this series as bars or a line.Default "bar"
data.series[].axis"left" | "right"
The value axis: left (yAxis) or right (y2Axis).Default "left"

Options

options.titlestring
Drawn at the top of the chart.
options.subtitlestring
Drawn under the title.
options.paddinginteger, 0 to 64
Space around the chart, in px.Default 16
options.localelocale
Locale for numbers and dates.Default "en-GB"
options.legend"top" | "bottom" | "right" | "none"
Legend position. Defaults to bottom for pies, donuts and two or more series, none for one series.
options.gridboolean
Grid lines at the value axis ticks.Default true
options.xAxis.formatformat
number (1,234.5), compact (1.2k), percent (0.124 shows as 12.4%), currency:<ISO code> (currency:USD), or date:<pattern> with yyyy yy MMMM MMM MM M dd d EEEE EEE HH H mm (date:d MMM). Dates are ISO 8601 strings, read as UTC.
options.xAxis.minnumber
Value axis only.
options.xAxis.maxnumber
Value axis only.
options.xAxis.labelstring
Axis title.
options.xAxis.hiddenboolean
Leave out the axis's tick labels and title.Default false
options.yAxis.formatformat
number (1,234.5), compact (1.2k), percent (0.124 shows as 12.4%), currency:<ISO code> (currency:USD), or date:<pattern> with yyyy yy MMMM MMM MM M dd d EEEE EEE HH H mm (date:d MMM). Dates are ISO 8601 strings, read as UTC.
options.yAxis.minnumber
Value axis only.
options.yAxis.maxnumber
Value axis only.
options.yAxis.labelstring
Axis title.
options.yAxis.hiddenboolean
Leave out the axis's tick labels and title.Default false
options.y2Axis.formatformat
number (1,234.5), compact (1.2k), percent (0.124 shows as 12.4%), currency:<ISO code> (currency:USD), or date:<pattern> with yyyy yy MMMM MMM MM M dd d EEEE EEE HH H mm (date:d MMM). Dates are ISO 8601 strings, read as UTC.
options.y2Axis.minnumber
Value axis only.
options.y2Axis.maxnumber
Value axis only.
options.y2Axis.labelstring
Axis title.
options.y2Axis.hiddenboolean
Leave out the axis's tick labels and title.Default false
options.curve"linear" | "monotone" | "step"
How the line joins its values: straight, smoothly, or in steps.Default "monotone"
options.pointsboolean
Draw a dot at each line value.Default false
options.stackedboolean
Stack the bars on each axis.Default false
options.radiusnumber, 0 to 32
Bar corner radius in px. Defaults to the theme's.

Sparkline

"type": "sparkline"

Data

data.values(number | null)[]Required
The values to draw, in order; null leaves a gap.

Options

options.paddinginteger, 0 to 64
Space around the line, in px.Default 0
options.curve"linear" | "monotone" | "step"
How the line joins its values: straight, smoothly, or in steps.Default "monotone"
options.colorcolour
A theme colour (chart-1 … chart-15) or a hex colour. Defaults to the next theme colour.

KPI

"type": "kpi"

Data

data.labelstringRequired
What the number is, such as MRR.
data.valuenumberRequired
The number, in valueFormat.
data.deltanumber
Change to show beside the value, in deltaFormat (0.124 shows as +12.4%).
data.trendnumber[]
Recent values for a mini trend line.

Options

options.paddinginteger, 0 to 64
Space around the chart, in px.Default 16
options.localelocale
Locale for numbers and dates.Default "en-GB"
options.valueFormatformat
number (1,234.5), compact (1.2k), percent (0.124 shows as 12.4%), currency:<ISO code> (currency:USD), or date:<pattern> with yyyy yy MMMM MMM MM M dd d EEEE EEE HH H mm (date:d MMM). Dates are ISO 8601 strings, read as UTC.Default "number"
options.deltaFormatformat
number (1,234.5), compact (1.2k), percent (0.124 shows as 12.4%), currency:<ISO code> (currency:USD), or date:<pattern> with yyyy yy MMMM MMM MM M dd d EEEE EEE HH H mm (date:d MMM). Dates are ISO 8601 strings, read as UTC.Default "percent"
options.increaseIsGoodboolean
Whether a rise is good news, drawn in the positive colour. False for churn or cost.Default true

Formats

number (1,234.5), compact (1.2k), percent (0.124 shows as 12.4%), currency:<ISO code> (currency:USD), or date:<pattern> with yyyy yy MMMM MMM MM M dd d EEEE EEE HH H mm (date:d MMM). Dates are ISO 8601 strings, read as UTC.

  • number
  • compact
  • percent
  • currency:USD
  • date:d MMM

Colours

A theme colour (chart-1 … chart-15) or a hex colour. Defaults to the next theme colour.

Themes

A built-in theme name, a saved theme id (theme_…), or an inline theme. The built-in themes:

  • default
  • slate
  • midnight
  • ocean
  • sunset
  • mono

An inline theme starts from a built-in one and overrides some of its tokens:

theme.extends"default" | "slate" | "midnight" | "ocean" | "sunset" | "mono"
Built-in theme to start from.Default "default"
theme.font"Geist" | "Inter" | "DM Sans" | "Figtree" | "IBM Plex Sans" | "Lora" | "Manrope" | "Merriweather" | "Montserrat" | "Noto Sans" | "Nunito" | "Open Sans" | "Outfit" | "Plus Jakarta Sans" | "Poppins" | "Raleway" | "Roboto" | "Rubik" | "Source Sans 3" | "Work Sans"
Font for both modes. A mode's own fontFamily wins over it.
theme.lighttokens
Token overrides for light mode.
theme.darktokens
Token overrides for dark mode.

Tokens

Each mode, light and dark, can set any of these:

backgroundhex colour
Image background (shadcn --background).
foregroundhex colour
Title and legend text (--foreground).
mutedForegroundhex colour
Subtitle and axis labels (--muted-foreground).
borderhex colour
Grid lines, drawn at half this colour's opacity (--border).
positivehex colour
A KPI change for the better, such as revenue up.
negativehex colour
A KPI change for the worse (shadcn --destructive).
chart1 … chart15hex colour
Series colours, in order. A colour of chart-3 in the spec is chart3.
fontFamily"Geist" | "Inter" | "DM Sans" | "Figtree" | "IBM Plex Sans" | "Lora" | "Manrope" | "Merriweather" | "Montserrat" | "Noto Sans" | "Nunito" | "Open Sans" | "Outfit" | "Plus Jakarta Sans" | "Poppins" | "Raleway" | "Roboto" | "Rubik" | "Source Sans 3" | "Work Sans"
One of the bundled fonts.
radiusnumber, 0 to 32
Corner radius of bars, in px.

Fonts

A theme's font is one of these, each bundled in three weights:

  • Geist
  • Inter
  • DM Sans
  • Figtree
  • IBM Plex Sans
  • Lora
  • Manrope
  • Merriweather
  • Montserrat
  • Noto Sans
  • Nunito
  • Open Sans
  • Outfit
  • Plus Jakarta Sans
  • Poppins
  • Raleway
  • Roboto
  • Rubik
  • Source Sans 3
  • Work Sans

Locales

Locale for numbers and dates.

  • en-GB
  • en-US
  • en-AU
  • en-CA
  • en-IE
  • en-IN
  • en-NZ
  • en-ZA
  • de-DE
  • de-AT
  • de-CH
  • fr-FR
  • fr-BE
  • fr-CA
  • fr-CH
  • es-ES
  • es-MX
  • es-AR
  • it-IT
  • nl-NL
  • nl-BE
  • pt-PT
  • pt-BR
  • sv-SE
  • da-DK
  • nb-NO
  • fi-FI
  • pl-PL
  • cs-CZ
  • sk-SK
  • hu-HU
  • ro-RO
  • tr-TR
  • id-ID
PreviousMCP for AI assistantsNextAPI