Chart

The Chart component displays data in a graphical format.

Chart types

The Chart component supports four different types of charts: scatter plots, line charts, bar charts, and pie charts.

Scatter plots

In the example below, weight is chosen to be the x-axis, and one point is generated for each pair of (weight, length) provided.

Line charts

In the example below, age is chosen to be the x-axis. Three different datasets are provided, representing a different cat each (Baosky, Hazel, Peaches), and one line is generated for each cat by joining up the provided weights at different ages.

Bar charts

In the example below, age is chosen to be the x-axis. Three different datasets are provided, representing a different cat each (Baosky, Hazel, Peaches). For each different value of the x-axis, a set of bars is generated for each dataset, indicating the weight of the cat at that age.

Pie charts

In the example below, three different data points are provided, each with a single food attribute that indicates the amount of food that a particular cat has eaten that week. The labels prop is used to indicate which cat each amount of food corresponds to.
Note that pie charts only take a single axis, unlike the other series-based charts.

Data format

The Chart component can receive data through the data prop. This prop expects data in one of two formats: row-based or column-based. The format will be automatically inferred by the Chart component.

Row-based data

A chart with row-based data expects to receive a list of objects.
For scatter, bar, and line charts, each object should have one attribute that represents the x-axis value of that object, and all other attributes represent the values of different datasets at that x-axis value.
For pie charts, each object should only contain a single attribute, which indicates the value of one slice of the pie chart.
Below is an example of using the row-based data format:
tsx
Copied
1
<Chart
2
type="scatter"
3
data={[
4
{ x: 2, square: 4, cube: 8 },
5
{ x: 3, square: 9, cube: 27 },
6
{ x: 4, square: 16, cube: 64 },
7
]}
8
/>

Column-based data

A chart with column-based data expects an object containing multiple lists.
For scatter, bar, and line charts, one list is the x-axis values of data points and all other lists represent different datasets with those x-axis values.
For pie charts, the object should only contain a single list, which indicates the values of different slices of the pie chart.
In the example below, the x-axis is chosen to be age, and three different series of data indicating the weight of each cat at that age are provided, each as an array.

Task backed

A Chart can be backed by an Airplane Task rather than hardcoding the data. Set the task prop to call an Airplane task. The axes and data are automatically inferred from the output of the task, though you may still need to set the chart titles manually.

Customizing data

The output of a task can also be transformed using the outputTransform prop to an appropriate format.
In the example below, we create an additional dataset in the chart that represents the total weights of the cats at each age.

Using a subset of the data

A Chart can be restricted to a subset of the datasets provided by using the datasets prop (for line, scatter, and bar charts) or the dataset prop (for pie charts).
In the following example, the data originally contained weights for three different cats (Baosky, Hazel, and Peaches), but by setting the datasets prop (to ["Baosky", "Hazel"]), we can limit the chart to only show data for the two cats Baosky and Hazel.

Point selection

Individual data points in some types of charts can be selected by clicking on them. You can select individual points in scatter and line charts, and individual bars in bar charts. At the moment, selecting data from pie charts is not supported.
The currently selected points in a chart can be accessed via the selectedPoints prop in the component state.

Component API

NameDescriptionDefault
data
Record<string, Datum>[] | Record<string, Datum[]>
Data to render in the chart. Supports an array of objects: [{x: 0, y: 100}, {x: 1, y: 101}, ...] and also an object of arrays: {x: [0, 1], y: [100, 101]} Use `xAxis` and `datasets` to control which fields are rendered.
type
"line" | "scatter" | "bar" | "pie"
Type of chart.
id
string
The ID referenced by the global component state.
error
string
Renders an error message.
loading
boolean
Renders a loading indicator when true.
title
string
Title to show above the chart.
legendPosition
"hidden" | "left" | "right" | "top" | "bottom"
Position of the legend.
right
xAxis
string
Which field of `data` to use for the chart's x-axis.
First field found in `data`
datasets
string[]
Which fields of `data` to use in the chart. Each field is a separate series.
All fields in `data` aside from xAxis
colors
string[] | Record<string, string>
Override colors used to render datasets. If using a scatter, bar, or line chart, this should be a `Record<string, string>`, indicating the color of each dataset. If using a pie chart, this should be a `string[]`, indicating the color of each slice of the pie chart. Color can either be a built-in color: `"orange" | "yellow" | "lime" | "green" | "teal" | "cyan" | "blue" | "indigo" | "violet" | "grape" | "pink" | "red" | "gray" | "dark"` Or a custom CSS color: `"rgba(1, 2, 3, 0.5)" | "#efefef"`
xAxisTitle
string
Title for the x-axis.
xAxisFormat
string
Formatting for x-axis values. Uses d3-format for numerical values and d3-time-format for date values.
For example, use `.1%` to render `0.23` as `23%` or `%B %d, %Y` to render a date as `June 30, 2020`
xAxisType
"log" | "date" | "auto" | "linear" | "category" | "multicategory"
Type of x-axis.
auto
yAxisTitle
string
Title for the y-axis.
yAxisFormat
string
Formatting for y-axis values, similar to xAxisFormat. See xAxisFormat for details.
yAxisType
"log" | "date" | "auto" | "linear" | "category" | "multicategory"
Type of y-axis.
auto
width
SizingToken | "{number}px"
Defines the width of the component.
auto
height
SizingToken | "{number}px"
Defines the height of the component.
auto
grow
boolean
If true, the element will grow to fill available space. This prop works only if the element is a direct child of a Stack.
dataset
string
Which field of `data` to use in the pie chart.
First field found in `data`
labels
string[]
Labels for values in `data`.
task
string | AirplaneFunc | SlugQuery | FunctionQuery

The task query to execute when this component loads. The component's data will be populated by the task's output and loading and error states will be handled automatically.

If the task doesn't require any parameters or special options, you can just pass the task slug (task="my_task") or an AirplaneFunc—the return value of airplane.task() (task={myTask}).

If the task does require parameters or special options, pass the task as an object. If you are using a slug, specify the slug prop to pass the task configuration as a SlugQuery. If you are using an AirplaneFunc, specify the fn prop to pass the task configuration as a FunctionQuery.

SlugQuery
FunctionQuery

The refetchInterval prop represents how often (in milliseconds) the task query should be rerun to refetch data automatically.

The onSuccess and onError callbacks will run on task success or failure.

The executeOnMount, executeOnWindowFocus, and executeOnReconnect params control when the task is (re)run - on component mount, when the window is (re)focused, and if the network reconnects. All of these options are true by default.

outputTransform
(output: TOutput) => ChartData<Datum>
Callback to transform the task output.

State API

NameDescription
selectedPoints
Record<string, Datum>[]
Points that have been selected. Only applicable for scatter, line, and bar charts.
changeSelection
(points: Record<string, Datum>[]) => void
Changes the selected points in the chart.
clearSelection
() => void
Clears the current selection.