How to Create Custom Charts in Retool with Plotly

Drag a Chart component onto your canvas from the component panel. In the Inspector, set the Data source to {{ query1.data }}. By default, the chart shows in Series mode — Retool tries to auto-detect X and Y columns. Switch the X axis to a Date or category column and add one or more Y axis series pointing to numeric columns. For example, X: 'date', Y Series 1: 'revenue', Y Series 2: 'expenses'. Choose 'Line' as the chart type from the Type dropdown.

In the Chart Inspector, expand the Axes section to set axis labels, tick formats, and ranges. Set X axis title to 'Month' and Y axis title to 'USD ($)'. Under each series, set a custom Color (hex code) and Marker size. Enable Show legend to add a chart legend. For numeric Y axes, set Tick prefix to '$' or Tick format to ',.2f' for formatted numbers. These Inspector options cover ~80% of common chart customization needs without writing any JSON.

When your query returns data in a flat format (one row per measurement), you may need to pivot it for multi-series charts. Add a Transformer in the Code panel. The transformer receives your query results as the 'data' input and must return a reshaped array. Use JavaScript's reduce() to group by a category column, then produce separate arrays for each series. Reference the transformer output in the Chart component as {{ transformer1.value }}.

1// Transformer: pivotChartData
2// Input: data = [{ date: '2026-01', category: 'A', value: 100 }, ...]
3// Output: Plotly-compatible series arrays
4
5const grouped = data.reduce((acc, row) => {
6  if (!acc[row.category]) acc[row.category] = { x: [], y: [] };
7  acc[row.category].x.push(row.date);
8  acc[row.category].y.push(row.value);
9  return acc;
10}, {});
11
12// Return as Plotly traces array for Plotly JSON mode
13return Object.entries(grouped).map(([name, series]) => ({
14  name,
15  x: series.x,
16  y: series.y,
17  type: 'scatter',
18  mode: 'lines+markers',
19}));

In the Chart Inspector, toggle 'Plotly JSON' to ON. The Series UI is replaced by two fields: 'Data (JSON)' and 'Layout (JSON)'. Set Data (JSON) to {{ transformer1.value }} — this should be the Plotly traces array from the previous step. For the Layout (JSON), provide a JSON object controlling the chart's overall appearance. In Plotly JSON mode you have access to every Plotly.js chart type: 'candlestick', 'ohlc', 'waterfall', 'funnel', 'indicator' (gauge), 'heatmap', 'treemap', 'sunburst', and more.

1// Layout JSON object — paste into the Layout (JSON) field
2{
3  "title": { "text": "Monthly Revenue by Category" },
4  "font": { "family": "Inter, sans-serif", "size": 13 },
5  "plot_bgcolor": "rgba(0,0,0,0)",
6  "paper_bgcolor": "rgba(0,0,0,0)",
7  "xaxis": { "title": "Month", "showgrid": false },
8  "yaxis": { "title": "Revenue (USD)", "tickprefix": "$", "gridcolor": "#e5e7eb" },
9  "legend": { "orientation": "h", "y": -0.2 },
10  "margin": { "l": 60, "r": 20, "t": 50, "b": 60 }
11}

For KPI dashboards, a gauge chart is often more impactful than a line chart. In Plotly JSON mode, set Data (JSON) to a single-element array with type 'indicator'. Set the value from a query using {{ query1.data[0].score }}. Configure the gauge range and color thresholds in the gauge object. This creates a speedometer-style gauge that updates dynamically with your query data.

1// Gauge chart — Data (JSON) field
2[
3  {
4    "type": "indicator",
5    "mode": "gauge+number+delta",
6    "value": {{ query1.data[0].nps_score }},
7    "delta": { "reference": {{ query1.data[0].prev_nps_score }} },
8    "gauge": {
9      "axis": { "range": [0, 100] },
10      "steps": [
11        { "range": [0, 40], "color": "#fee2e2" },
12        { "range": [40, 70], "color": "#fef3c7" },
13        { "range": [70, 100], "color": "#d1fae5" }
14      ],
15      "threshold": {
16        "line": { "color": "#6366f1", "width": 4 },
17        "thickness": 0.75,
18        "value": 80
19      }
20    },
21    "title": { "text": "NPS Score" }
22  }
23]

The Chart component exposes a {{ chart1.selectedPoints }} property containing an array of the data points the user clicked on. Use this to build cross-filtering: when a user clicks a bar in a bar chart, filter a table to show only rows matching that category. Set the Table component's Data source to a transformer that filters based on {{ chart1.selectedPoints[0].x }} — the X value of the selected point. Add an event handler on the Chart component's 'Point click' event to trigger a filtered query.

1// Transformer: filterTableByChartSelection
2// Filters the full dataset to the selected chart category
3
4const selectedCategory = chart1.selectedPoints?.[0]?.x;
5
6if (!selectedCategory) {
7  return query1.data; // No selection — show all
8}
9
10return query1.data.filter(row => row.category === selectedCategory);