Skip to main content
Chart is a namespace, not a component you can render. Import it as Chart and use one of its members: Chart.Bar, Chart.Line, Chart.Pie, Chart.Metric, Chart.Funnel, or Chart.Loading.
Charts are read-only representations of data: there are no click or hover handlers, and tooltips are always drawn. Charts take the full width of their container, so pair them with Sections and Tables to get the layout you want. Available in dialogs, record widgets and full page apps. They do not render on mobile or in the browser extension. Every data point is serialized across the app/host bridge. Very large sets (10k+ points) can block the main thread.

​
Which chart to use

Pick by the question the chart answers, not by the data you happen to have.

Chart.Metric

One number, rendered large. A total, a count, a rate. Nothing to compare it against, so nothing is plotted.

Chart.Bar

Compare values across categories. Several series per category, side by side (mode="grouped") or as one stack (mode="stacked").

Chart.Line

Follow a value along an ordered axis, usually dates. Use it when the shape of the trend matters more than each individual value.

Chart.Pie

Parts of one whole, a handful of slices. Slices always draw largest first, so use it for composition, never for ranking over time.

Chart.Funnel

Ordered stages, each measured against the one before. Conversion through a pipeline, not composition of a total.

Chart.Loading

A placeholder while data is in flight. Give it the height of the chart it stands in for.

​
At a glance

​
Shared props

These apply to every chart except Chart.Loading, which only takes height.

​
title

An optional caption above the chart.

​
height

The token covers the whole chart: a title and a legend fit inside it rather than adding to it. Defaults to "medium". Height tokens do not shrink. If the surface is shorter than the token, the surface scrolls rather than squeezing the chart to a blank box.

​
Color tokens

Names rather than hex values, so charts follow the viewer’s theme: "blue" "green" "yellow" "orange" "red" "purple" "pink" "teal" "grey" On a cartesian chart, set color on series, not on each point. On a pie or funnel, set color on each slice or step. A metric takes color on the component. The default is the report palette slot, except metric and funnel steps, which default to "blue".

​
format

How a value is rendered, in the viewer’s locale. These examples are from the en-US tests against the shipped formatter.
format="currency" needs the sibling currency code, an ISO 4217 value such as "USD", "EUR", or "BRL". Every other format rejects currency.format="percent" takes a fraction: send 0.42, not 42.format="date" reads an ISO string as the calendar date it names, so the viewer’s timezone never shifts it a day. Send x as an ISO string or a number, never a Date.

​
States

  • Chart.Loading is the placeholder while data is in flight. Give it the same height as the chart it stands in for so the dialog does not reflow.
  • An empty data array (and a funnel whose first step is 0) draws No data instead of a plot.
  • If the host cannot draw the chart, the error boundary draws Something went wrong and keeps the resolved height.