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
number | "content" | "auto" | `${number}%` | `${number}/${number}` | { xs?: ColWidth; sm?: ColWidth; md?: ColWidth; lg?: ColWidth; xl?: ColWidth; }
Width of the component. This component must be a direct child of a <Stack> for this prop to take effect. If an integer is specified, signifies the width in a 12 item grid. 12 means that the component takes up the entire row, 6 is half, 1 is 1/12. If a decimal or fraction is specified, signifies the fractional share of the row. e.g. 1/2 takes up half of the row. If a percentage is specified, signifies the percentage share of the row. e.g. "50%" takes up half of the row. content indicates that the component should take up as much space as its content. auto indicates that the component should take any leftover space on the row. To set width based on the screen size, use an object with a specific width for each breakpoint. e.g. {xs: "100%", md: "50%"} sets the width on xs-md screens to 100% and md and larger screens to 50%.
content
offset
number | `${number}%` | `${number}/${number}` | { xs?: ColOffset; sm?: ColOffset; md?: ColOffset; lg?: ColOffset; xl?: ColOffset; }
Creates a gap to the left of the component. Has the same units as width. This component must be a direct child of a <Stack> for this prop to take effect. If an integer is specified, signifies the offset in a 12 item grid. 6 means the component is offset by half a row, 1 is 1/12 of a row. If a decimal or fraction is specified, signifies the fractional share of the row. e.g. 1/2 offsets a component by half of the row. If a percentage is specified, signifies the percentage share of the row. e.g. "50%" offsets a component by half of the row. To set offset based on the screen size, use an object with a specific offset for each breakpoint. e.g. {xs: "50%", md: "0%"} sets the offset on xs-md screens to 50% and md and larger screens to 0%.
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 | { slug: string; params?: Record<string, any>; executeOnMount?: boolean; executeOnWindowFocus?: boolean; executeOnReconnect?: boolean; enabled?: boolean; refetchInterval?: number; onSuccess?: (output?: TOutput) => void; onFailure?: (output?: TOutput, error?: TError) => void; }
The task query to execute when this component loads. The component's data will be populated by the task's output. If the task doesn't require any parameters or special options, you can just pass the task slug as a string. Otherwise, create an object with the given params, and set slug to the task slug.
If the task requires parameters, these can be passed in via params.
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.
The enabled param can be set to false to disable running the task query automatically.
The refetchInterval param represents how often (in milliseconds) the task query should be rerun to refetch data automatically. By default, the task will not automatically refetch data on a millisecond timer (though it may still refetch data on window refocus or network reconnect).
The onSuccess and onFailure callbacks will run on task success or failure. Note that depending on execute or refetch settings, task queries may be run repeatedly, which can trigger these callbacks multiple times.
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.