Calendar Filter
An interactive, selectable calendar heatmap chart plugin for Apache Superset 6.1.0 — click dates to cross-filter your entire dashboard. Built from the ground up with TypeScript, React 17, and Emotion 11. Fully tested (27/27 tests passing).
2
Calendar views (Month + Year)
6
Color palettes
27
Tests — all passing
4
Test suites
About the Plugin
Calendar Filter is a custom visualization plugin for Apache Superset that renders an interactive calendar heatmap. Each day cell is color-coded by metric intensity, and every date is clickable — when you select dates, the plugin emits a cross-filter that propagates to all other charts on your dashboard via the __time_range column.
This project was born from a real need: Superset lacked a native calendar heatmap that could also serve as an intuitive date picker for dashboard filtering. The plugin implements the full Superset Chart Plugin API (ChartMetadata, ChartPlugin, buildQuery, controlPanel, transformProps) and follows the official Apache Superset viz plugin conventions. It was published on July 8, 2026.
Key Features
📆 Month View
Color-coded day cells show metric intensity at a glance. Navigate between months with ‹/› buttons, jump to any year via dropdown, or return to today with one click.
🗓️ Year Overview
See all 12 months as a 4×3 grid of interactive mini-calendars. Each mini-month is fully interactive — click any date to toggle selection directly from the overview.
🔗 Dashboard Cross-Filter
Select dates to automatically filter all other dashboard charts. Single-click toggles a date; Shift+click selects a contiguous date range. Emits __time_range IN [...] filters.
🎨 6 Color Palettes
Choose from Superset Default, Greens, Blues, Oranges, Reds, or Purples. Each palette offers 7 color stops from light to intense for optimal heatmap readability.
📊 Legend & Tooltips
Gradient legend bar shows min→max value range. Hover any cell to see date, raw metric value, and percentage of maximum in a rich tooltip overlay.
🔢 Week Numbers & Config
Optional ISO 8601 week numbers on each row. Configurable first day of week (Sunday/Monday). Year dropdown for quick navigation across data range.
Technical Architecture
📦 Plugin Registration
SupersetPluginChartCalendarFilter extends ChartPlugin with ChartMetadata providing name, description, and thumbnail. Lazy-loads the main component via loadChart: () => import('../CalendarFilter').
🔍 Query Builder
buildQuery.ts uses buildQueryContext from @superset-ui/core, passing the groupby (date column) through to the query object. Supports ad-hoc filters and metric aggregation.
⚙️ Control Panel
7 configurable controls: color_scheme (SelectControl, 6 palettes), show_legend, show_week_numbers, first_day_of_week, show_year_dropdown, enable_overview, plus time range, metric, groupby, and ad-hoc filters.
🔄 Data Pipeline
transformProps.ts extracts chart props (width, height, formData, queriesData) and maps Superset's TimeseriesDataRecord[] into the component interface with proper type coercion.
🧩 React Component
CalendarFilter.tsx (~900 lines) is a pure functional component using React hooks (useState, useMemo, useCallback, useRef). Styled via @emotion/styled with full Superset theme integration.
🗄️ TypeScript Types
types.ts defines 9 interfaces: CalendarFilterProps, CalendarDay, CalendarMonth, WeekRow, TooltipData, and more. Full integration with Superset's SetDataMaskHook, DataMask, and TimeseriesDataRecord.
Technology Stack
| Component | Technology | Version |
|---|---|---|
| Platform | Apache Superset | 6.1.0 |
| Language | TypeScript | 4.1 |
| UI Framework | React | 17.x |
| Styling | Emotion (styled) | 11.x |
| Superset SDK | @superset-ui/core + @superset-ui/chart-controls | 0.20.x |
| Build | Babel 7 + TypeScript compiler | — |
| Testing | Jest 29 + @testing-library/react | 29.x / 12.x |
| Module Formats | CommonJS (lib/) + ES Modules (esm/) | — |
| Linting | Babel plugin-transform-dev | — |
Cross-Filter API
When dates are selected, the plugin calls setDataMask() with the following payload:
setDataMask({
extraFormData: {
filters: [{ col: '__time_range', op: 'IN', val: ['2024-01-01', '2024-01-15'] }],
},
filterState: {
value: ['2024-01-01', '2024-01-15'],
selectedValues: { '2024-01-01': '2024-01-01', '2024-01-15': '2024-01-15' },
},
});
The __time_range column is automatically recognized by Superset's native time-range filter system, enabling seamless integration with existing dashboard charts.
Test Coverage
| Suite | File | Tests | Coverage |
|---|---|---|---|
| Component | test/CalendarFilter.test.tsx | 21 | Rendering, date selection, shift-click range, tooltips, navigation, year overview, empty state, color palettes |
| Plugin registration | test/index.test.ts | 1 | Plugin class instantiation and metadata |
| Build query | test/plugin/buildQuery.test.ts | 3 | Query context generation, groupby passthrough |
| Transform props | test/plugin/transformProps.test.ts | 2 | Data transformation, default values |
Installation Guide
1. Build the plugin
cd superset-plugin-chart-calendar-filter
npm install --legacy-peer-deps
npm run build
This produces lib/ (CommonJS) and esm/ (ES Modules) with TypeScript declarations, and runs the full test suite.
2. Link & Register
# From superset-frontend/:
npm i -S ../../superset-plugin-chart-calendar-filter
Then register in MainPreset.js and restart Superset. The Calendar Filter will appear in the chart picker.
Project Structure
superset-plugin-chart-calendar-filter/ ├── src/ │ ├── index.ts # Plugin entry point │ ├── CalendarFilter.tsx # Main React component (~900 lines) │ ├── types.ts # TypeScript interfaces (9 types) │ ├── images/thumbnail.png # Chart picker thumbnail │ └── plugin/ │ ├── index.ts # ChartPlugin registration │ ├── buildQuery.ts # Query builder │ ├── controlPanel.ts # 7 form controls │ └── transformProps.ts # Data transformation ├── test/ │ ├── CalendarFilter.test.tsx # 21 component tests │ ├── index.test.ts # 1 plugin test │ ├── __mocks__/ # Test mocks │ └── plugin/ # 5 unit tests ├── demo/ # Standalone demo ├── package.json ├── tsconfig.json ├── babel.config.js ├── jest.config.js └── AGENTS.md
Results
The plugin implements the complete Superset Chart Plugin contract: ChartMetadata → ChartPlugin → buildQuery → controlPanel → transformProps → React component. It supports lazy loading, TypeScript declarations, dual CommonJS/ESM module formats, and integrates with Superset's native cross-filter system via setDataMask.
Get the Plugin
The full source code is available on GitHub. Clone, build, and integrate into your Superset instance.