Skip to main content

Visualize data with the Chart component

Learn how to use your data to create charts and graphs.

The Chart component allows you to visualize data as graphs and charts. It's built using Plotly.js, so you can also customize charts to fit your needs.

Demo​

Check out the demo to see the Chart component in action.

Demo

Choose your data​

You can use queries and transformers, or JavaScript to build charts. You can reference an array or an object in the Data source field for a chart and Retool automatically detects the data type and transforms it for graphing. If your data source is an array and you enable Use JavaScript, Retool's built-in formatArrayAsObject function wraps the data source reference.

After you select a data source, Retool parses the data and populates the chart. By default, the first non-numeric column populates the X-axis but you can change this and other properties like Chart type, Group by, etc.

Choosing chart data

Supported data structures​

The Chart component requires data in a tabular format. This can either be an array of objects, where every object field is a column, or as an object where each key represents a column and the value is an array of values for that column.

Array of objects: typical data response from an API
[
  { "date": "2022-03-01", "animal": "dog", "count": 4 },
  { "date": "2022-03-01", "animal": "cat", "count": 6 },
  { "date": "2022-04-01", "animal": "frog", "count": 10 },
  { "date": "2022-04-01", "animal": "cat", "count": 3 },
  { "date": "2022-04-01", "animal": "dog", "count": 2 }
]
Object with array fields: typical data format returned by a SQL query
{
  "date": [
    "2022-03-01",
    "2022-03-01",
    "2022-04-01",
    "2022-04-01",
    "2022-04-01"
  ],
  "animal": ["dog", "cat", "frog", "cat", "dog"],
  "count": [4, 6, 10, 3, 2]
}

Group data​

One common use case is to chart time series data for a dynamic number of groups. For example, grouping revenue by product or headcount by team. Use the Group by property to choose a field from your data source to group and display this kind of data.

To see an example of this, create a JavaScript transformer using the code below. Make sure to save and run it before continuing.

const data = [
  { date: "2022-03-01", animal: "dog", count: 1 },
  { date: "2022-03-01", animal: "cat", count: 6 },
  { date: "2022-04-01", animal: "frog", count: 10 },
  { date: "2022-04-01", animal: "cat", count: 3 },
  { date: "2022-04-01", animal: "dog", count: 2 },
  { "date": "2022-03-01", "animal": "bird", "count": 4 },
  { "date": "2022-04-01", "animal": "bird", "count": 2 },
  { "date": "2022-03-01", "animal": "frog", "count": 6 },
  { date: "2022-05-01", animal: "dog", count: 7 },
  { date: "2022-05-01", animal: "cat", count: 4 },
  { date: "2022-05-01", animal: "frog", count: 1 },
  { "date": "2022-05-01", "animal": "bird", "count": 8 },
];

return data;

Add a Chart component to the Canvas and set its Data source to the transformer you created. Change the chart type to Line chart and set Group by to animal. The chart now shows the number of animals over time. If you add more data points to the transformer, the chart updates automatically.

Line chart showing the number of animals over time

Transformation types​

Retool supports two transformation types:

  • Group by: Group the data by a specific column.

  • Aggregation: Summarize the values for a group.

    You can use the following methods to aggregate data.

MethodDescription
countReturns the quantity of items for each group.
sumReturns the summation of all numeric values.
avgReturns the average of all numeric values.
medianReturns the median of all numeric values.
modeReturns the mode of all numeric values.
rmsReturns the rms of all numeric values.
stddevReturns the standard deviation of all numeric values.
minReturns the minimum numeric value for each group.
maxReturns the maximum numeric value for each group.
firstReturns the first numeric value for each group.
lastReturns the last numeric value for each group.

You can also edit the Plotly JSON for a Chart component directly to use the filter and sort transformation methods.

Customize the layout​

Edit the chart's layout using the Interaction section in the right panel. Select UI Form to edit these settings directly or Plotly JSON to configure the layout using Plotly layout JSON values.

Chart layout options

Axis tick formats​

Use the X-axis tick format and Y-axis tick format fields to customize tick labels using a valid d3-format specifier. For a full list of numerical values, use d3-format specifier. See d3-time-format for a list of date-time formatters and d3-format for a list of numerical formatters. Here are a few examples of commonly used formats.

