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.
tsx
Copied
1
<Chart
2
  type="scatter"
3
  title="Cat lengths and weights"
4
  xAxisTitle="Weight (pounds)"
5
  xAxis="weight"
6
  yAxisTitle="Length (inches)"
7
  data={[
8
    { weight: 8.1, length: 15 },
9
    { weight: 9.5, length: 13.7 },
10
    { weight: 10.2, length: 16.8 },
11
    { weight: 9.3, length: 15.3 },
12
    { weight: 9.4, length: 16.7 },
13
    { weight: 8.8, length: 14 },
14
  ]}
15
/>

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.
tsx
Copied
1
<Chart
2
  type="line"
3
  title="Cat weight by age"
4
  xAxisTitle="Age (months)"
5
  xAxis="age"
6
  yAxisTitle="Weight (pounds)"
7
  data={[
8
    { age: 3, Baosky: 5.2, Hazel: 5.4, Peaches: 6.1 },
9
    { age: 6, Baosky: 5.9, Hazel: 5.8, Peaches: 6.3 },
10
    { age: 9, Baosky: 7, Hazel: 6.6, Peaches: 6.8 },
11
    { age: 12, Baosky: 8.5, Hazel: 8.6, Peaches: 8.9 },
12
  ]}
13
/>

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.
tsx
Copied
1
<Chart
2
  type="bar"
3
  title="Cat weight by age"
4
  xAxisTitle="Age (months)"
5
  xAxis="age"
6
  yAxisTitle="Weight (pounds)"
7
  data={[
8
    { age: 3, Baosky: 5.2, Hazel: 5.4, Peaches: 6.1 },
9
    { age: 6, Baosky: 5.9, Hazel: 5.8, Peaches: 6.3 },
10
    { age: 9, Baosky: 7, Hazel: 6.6, Peaches: 6.8 },
11
    { age: 12, Baosky: 8.5, Hazel: 8.6, Peaches: 8.9 },
12
  ]}
13
/>

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.
tsx
Copied
1
<Chart
2
  type="pie"
3
  title="Cat food by week"
4
  labels={["Baosky", "Peaches", "Hazel"]}
5
  data={[{ food: 3.4 }, { food: 4.5 }, { food: 5.8 }]}
6
/>

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.
tsx
Copied
1
<Chart
2
  type="line"
3
  title="Cat weight by age"
4
  xAxisTitle="Age (months)"
5
  xAxis="age"
6
  yAxisTitle="Weight (pounds)"
7
  data={{
8
    age: [3, 6, 9, 12],
9
    Baosky: [5.2, 5.9, 7, 8.5],
10
    Hazel: [5.4, 5.8, 6.6, 6.8],
11
    Peaches: [6.1, 6.3, 6.8, 8.9],
12
  }}
13
/>

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.
tsx
Copied
1
<Chart type="line" task="get_cat_weights" />

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.
tsx
Copied
1
<Chart
2
  type="line"
3
  task="get_cat_weights"
4
  outputTransform={(data) => ({
5
    ...data,
6
    total: data.age.map(
7
      (age: number, idx: number) => data.Baosky[idx] + data.Hazel[idx] + data.Peaches[idx],
8
    ),
9
  })}
10
/>

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.
tsx
Copied
1
<Chart type="line" task="get_cat_weights" datasets={["Baosky", "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.
tsx
Copied
1
const chartState = useComponentState("catChart");
2
return (
3
  <>
4
    <Chart type="line" task="get_cat_weights" id="catChart" />
5
    <Text>{JSON.stringify(chartState.selectedPoints)}</Text>
6
  </>
7
);

Component API
colors
optional
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"`
data
REQUIRED
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.

dataset
optional
Default
First field found in `data`
string

Which field of data to use in the pie chart.

datasets
optional
Default
All fields in `data` aside from xAxis
string[]

Which fields of data to use in the chart. Each field is a separate series.

error
optional
string

Renders an error message.

grow
optional
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.

height
optional
Default
auto
SizingToken | "{number}px"
Defines the height of the component. See SizingToken docs for more details.
id
optional
string

The ID referenced by the global component state.

labels
optional
string[]

Labels for values in data.

legendPosition
optional
Default
right
"hidden" | "left" | "right" | "top" | "bottom"

Position of the legend.

loading
optional
boolean

Renders a loading indicator when true.

mode
optional
Default
group
"group" | "stack"

The variant of the bar graph.

outputTransform
optional
(output: TOutput) => ChartData<Datum>

Callback to transform the task output.

task
optional
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
title
optional
string

Title to show above the chart.

type
optional
"line" | "scatter" | "bar" | "pie"

Type of chart.

width
optional
Default
auto
SizingToken | "{number}px"
Defines the width of the component. See SizingToken docs for more details.
xAxis
optional
Default
First field found in `data`
string

Which field of data to use for the chart's x-axis.

xAxisFormat
optional
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`
xAxisRange
optional
[unknown, unknown] | "tozero"

A custom range for the x-axis from the first element to the second element. This can also be set to "tozero" which sets the start of the range to 0 and auto-calculates the end. If not set, the range is auto-calculated based on the extrema of the input data.

xAxisTitle
optional
string

Title for the x-axis.

xAxisType
optional
Default
auto
"log" | "date" | "auto" | "linear" | "category" | "multicategory"

Type of x-axis.

yAxisFormat
optional
string

Formatting for y-axis values, similar to xAxisFormat. See xAxisFormat for details.

yAxisRange
optional
[unknown, unknown] | "tozero"

A custom range for the y-axis from the first element to the second element. This can also be set to "tozero" which sets the start of the range to 0 and auto-calculates the end. If not set, the range is auto-calculated based on the extrema of the input data.

yAxisTitle
optional
string

Title for the y-axis.

yAxisType
optional
Default
auto
"log" | "date" | "auto" | "linear" | "category" | "multicategory"

Type of y-axis.

State API
changeSelection
optional
(points: Record<string, Datum>[]) => void

Changes the selected points in the chart.

clearSelection
optional
() => void

Clears the current selection.

selectedPoints
optional
Record<string, Datum>[]

Points that have been selected. Only applicable for scatter, line, and bar charts.

PrivacyTermsSupport