Apache Superset ships with more than fifty chart types, and for most dashboards that is plenty. Then someone asks for a bullet chart against a target band, a Sankey with a custom node order, a map layer the built-in deck.gl charts do not offer, or a KPI tile that colours itself against three thresholds instead of one. At that point you have two options: bend an existing chart until it almost fits, or write a plugin.
Plugins are how Superset itself is built. Every chart in the Explore view, from the humble table to the ECharts time series, is a plugin registered through the same ChartPlugin API you are about to use. Nothing about a custom plugin is second-class. It gets the same query layer, the same control panel framework, the same dashboard filters and cross-filters, and the same theming.
This guide builds a small but complete plugin for Superset 4.x. The chart is deliberately simple, a bar per category with a configurable highlight threshold, so that the plugin mechanics stay in focus. Swap the rendering for ECharts, D3, or deck.gl once the plumbing is in place.
<h2>What a plugin is made of</h2>
A Superset chart plugin is an npm package that exports a class extending ChartPlugin from @superset-ui/core. The class wires together five things:
<table>
<tbody>
<tr>
<td style="text-align: center;" width="192">Piece</td>
<td style="text-align: center;" width="192">File</td>
<td style="text-align: center;" width="192">Job</td>
</tr>
<tr>
<td width="192">Metadata</td>
<td width="192">index.ts</td>
<td width="192">Name, description, thumbnail, category, tags, and behaviours shown in the chart picker</td>
</tr>
<tr>
<td width="192">Query builder</td>
<td width="192">buildQuery.ts</td>
<td width="192">Turns the form data from the control panel into one or more query objects for Superset&#8217;s backend</td>
</tr>
<tr>
<td width="192">Control panel</td>
<td width="192">controlPanel.ts</td>
<td width="192">Declares which controls appear in Explore and how they are grouped</td>
</tr>
<tr>
<td width="192">Props transformer</td>
<td width="192">transformProps.ts</td>
<td width="192">Converts raw query results and form data into the props your component needs</td>
</tr>
<tr>
<td width="192">Component</td>
<td width="192">HelloChart.tsx</td>
<td width="192">The React component that draws the chart</td>
</tr>
</tbody>
</table>
The flow at runtime is: the user changes a control, Superset runs buildQuery, sends the query to the backend, receives rows, calls transformProps with those rows plus the form data, and renders your component with the result. Controls flagged as renderTrigger skip the query and go straight to transformProps, which is how colour and label changes stay instant.
<h3>Prerequisites</h3>
<ul>
<li>Node.js at the version pinned in superset-frontend/package.json for the Superset release you deploy. For the 4.x line that is Node 18. Use nvm or fnm; mismatched Node versions are the most common cause of a build that fails for no obvious reason.</li>
<li>A checkout of the Superset repository at the exact tag you run in production, for example git clone &#8211;branch 4.1.1 https://github.com/apache/superset.git. You will run the frontend dev server from it and, later, build the production image from it.</li>
<li>A running Superset backend to develop against. The repo&#8217;s docker-compose setup works, or a local superset run -p 8088 &#8211;with-threads &#8211;reload &#8211;debugger.</li>
<li>Working knowledge of React and TypeScript. Plugins are TypeScript by default and there is no reason to fight that.</li>
</ul>
<h2>Step 1: Scaffold the plugin</h2>
Superset maintains a Yeoman generator that produces a working plugin skeleton. Install it and run it in a new directory next to, not inside, your Superset checkout:
[bash] 
npm install -g yo @superset-ui/generator-superset
mkdir superset-plugin-chart-hello 
cd superset-plugin-chart-hello 
yo @superset-ui/superset
Answer the prompts: choose Chart plugin, accept the package name, add a one-line description, and pick Regular as the chart type (choose Time-series if your chart has a time axis; it changes the default controls). The generator writes a package.json, TypeScript config, Jest setup, a src/ folder with the five files above, and a src/images/thumbnail.png placeholder.
If the published generator lags behind the Superset version you are targeting, run it from your checkout instead:
[bash] 
cd superset/superset-frontend/packages/generator-superset 
npm install 
npm link 
cd ../../../../superset-plugin-chart-hello 
yo @superset-ui/superset
Open package.json and check the peerDependencies. The generator pins @superset-ui/core and @superset-ui/chart-controls to the versions in the checkout you ran it from. These must match the Superset you deploy, or the plugin will compile against one API and run against another.
<h2>Step 2: The five files</h2>
The generated code works as-is. The point of walking through each file is to know what to change when your chart needs something different.
<h3>index.ts: metadata and wiring</h3>
[typescript] 
import { t, ChartMetadata, ChartPlugin, Behavior } from &#8216;@superset-ui/core&#8217;; 
import buildQuery from &#8216;./buildQuery&#8217;; 
import controlPanel from &#8216;./controlPanel&#8217;; 
import transformProps from &#8216;./transformProps&#8217;; 
import thumbnail from &#8216;./images/thumbnail.png&#8217;;
export default class HelloChartPlugin extends ChartPlugin { 
constructor() { 
const metadata = new ChartMetadata({ 
name: t(&#8216;Hello Chart&#8217;), 
description: t(&#8216;One bar per category, with bars above a threshold highlighted.&#8217;), 
thumbnail, 
category: t(&#8216;Custom&#8217;), 
tags: [t(&#8216;Comparison&#8217;), t(&#8216;Custom&#8217;)], 
behaviors: [Behavior.InteractiveChart], 
});
super({ 
buildQuery, 
controlPanel, 
loadChart: () =&gt; import(&#8216;./HelloChart&#8217;), 
metadata, 
transformProps, 
}); 
} 
}
loadChart is a dynamic import so the component is code-split and only downloaded when someone opens a dashboard that uses it. Behavior.InteractiveChart tells Superset the chart can emit cross-filters; leave it out if it cannot. Wrap every user-visible string in t() so it goes through Superset&#8217;s translation layer.
<h3>buildQuery.ts: from form data to a query</h3>
[typescript] 
import { buildQueryContext, QueryFormData } from &#8216;@superset-ui/core&#8217;;
export default function buildQuery(formData: QueryFormData) { 
const { cols: groupby } = formData; 
return buildQueryContext(formData, baseQueryObject =&gt; [ 
{ 
&#8230;baseQueryObject, 
groupby, 
}, 
]); 
}
buildQueryContext assembles a query object from the standard controls (metrics, filters, row limit, time range) and hands it to your callback. You return an array of query objects; one is normal, two or more is how charts like the big number with trendline fetch both a total and a series. The generator names the group-by control cols and maps it onto the query&#8217;s groupby. Recent Superset versions also accept columns; either works on 4.x.
<h3>controlPanel.ts: what the user can change</h3>
[typescript] 
import { t, validateNonEmpty } from &#8216;@superset-ui/core&#8217;; 
import { 
ControlPanelConfig, 
sections, 
sharedControls, 
} from &#8216;@superset-ui/chart-controls&#8217;;
const config: ControlPanelConfig = { 
controlPanelSections: [ 
sections.legacyRegularTime, 
{ 
label: t(&#8216;Query&#8217;), 
expanded: true, 
controlSetRows: [ 
[ 
{ 
name: &#8216;cols&#8217;, 
config: { 
&#8230;sharedControls.groupby, 
label: t(&#8216;Category column&#8217;), 
description: t(&#8216;One bar per distinct value&#8217;), 
}, 
}, 
], 
[ 
{ 
name: &#8216;metrics&#8217;, 
config: { 
&#8230;sharedControls.metrics, 
validators: [validateNonEmpty], 
}, 
}, 
], 
[&#8216;adhoc_filters&#8217;], 
[&#8216;row_limit&#8217;], 
], 
}, 
{ 
label: t(&#8216;Hello Chart options&#8217;), 
expanded: true, 
controlSetRows: [ 
[ 
{ 
name: &#8216;threshold&#8217;, 
config: { 
type: &#8216;TextControl&#8217;, 
isInt: true, 
default: 0, 
renderTrigger: true, 
label: t(&#8216;Highlight threshold&#8217;), 
description: t(&#8216;Bars at or above this value are highlighted&#8217;), 
}, 
}, 
], 
[ 
{ 
name: &#8216;highlight_color&#8217;, 
config: { 
type: &#8216;ColorPickerControl&#8217;, 
default: { r: 26, g: 169, b: 202, a: 1 }, 
renderTrigger: true, 
label: t(&#8216;Highlight colour&#8217;), 
}, 
}, 
], 
], 
}, 
], 
};
export default config;
Two things to notice. First, sharedControls gives you the same metric, group-by and filter controls every built-in chart uses, so the Explore experience is consistent. Second, renderTrigger: true on the threshold and colour controls means changing them re-renders without re-querying the database. Anything that only affects drawing should be a render trigger; anything that changes what data comes back should not.
Control names are snake_case here. They arrive in transformProps as camelCase (highlight_color becomes highlightColor). This conversion is the single most common source of &#8220;my control value is undefined&#8221;.
<h3>transformProps.ts: shaping data for the component</h3>
[typescript] 
import { ChartProps, DataRecord } from &#8216;@superset-ui/core&#8217;;
export interface HelloChartProps { 
width: number; 
height: number; 
data: DataRecord[]; 
categoryColumn: string; 
metricLabel: string; 
threshold: number; 
highlightColor: string; 
}
export default function transformProps(chartProps: ChartProps): HelloChartProps { 
const { width, height, formData, queriesData } = chartProps; 
const { cols, metrics, threshold, highlightColor } = formData;
const data = (queriesData[0]?.data ?? []) as DataRecord[]; 
const metric = metrics?.[0]; 
const metricLabel = 
typeof metric === &#8216;string&#8217; ? metric : metric?.label ?? &#8216;value&#8217;; 
const rgba = highlightColor 
? `rgba(${highlightColor.r}, ${highlightColor.g}, ${highlightColor.b}, ${highlightColor.a})` 
: &#8216;#1aa9ca&#8217;;
return { 
width, 
height, 
data, 
categoryColumn: Array.isArray(cols) ? cols[0] : cols, 
metricLabel, 
threshold: Number(threshold) || 0, 
highlightColor: rgba, 
}; 
}
queriesData is an array with one entry per query object you returned from buildQuery. Each entry has a data array of row objects keyed by column or metric label. Metrics can be plain strings (saved metrics) or ad-hoc metric objects with a label; handle both. Keep this function pure and cheap; it runs on every render trigger.
<h3>HelloChart.tsx: the component</h3>
[tsx] 
import React from &#8216;react&#8217;; 
import { styled } from &#8216;@superset-ui/core&#8217;; 
import { HelloChartProps } from &#8216;./transformProps&#8217;;
const Wrapper = styled.div&lt;{ height: number; width: number }&gt;` 
height: ${({ height }) =&gt; height}px; 
width: ${({ width }) =&gt; width}px; 
display: flex; 
align-items: flex-end; 
gap: 6px; 
padding: 8px; 
font-family: ${({ theme }) =&gt; theme.typography.families.sansSerif}; 
`;
export default function HelloChart({ 
width, 
height, 
data, 
categoryColumn, 
metricLabel, 
threshold, 
highlightColor, 
}: HelloChartProps) { 
const max = Math.max(1, &#8230;data.map(row =&gt; Number(row[metricLabel]) || 0));
return (
{data.map(row =&gt; { 
const value = Number(row[metricLabel]) || 0; 
const pct = (value / max) * 100; 
const hot = value &gt;= threshold; 
return (
<div>
<div title="{&#96;${row[categoryColumn]}:"></div>
<div hidden="">{String(row[categoryColumn])}</div>
</div>
); 
})}
); 
}
This is plain HTML and CSS on purpose. It has no chart library dependency; it is trivially testable, and it demonstrates the two things every component must do: fill the width and height Superset gives it, and read its theme from @superset-ui/core rather than hard-coding fonts. For anything more demanding, look at how @superset-ui/plugin-chart-echarts wraps ECharts, or how the deck.gl plugins handle WebGL. The pattern is the same; only the drawing changes.
<h3>Step 3: Run it inside Superset</h3>
The plugin has to be part of the Superset frontend bundle. There is no runtime plugin loading. During development, link the package into the Superset frontend and register it:
[bash] 
cd superset/superset-frontend 
npm install -S ../../superset-plugin-chart-hello
Then open src/visualizations/presets/MainPreset.js and add the plugin alongside the built-ins:
[javascript] 
import HelloChartPlugin from &#8216;superset-plugin-chart-hello&#8217;;
// &#8230; inside the plugins array passed to super() 
new HelloChartPlugin().configure({ key: &#8216;hello_chart&#8217; }),
The key is the chart&#8217;s viz_type. It is stored on every saved chart that uses the plugin, so choose it once and never change it.
Start the backend on port 8088 and the frontend dev server:
[bash] 
# terminal 1, from the repo root with your virtualenv active 
superset run -p 8088 &#8211;with-threads &#8211;reload &#8211;debugger
# terminal 2 
cd superset-frontend 
npm run dev-server
Open http://localhost:9000, create a chart, and search for &#8220;Hello Chart&#8221; in the picker. Pick a dataset, a category column and a metric, and you should see bars. Change the threshold and watch the bars recolour without a spinner, which confirms the render trigger is wired correctly.
Edits to the plugin source are picked up by the dev server because the package is linked rather than copied. If the dev server does not notice a change, restart it; watching across a symlink is occasionally flaky on Windows and in Docker volumes.
<h2>Step 4: Getting it into production</h2>
Because the plugin is compiled into the bundle, production means building Superset&#8217;s frontend with your plugin included. The official apache/superset image does not contain the frontend source, so you build from the repository at the tag you deploy:
<ul>
<li>In your Superset checkout, add the plugin dependency to superset-frontend/package.json (a git URL or a private registry entry is cleaner than a relative path) and the registration line in MainPreset.js. Commit these on a branch named for the Superset version, for example, 4.1.1-acme.</li>
<li>Build the image from the repo root: docker build -t registry.example.com/superset:4.1.1-acme. The Dockerfile&#8217;s superset-node stage runs npm ci and npm run build, which now includes your plugin.</li>
<li>Deploy that image in place of the official one. Nothing else changes: same configuration, same metadata database, same Helm chart or compose file.</li>
</ul>
When you upgrade Superset, rebase the branch onto the new tag, bump the plugin&#8217;s @superset-ui/* peer dependencies to match, rebuild, and run the plugin&#8217;s tests. Budget half a day for a minor version and more for a major one; the ChartPlugin API is stable, but control-panel helpers and theme tokens do move.
<h2>Step 5: Tests worth writing</h2>
The generator sets up Jest. Three tests pay for themselves immediately:
<ul>
<li>transformProps with a realistic ChartProps fixture: assert the metric label resolution for both string and ad-hoc metrics, the camelCase control names, and the empty queriesData case.</li>
<li>buildQuery with sample form data: assert the query object contains the expected groupby and metrics, so a control rename does not silently produce an empty query.</li>
<li>The component with React Testing Library: render with three rows, assert three bars, and assert the highlighted count for a given threshold.</li>
</ul>
Superset&#8217;s frontend also has a Storybook (superset-frontend/storybook). Adding a story for your plugin gives designers and stakeholders a place to look at it without a running backend.
<h2>Pitfalls that cost time</h2>
<ul>
<li>Peer dependency drift. @superset-ui/core in your plugin must be the version the Superset frontend uses. Two copies of the library in one bundle produce baffling errors about themes or registries being undefined.</li>
<li>camelCase vs snake_case. Controls are defined in snake_case and read in camelCase. Log formData once in transformProps if a value is missing.</li>
<li>Forgetting renderTrigger. Every cosmetic control without it forces a database round trip.</li>
<li>Hard-coded colours and fonts. Read them from the theme so the chart looks right in a themed or white-labelled Superset.</li>
<li>Changing the viz_type key. Saved charts reference it. Renaming it orphans every chart built on the plugin.</li>
<li>Ignoring width and height. Superset tells your component its size. A chart that sizes itself overflows dashboard grid cells.</li>
<li>Forking Superset core. Put chart logic in the plugin package, not in the Superset repo. The only lines you should be maintaining in the fork are the dependency and the registration.</li>
</ul>
<h2>What we have built this way</h2>
The mechanics above are the same ones behind the plugins we have written up on this blog: a <a href="https://www.andolasoft.com/blog/dual-axis-line-chart-plugin-for-superset-4-unlock-dual-perspectives-in-dashboards" target="_blank" rel="noopener">dual-axis line chart for Superset 4</a> that plots two measures on independent axes and takes part in cross-filtering, and a <a href="https://www.andolasoft.com/blog/transforming-insights-with-intelligent-heatmaps-multi-threshold-coloring-comes-to-superset-4-1" target="_blank" rel="noopener">multi-threshold heatmap for Superset 4.1</a> that colours cells against several hard limits instead of one gradient. Both started as exactly the skeleton in this post.
If you have a chart in mind and want to know what it would take, our Plugin Scoping Call is a free 45-minute session with a plugin engineer. You describe the visualisation, we walk through the data shape and interactions, and within 48 hours you get a written scope, effort estimate, and timeline you can act on with or without us. The wider service is described on our <a href="https://www.andolasoft.com/what-we-do/superset-plugin-development" target="_blank" rel="noopener">Superset plugin development</a> page.

How to Build a Custom Chart Plugin for Apache Superset 4.x

Table of Contents

Related Articles

Quick Links

Products

For Career

For Sales