ECharts Plugin System#

Apache Superset implements each ECharts chart type as a self-contained plugin in the plugin-chart-echarts package (~25 chart types). Every plugin follows the same structure, inherits from the ChartPlugin base class in @superset-ui/core, and is assembled into the Superset runtime by a single MainPreset class loaded at application startup.

Key source files:

• plugin-chart-echarts/src/index.ts — package public API; exports all plugin classes and transformProps functions
• src/visualizations/presets/MainPreset.js — the single place where every Superset chart type is registered
• packages/superset-ui-core/src/chart/models/ChartPlugin.ts — base ChartPlugin class
• packages/superset-ui-core/src/models/Preset.ts — Preset registration container

Plugin Anatomy#

Each chart type lives in its own subdirectory under plugin-chart-echarts/src/ and contains the same set of files. The Pie chart is the canonical reference:

The plugin class in index.ts extends EchartsChartPlugin 1, which itself extends the core ChartPlugin 2. The key difference: EchartsChartPlugin forces parseMethod: 'json-bigint' in the chart metadata to preserve numeric precision for large values.

A typical plugin constructor wires together the five pieces:

super({
  buildQuery,
  controlPanel,
  loadChart: () => import('./EchartsPie'), // lazy-loaded for code splitting
  metadata: { behaviors, category, name, thumbnail, ... },
  transformProps,
});

transformProps: Query Results → ECharts Options#

transformProps is the most important function in any ECharts plugin. It is typed as TransformProps<Props> 3 — it receives a ChartProps (width, height, form data, raw query data, hooks) and returns an object whose echartOptions field is passed directly to ECharts.

For the Pie chart 4, the function:

1. Extracts form data (color scheme, legend, donut mode, radii, label config) and raw query rows
2. Maps database rows to ECharts series data, applying the active color scheme, filter state (opacity), and optional "Other" grouping for small slices
3. Assembles the final ECharts config object: tooltip, legend, series, and optional center-label for donut totals
4. Returns the config alongside cross-filtering state (setDataMask, selectedValues, emitCrossFilters) and context-menu handlers

transformProps functions for all charts are re-exported from the package index, making them available for embedding or testing outside the full plugin stack.

Control Panels#

Each plugin's controlPanel.tsx exports a ControlPanelConfig that declares the chart's editor UI. Controls are organized into named sections of rows; each row is an array of control keys or inline control definitions. For example, the Pie control panel 5 has a Query section (groupby, metric, filters, row limit) and a Chart Options section (color scheme, label thresholds, rose type, donut mode, legend).

Controls support:

• Shared controls referenced by string key (e.g., 'color_scheme', 'groupby')
• Inline custom controls defined directly with name, config, and optional visibility callback for conditional display
• Shared section helpers (e.g., legendSection) imported from the package's shared utilities

The ChartPlugin registers the control panel config into a separate registry during plugin.register() 6, so the Explore view can dynamically render the correct controls for any chart type.

MainPreset and Plugin Registration#

MainPreset 7 extends the Preset class 8 and is the single place where all Superset chart types are wired into the runtime. It is instantiated and .register() is called at application startup.

The Preset.register() method 9 iterates its plugins and presets arrays and calls plugin.register() on each, which stores the plugin's metadata, component, control panel, transformProps, and buildQuery into five separate singleton registries. The Explore view, chart gallery, and rendering pipeline all read from these registries at runtime.

Notable patterns in MainPreset:

• ECharts plugins are imported from @superset-ui/plugin-chart-echarts and assigned a VizType key via .configure({ key: VizType.Pie }) . The VizType enum is the stable identifier used everywhere else (backend, URL params, Explore).
• Nested presets are supported: DeckGLChartPreset is passed in the presets array 11 and registered recursively.
• Feature-flag gating: BigNumberPeriodOverPeriodChartPlugin is only added when FeatureFlag.ChartPluginsExperimental is enabled 12. This pattern allows shipping unreleased chart types behind a flag.

Currently, MainPreset registers ~25 ECharts plugins alongside legacy NVD3, DeckGL, and other chart types 13. The complete ECharts export list is in plugin-chart-echarts/src/index.ts.

Adding a New ECharts Chart Type#

To add a new chart:

1. Create a directory under plugin-chart-echarts/src/<ChartName>/ with the standard files (index.ts, controlPanel.tsx, buildQuery.ts, transformProps.ts, Echart<Name>.tsx, types.ts).
2. Export the plugin class and transformProps from plugin-chart-echarts/src/index.ts.
3. Register in MainPreset.js by importing the plugin class and adding new Echart<Name>ChartPlugin().configure({ key: VizType.<Name> }) to the plugins array.
4. Add the VizType enum value in @superset-ui/core if it does not already exist.

For experimental charts, conditionally push the plugin into experimentalPlugins behind FeatureFlag.ChartPluginsExperimental 12 before including it in super({...}).