Line charts

Use line when category order carries meaning and the path between observations is part of the story. Time is the most common category, but any ordered numeric or categorical dimension can work.

Time series

 1{
 2  "version": "2026-09-26",
 3  "config": {
 4    "version": "2026-09-26",
 5    "title": "Daily active users",
 6    "type": "line",
 7    "category": {
 8      "field": "date",
 9      "scale": {
10        "type": "utc"
11      },
12      "format": "%b %d"
13    },
14    "values": {
15      "type": "long",
16      "field": "users",
17      "format": ",.0f"
18    },
19    "points": true,
20    "valueAxis": {
21      "title": "Users"
22    },
23    "theme": "editorial"
24  },
25  "data": [
26    {
27      "date": "2026-03-01",
28      "users": 1200
29    },
30    {
31      "date": "2026-03-04",
32      "users": 1350
33    },
34    {
35      "date": "2026-03-08",
36      "users": 1280
37    },
38    {
39      "date": "2026-03-13",
40      "users": 1520
41    },
42    {
43      "date": "2026-03-19",
44      "users": 1660
45    },
46    {
47      "date": "2026-03-26",
48      "users": 1840
49    }
50  ],
51  "presentation": {
52    "background": "opaque",
53    "colorScheme": "system",
54    "systemFallback": "light"
55  }
56}

Edit me!

Set category.scale to utc when temporal distance matters. Year strings are recognized as UTC dates; use %Y for annual ticks. Set values.scale to log only for positive measures where ratios and orders of magnitude matter. Use UTC when the value itself is a date or time; ordinary line values remain linear.

Multiple series

Add values.series or use wide values. Series identity drives color, legend entries, and optional end labels.

Direct end labels can replace a legend when there is enough room. Keep the legend when series end near one another or the chart is too narrow for stable labels.

Points and labels

Set points: true to show default markers, or use an options object such as points: { radius: 4 } to customize them. Set points: false or omit it to hide markers. Use points.series in an options object to show points only on named series. Points can also set a fixed fill and a stroke. An explicit stroke color is fixed; omitting it makes the stroke follow each series. Points are useful when observations are sparse, exact sampling matters, or the line must remain legible without relying on path color alone.

Point labels can target all, ends, or extrema and either display category/value semantics or read a dedicated field with an optional format. They sit above the point by default; use position: "side" for side-aligned labels. End labels display series and value. These are separate native placements because they solve different reading tasks.

Curves and line width

Choose linear, monotone, or step. monotone smooths without overshooting observed values; step is appropriate for state that changes at discrete boundaries. Omit curve and stroke to use the selected theme.

References and annotations

Use fixed reference lines for targets, calculated references for averages or extrema, and category references for events. A calculated reference may follow visible legend state or retain all data. Attach an annotation to a category and series when it should follow that point; use { type: "coordinate", category, value } for an exact authored location.

Properties

Field	Type	Default	Description
`version`	"2026-09-26"	`–`	Required. The chart config version.
`type`	ChartType	`–`	Required. The chart family.
`title`	string	`–`	Chart title.
`subtitle`	string	`–`	Supporting text beneath the title.
`caption`	string	`–`	Caption below the chart for a source, methodology note, or date.
`accessibilityDescription`	string	`–`	Accessible description of the chart's meaning.
`headerAlign`	"start" \| "center" \| "end"	`theme default`	Horizontal alignment for the title and subtitle. Omit it to use the selected theme's alignment.
`locale`	string	`"en-US"`	Locale identifier accepted by JavaScript Intl and associated with the chart content, such as en, pl, or zh-Hant.
`theme`	ThemeName	`"editorial"`	One of 6 built-in themes.
`themeOverrides`	ThemeOverrides	`–`	Override individual theme properties.
`category`	CategoryRole	`–`	Required. Category field, scale, and format.
`values`	ValuesRole	`–`	Required. Long, wide, or count value roles.
`order`	CategoryOrder	`–`	Category ordering policy.
`color`	CategoricalColor	`–`	Categorical color preferences.
`categoryAxis`	boolean \| AxisOptions	`–`	True shows the category axis, false hides it, and an options object shows it with those settings. Omit for defaults.
`plotBorder`	boolean	`theme default`	Full plot border, independent of axis visibility.
`valueAxis`	boolean \| AxisOptions	`–`	True shows the value axis, false hides it, and an options object shows it with those settings. Omit for defaults.
`annotations`	CartesianAnnotation[]	`–`	Positioned annotations.
`references`	CategoricalReference[]	`–`	Reference lines.
`curve`	"linear" \| "monotone" \| "step"	`theme default`	Line interpolation.
`stroke`	LineStroke	`theme default`	Line thickness; color follows the series.
`points`	boolean \| LinePointOptions	`–`	True shows default markers; false or omission hides them. An options object enables markers with series selection, radius, fill, and stroke.
`labels`	LineLabels	`–`	End and point labels.