<article class="blog-post">Two different things get called a &#8220;Superset custom filter&#8221;, and they are built in completely different places.The first is a <strong>control</strong>: a widget in the Explore control panel that configures a single chart. Metrics, group-by, colour scheme, a threshold slider. Controls belong to the chart plugin and are declared in <code>controlPanel.ts</code>.</p>
<p>The second is a <strong>native filter</strong>: a widget in the dashboard filter bar that pushes a value into every chart in scope. Select, range, time range, time column. Native filters belong to the dashboard, not to any chart, and are implemented inside the Superset frontend.</p>
<p>There is a third thing that sits between them: a <strong>chart that acts as a filter</strong>, so that clicking a bar or a region filters the rest of the dashboard. That is cross-filtering, and it is something a plugin can do on its own.</p>
<p>This guide covers all three, in order of how much of Superset you have to touch. Most requirements are satisfied by the first, which needs no changes to Superset at all.</p>
<h2>Part 1: Custom controls inside a plugin</h2>
<p>A control panel is data, not code: a <code>ControlPanelConfig</code> object listing sections, each with rows of controls. Each control has a <code>type</code> naming a React component that Superset already ships, plus configuration. You can go a long way by composing those components well.</p>
<h3>The control types you already have</h3>
<p><code>@superset-ui/chart-controls</code> exposes the components Superset&#8217;s own charts use. The ones that cover most needs:</p>
<div class="table-responsive">
<table>
<thead>
<tr>
<th>type</th>
<th>What it renders</th>
<th>Typical use</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>SelectControl</code></td>
<td>Single or multi select, optionally free-form</td>
<td>Pick a column, a mode, an aggregation</td>
</tr>
<tr>
<td><code>TextControl</code></td>
<td>Text or number input</td>
<td>Thresholds, labels, limits</td>
</tr>
<tr>
<td><code>TextAreaControl</code></td>
<td>Multi-line text, optional code highlighting</td>
<td>Custom SQL, JSON, templates</td>
</tr>
<tr>
<td><code>CheckboxControl</code></td>
<td>Boolean toggle</td>
<td>Show legend, stack bars</td>
</tr>
<tr>
<td><code>SliderControl</code></td>
<td>Numeric slider</td>
<td>Opacity, radius, bucket count</td>
</tr>
<tr>
<td><code>RadioButtonControl</code></td>
<td>Mutually exclusive options</td>
<td>Chart orientation, sort order</td>
</tr>
<tr>
<td><code>ColorPickerControl</code></td>
<td>Single colour</td>
<td>Highlight colour</td>
</tr>
<tr>
<td><code>ColorSchemeControl</code></td>
<td>Registered categorical scheme</td>
<td>Series colours</td>
</tr>
<tr>
<td><code>BoundsControl</code></td>
<td>Min and max pair</td>
<td>Axis bounds</td>
</tr>
<tr>
<td><code>MetricsControl</code></td>
<td>Saved or ad-hoc metrics</td>
<td>Any measure</td>
</tr>
<tr>
<td><code>AdhocFilterControl</code></td>
<td>Filter builder</td>
<td>Where clauses</td>
</tr>
<tr>
<td><code>CollectionControl</code></td>
<td>Repeating group of sub-controls</td>
<td>Multiple thresholds, multiple series</td>
</tr>
</tbody>
</table>
</div>
<p>You reference them by string in the <code>type</code> field. The shared, pre-configured versions for metrics, group-by, filters and row limits live in <code>sharedControls</code>; spread one and override the label and description rather than configuring from scratch.</p>
<h3>Dynamic visibility</h3>
<p>Controls can appear and disappear based on other controls. The <code>visibility</code> function receives the current control state and returns a boolean:</p>
<div class="code-block">
<div class="code-header">typescript</div>
<pre><code class="language-typescript">[
  {
    name: 'threshold_mode',
    config: {
      type: 'RadioButtonControl',
      label: t('Threshold'),
      default: 'none',
      options: [
        ['none', t('None')],
        ['fixed', t('Fixed value')],
        ['percentile', t('Percentile')],
      ],
      renderTrigger: true,
    },
  },
],
[
  {
    name: 'threshold_value',
    config: {
      type: 'TextControl',
      label: t('Threshold value'),
      isFloat: true,
      default: 0,
      renderTrigger: true,
      visibility: ({ controls }) =&gt; controls?.threshold_mode?.value === 'fixed',
    },
  },
],
[
  {
    name: 'threshold_percentile',
    config: {
      type: 'SliderControl',
      label: t('Percentile'),
      min: 1,
      max: 99,
      default: 90,
      renderTrigger: true,
      visibility: ({ controls }) =&gt; controls?.threshold_mode?.value === 'percentile',
    },
  },
],</code></pre>
</div>
<p>This pattern replaces a great deal of what people initially think needs a custom component. A control panel that shows only the relevant options feels bespoke without being bespoke.</p>
<h3>Options that depend on the dataset</h3>
<p>Controls can derive their options from the dataset and the rest of the form through <code>mapStateToProps</code>. The canonical example is a select whose choices are the dataset&#8217;s columns filtered by type:</p>
<div class="code-block">
<div class="code-header">typescript</div>
<pre><code class="language-typescript">{
  name: 'geo_column',
  config: {
    type: 'SelectControl',
    label: t('Geometry column'),
    description: t('A column holding WKT or GeoJSON'),
    mapStateToProps: ({ datasource }) =&gt; ({
      choices: (datasource?.columns ?? [])
        .filter(col =&gt; /geom|geo|wkt|shape/i.test(col.column_name))
        .map(col =&gt; [col.column_name, col.verbose_name || col.column_name]),
    }),
    validators: [validateNonEmpty],
  },
}</code></pre>
</div>
<p><code>mapStateToProps</code> runs whenever the Explore state changes, so keep it cheap.</p>
<h3>Validation</h3>
<p><code>validators</code> is an array of functions that take the value and return an error string or nothing. <code>validateNonEmpty</code>, <code>validateInteger</code> and <code>validateNumber</code> are provided; writing your own is one function:</p>
<div class="code-block">
<div class="code-header">typescript</div>
<pre><code class="language-typescript">const validateRange = (value: unknown) =&gt; {
  const n = Number(value);
  return n &gt;= 0 &amp;&amp; n &lt;= 100 ? false : t('Must be between 0 and 100');
};</code></pre>
</div>
<p>Explore shows the error under the control and disables the Update button until it clears. That is a better experience than letting a bad value through and handling it in <code>transformProps</code>.</p>
<h3>Repeating groups</h3>
<p><code>CollectionControl</code> renders a list of sub-control groups the user can add to and remove from. It is how you get &#8220;add another threshold band&#8221; without writing a component. Each item is an object with the sub-control values, and it arrives in <code>transformProps</code> as an array.</p>
<p>If a requirement survives all of the above, you genuinely need a new component, and that means Part 3.</p>
<style>
.as-inline-cta{display:flex;align-items:stretch;border-radius:14px;overflow:hidden;<br />background:#eaf4f6;border:1px solid #dee7ea;margin:32px 0}<br />.as-inline-cta__icon{flex:0 0 128px;background-color:#1aa9ca;<br />background-image:radial-gradient(rgba(255,255,255,.35) 1.4px,transparent 1.4px);<br />background-size:11px 11px;display:flex;align-items:center;justify-content:center;padding:20px}<br />.as-inline-cta__icon span{width:64px;height:64px;border-radius:50%;background:#fff;<br />display:flex;align-items:center;justify-content:center;box-shadow:0 2px 6px rgba(0,0,0,.12)}<br />.as-inline-cta__icon svg{width:28px;height:28px;stroke:#0f7f9c;fill:none;stroke-width:2;<br />stroke-linecap:round;stroke-linejoin:round}<br />.as-inline-cta__body{padding:22px 28px;display:flex;flex-direction:column;justify-content:center;gap:8px}<br />.as-inline-cta__body h4{font-size:19px;font-weight:700;color:#1e2246;margin:0}<br />.as-inline-cta__body p{font-size:14.5px;line-height:1.6;color:#45506b;margin:0;max-width:52ch}<br />.as-inline-cta__link{display:inline-flex;align-items:center;gap:5px;font-size:14.5px;<br />font-weight:700;color:#0f7f9c;text-decoration:none;width:max-content}<br />.as-inline-cta__link svg{width:16px;height:16px;stroke:currentColor;fill:none;stroke-width:2.4;<br />stroke-linecap:round;stroke-linejoin:round}<br />.as-inline-cta__link:hover{text-decoration:underline}<br />@media (max-width:560px){.as-inline-cta{flex-direction:column}<br />.as-inline-cta__icon{flex:0 0 auto;width:100%;padding:16px 0}}<br /></style>
<div class="as-inline-cta">
<div class="as-inline-cta__icon"></div>
<div class="as-inline-cta__body">
<h4>Building this control for more than one dashboard?</h4>
<p>A one-off control panel is a weekend project; one that survives Superset upgrades and gets reused across dashboards is not. A Plugin Scoping Call scopes that difference before you commit engineering time.</p>
<p><a class="as-inline-cta__link" href="https://www.andolasoft.com/what-we-do/superset-plugin-scoping" target="_blank" rel="noopener">Book a Plugin Scoping Call</a></p>
</div>
</div>
<h2>Part 2: Making a chart act as a filter</h2>
<p>A chart that filters the dashboard when the user clicks it is the most requested &#8220;custom filter&#8221; and needs no changes to Superset. It needs three things in the plugin.</p>
<p>First, declare the behaviour in <code>index.ts</code>:</p>
<div class="code-block">
<div class="code-header">typescript</div>
<pre><code class="language-typescript">behaviors: [Behavior.InteractiveChart],</code></pre>
</div>
<p>Second, in <code>transformProps</code>, pass through the hooks Superset gives you:</p>
<div class="code-block">
<div class="code-header">typescript</div>
<pre><code class="language-typescript">const { hooks, filterState } = chartProps;
return {
  // ...other props
  setDataMask: hooks.setDataMask,
  selectedValues: filterState?.value ?? [],
  emitCrossFilters: formData.emitCrossFilters ?? false,
};</code></pre>
</div>
<p>Third, in the component, call <code>setDataMask</code> when the user selects something, and clear it when they deselect:</p>
<div class="code-block">
<div class="code-header">typescript</div>
<pre><code class="language-typescript">function handleSelect(column: string, value: string | number, currentlySelected: boolean) {
  if (!emitCrossFilters) return;
  if (currentlySelected) {
    setDataMask({ extraFormData: { filters: [] }, filterState: { value: null } });
    return;
  }
  setDataMask({
    extraFormData: {
      filters: [{ col: column, op: 'IN', val: [value] }],
    },
    filterState: { value: [value], selectedValues: [value] },
  });
}</code></pre>
</div>
<p><code>extraFormData.filters</code> is what other charts receive as an additional where clause. <code>filterState.value</code> is what Superset uses to remember the selection, show it in the filter indicator, and hand it back to you as <code>selectedValues</code> so you can highlight the selected element. Set both, always; setting one leaves the dashboard confused.</p>
<p>The <code>emitCrossFilters</code> form-data flag is set by the dashboard&#8217;s cross-filter toggle, so respect it. Users expect to be able to turn cross-filtering off per dashboard.</p>
<p>Test this on a dashboard with at least two charts, not in Explore. Cross-filters do not exist outside a dashboard, and the failure modes (stale data in other charts, a selection that will not clear) only appear there.</p>
<h2>Part 3: A genuinely new control type or native filter</h2>
<p>Sometimes the requirement is a widget Superset does not have: a hierarchical tree picker for an org structure, a map-drawn bounding box, a date range with fiscal-quarter presets, a filter fed by an external service. Superset&#8217;s plugin API does not let a chart plugin register new control component types or new native filter types. Both are registries populated inside the Superset frontend, so both require a change to your Superset fork.</p>
<p>That is not a reason to avoid it. It is a reason to do it in a way that keeps the fork thin.</p>
<h3>A new control component</h3>
<ul>
<li>Put the component in its own package, exactly as you would a chart plugin, so that it is versioned, tested and built independently. It receives <code>value</code>, <code>onChange</code>, and the config fields you declare, and it renders inside Explore&#8217;s control frame.</li>
<li>In the fork, register it in the control map. In 4.x that map lives in the Explore controls module (<code>superset-frontend/src/explore/components/controls/index.js</code>). One import and one entry:</li>
</ul>
<div class="code-block">
<div class="code-header">javascript</div>
<pre><code class="language-javascript">import OrgTreeControl from 'superset-control-org-tree';
// ...
const controlMap = {
  // existing controls
  OrgTreeControl,
};</code></pre>
</div>
<ul>
<li>Reference it from any plugin by <code>type: 'OrgTreeControl'</code>.</li>
</ul>
<p>Your fork diff is two lines. When Superset moves the control map, which it does occasionally, the rebase is a two-line conflict.</p>
<h3>A new native filter type</h3>
<p>Native filters are filter plugins in <code>superset-frontend/src/filters</code>, each with a control panel config, a <code>buildQuery</code> (for filters that need to fetch their own options) and a component that calls <code>setDataMask</code> just like a cross-filtering chart. Start by copying the select filter, which is the most complete example, and register the new plugin in the native filter preset alongside the built-ins.</p>
<p>The component contract is the same <code>setDataMask</code> call from Part 2. A native filter is, in effect, a chart that has no visualisation and lives in the filter bar. If you got a chart filtering the dashboard, you already know how to write one.</p>
<p>Keep the same discipline: the filter code in its own package, the registration in the fork.</p>
<h3>When to say no</h3>
<p>A new control or filter type is justified when the widget will be used across several charts or dashboards. For a one-off, restructure the requirement: a <code>SelectControl</code> with <code>mapStateToProps</code> and a <code>CollectionControl</code> cover more than people expect, and they upgrade for free.</p>
<h2>Frequently Asked Questions</h2>
<h3>Can I add a custom control to a Superset chart plugin without forking Superset?</h3>
<p>Yes, and that is the right default. A plugin&#8217;s control panel is built from the control types Superset already ships, and <code>mapStateToProps</code> gives them dataset-aware options, conditional visibility and validation. A separate plugin package survives upgrades; a fork turns every future Superset release into a merge.</p>
<h3>How do I make one chart filter another dashboard?</h3>
<p>Use cross-filters rather than building anything. A chart emits the clicked value as a filter that other charts on the dashboard respond to, which covers the majority of requests that arrive worded as &#8220;can this chart be a filter&#8221;. Reach for a custom native filter type only when the interaction genuinely cannot be expressed that way.</p>
<h3>When is a genuinely new control type justified?</h3>
<p>When the widget will be used across several charts or dashboards. For a one-off, restructure the requirement instead: <code>SelectControl</code> with <code>mapStateToProps</code> and <code>CollectionControl</code> cover more ground than people expect, and they inherit improvements from upstream for free. A bespoke control is a maintenance commitment at every upgrade.</p>
<h3>Where does control state live?</h3>
<p>In the form data that the control panel produces and <code>buildQuery</code> consumes, which is what makes a control&#8217;s value part of the saved chart and of the query it generates. Keeping state there, rather than in component-local state, is what lets a chart be saved, shared, embedded and rendered by the reports worker with the same result.</p>
<h2>Build It With Andolasoft</h2>
<p>Extending Superset beyond charts and filters follows the same rule of thin forks and separate packages. We wrote about that from a different angle in <a href="https://www.andolasoft.com/blog/how-to-add-collaboration-features-to-apache-superset" target="_blank" rel="noopener">adding collaboration features to Apache Superset</a>, and the mechanics of the plugin package itself are in the <a href="https://www.andolasoft.com/blog/how-to-build-a-custom-chart-plugin-for-apache-superset" target="_blank" rel="noopener">build guide</a>. The wider service is on the <a href="https://www.andolasoft.com/what-we-do/superset-plugin-development" target="_blank" rel="noopener">Superset plugin development</a> page.</p>
<p>If you are weighing a plugin-only approach against a fork for a specific requirement, that is exactly the question our <a href="https://www.andolasoft.com/what-we-do/superset-plugin-scoping" target="_blank" rel="noopener">Plugin Scoping Call</a> answers: free, 45 minutes, and you leave with a written recommendation and estimate. If you would rather describe the requirement first, <a href="https://www.andolasoft.com/contact-us" target="_blank" rel="noopener">talk to us</a>.</p>
</article>


Building a Custom Filter or Control-Panel Component for Apache Superset

Table of Contents

Related Articles

For Sales