SpecifierExampleDescription
%I:%M%p12:00 PMUses %I for 12-hour clock hour, %M for minute and %p for AM or PM.
Q%q %YQ2 2020Uses %q for quarter of the year and %Y for the year with century.
%Input: 0.05 Output: 5%% multiplies by 100, and then decimal notation with a percent sign.

Add interactivity​

When you select points on a chart, Retool exposes the underlying data in the .selectedPoints array property on the chart. This means you can filter, transform, or update your app by referencing the chart.selectedPoints array property in any component, query, or JavaScript function.

For example, to use the x values of selected points to filter a query, you can write {{ chart.selectedPoints.map(d => d.x) }}. Here is an example in a BigQuery SQL query:

BigQuery
SELECT id, event, timestamp, value, trigger
FROM big_query.event_table
WHERE timestamp IN UNNEST( {{chart.selectedPoints.map(d => d.x) }})

Advanced use cases​

Retool exposes chart information (chart type, aggregation methods, axes names, etc.) as JSON passed to the data and layout attributes. If you have an advanced use case, you can enable Plotly JSON to edit JSON directly.

Editing Plotly JSON

The Data field in Retool populates the Plotly data attribute. Use this attribute to define a list of traces (datasets) to chart. The schema of each trace is dependent on the type.

The Layout field in Retool populates the Plotly layout attribute. Use this attribute to control positioning and to set the title, axes, colors, and legend.

Visit the Plotly docs to read more about the data structure that the Plotly library operates on.

Common data options:

[
  {
    "name": "id",
    "x": ["2020-01-01","2020-01-02","2020-01-03","2020-01-04","2020-01-03"],
    "y": [4,8,3,12,7],
    "type": "bar",

    "marker": { // Used to customize how data points are displayed on chart.
      "color": "#3c92dc",
      "size": 3,
     "symbol": "circle"
    },
    "line": {  // Used to customize how data lines are drawn on chart.
      "color": "#3c92dc",
      "width": 3
    },
    "transforms": [
      {
        "type": "aggregate",
        "groups": ["2020-01-01","2020-01-02","2020-01-03","2020-01-04","2020-01-03"],
        "aggregations": [
          {
            "target": "y",
            "func": "sum",
            "enabled": true
          }
        ]
      }
    ]
  }, ...}
]

Common layout options:

{
  "title": "My Chart Title",
  "font": {
    "family": "Inter" // Default font for all chart labels.
  },
  "xaxis": {
    "title": "Date", // Text label for x-axis.
    "type": "-", // X-axis type.
    "tickformat": "YYYY-MM", // d3-format specifier. If empty or "", Plotly will attempt to guess format.
    "automargin": true,
    "fixedrange": true
  },
  "yaxis": {
    "title": "Count",
    "tickformat": "", // d3-format specifier. If empty or "" Plotly will attempt to guess format.
    "automargin": true,
    "fixedrange": true
  },
  "showlegend": true,
  "legend": {
    "xanchor": "left",
    "x": 1.05,
    "y": 0.5
  },
  "hovermode": "x unified",
  "margin": {
    "l": 75,
    "r": 25,
    "t": 80,
    "b": 75
  }
}

Add multiple y-axes​

If you're working on a chart that shows absolute numbers and percentages, you might want to show additional y-axes on your chart. For example, you could chart the total number of visits to a website, and the percentage of those visits split between new and existing users. The left y-axis would map to a count, and the right one would map to a percentage. You can do this by editing the Plotly JSON directly with the following steps.

1. Add another y-axis to the Plotly Layout JSON​

Select the chart and click Plotly JSON in the right panel. In the existing JSON, there's an entry for an existing y-axis with a "yaxis" key. Add a second entry named "yaxis2", and configure it to show up on the right side of the graph using side: right and overlaying: y.

y axis JSON
  "yaxis2": {
    "title": {
      "text": "an axis title",
      "standoff": 12,
      "font": {
        "size": 12
      }
    },
    "overlaying": "y",
    "side": "right",
    "type": "linear",
    "automargin": true,
    "fixedrange": true,
    "zerolinecolor": "#DEDEDE"
  }

You can also add some optional fields to format the axis as a percentage and restrict the range to [0,1].

"tickformat": "%",
"range": [0,1],

2. Assign datasets to the axes​

For each dataset that you want to assign to the additional y-axis, add this property:

"yaxis": "y2"

Chart with two y-axes

Additional resources​

Check out these external resources for more information on building charts and using Plotly.

Building an operations dashboard​

Customer case study with JetFuel​