Plugins 〉Calendar Heatmap
Calendar Heatmap
Calendar Heatmap Panel
Turn raw time-series data into an instantly readable, GitHub-style activity calendar. Calendar Heatmap Panel makes trends, spikes, and gaps obvious at a glance—perfect for dashboards built for action.
Visual showcase
Why teams love it
- GitHub-style calendar visualization makes activity patterns immediately obvious.
- Six color schemes (Green, Blue, Red, Yellow, Purple, Orange) to match your brand or dashboard theme.
- Five aggregation methods (Sum, Count, Average, Max, Min) to capture the story behind your data.
- Auto-sizing cells with theme-aware rendering for beautiful, responsive dashboards.
- Interactive tooltips for fast, precise inspection of any day.
- Fully customizable layout with control over cell size, spacing, labels, and legends.
Quick start
- Install Calendar Heatmap Panel from the Grafana plugin catalog.
- Add the panel to any dashboard with time-series data.
- Choose an aggregation method and color scheme.
- Adjust cell size, spacing, labels, and legend to match your layout.
You’ll have a calendar-style heatmap in minutes—no custom code required.
Common use cases
- DevOps & SRE: visualize incident frequency, deploy cadence, and alert volume over time.
- Data Analysts: reveal seasonal trends, usage spikes, or churn patterns day by day.
- Business Users: highlight customer activity, revenue signals, or engagement streaks.
- Operations: track daily throughput, compliance checks, or support load.
Configuration highlights
- Color schemes: quickly switch between six curated palettes.
- Aggregation: summarize values as Sum, Count, Average, Max, or Min.
- Layout controls: tune cell size, spacing, and corner radius.
- Labels & legend: show week/month labels and legend for clarity.
- Tooltips: give viewers precise daily values on hover.
Support and links
- Source repository: https://github.com/tim0-12432/calendar-heatmap-panel
- Issues & feature requests: https://github.com/tim0-12432/calendar-heatmap-panel/issues
- Documentation: https://github.com/tim0-12432/calendar-heatmap-panel
Make your Grafana dashboards instantly understandable with a calendar heatmap designed for real-world operational insights.
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Installing Calendar Heatmap on Grafana Cloud:
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Warning
Plugin installation from this page will be removed in February 2026. Use the Plugin Catalog in your Grafana instance instead. Refer to Install a plugin in the Grafana documentation for more information.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Warning
Plugin installation from this page will be removed in February 2026. Use the Plugin Catalog in your Grafana instance instead. Refer to Install a plugin in the Grafana documentation for more information.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Warning
Plugin installation from this page will be removed in February 2026. Use the Plugin Catalog in your Grafana instance instead. Refer to Install a plugin in the Grafana documentation for more information.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Warning
Plugin installation from this page will be removed in February 2026. Use the Plugin Catalog in your Grafana instance instead. Refer to Install a plugin in the Grafana documentation for more information.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Warning
Plugin installation from this page will be removed in February 2026. Use the Plugin Catalog in your Grafana instance instead. Refer to Install a plugin in the Grafana documentation for more information.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Warning
Plugin installation from this page will be removed in February 2026. Use the Plugin Catalog in your Grafana instance instead. Refer to Install a plugin in the Grafana documentation for more information.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
For more information, visit the docs on plugin installation.
Installing on a local Grafana:
For local instances, plugins are installed and updated via a simple CLI command. Plugins are not updated automatically, however you will be notified when updates are available right within your Grafana.
1. Install the Panel
Use the grafana-cli tool to install Calendar Heatmap from the commandline:
grafana-cli plugins install The plugin will be installed into your grafana plugins directory; the default is /var/lib/grafana/plugins. More information on the cli tool.
Alternatively, you can manually download the .zip file for your architecture below and unpack it into your grafana plugins directory.
Alternatively, you can manually download the .zip file and unpack it into your grafana plugins directory.
2. Add the Panel to a Dashboard
Installed panels are available immediately in the Dashboards section in your Grafana main menu, and can be added like any other core panel in Grafana.
To see a list of installed panels, click the Plugins item in the main menu. Both core panels and installed panels will appear.
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
Unreleased
Added
- Nothing yet.
1.0.0 - 2026-01-17
Added
Core Features
- Calendar heatmap visualization with GitHub-style grid layout displaying activity patterns across a full year
- Real-time data updates based on Grafana time range picker with automatic refresh when time range changes
- Standard Grafana time-series data support (DataFrame) with automatic detection and processing of timestamp-value pairs
- GitHub contribution graph aesthetics with familiar visual patterns for developers and data analysts
Color Schemes
- 6 built-in color palettes: Green (GitHub-style), Blue (professional), Red (alerts/errors), Yellow (warnings), Purple (creative), Orange (energetic)
- Theme-aware empty cell colors that automatically adapt to Grafana's dark mode, light mode, and high-contrast themes
- Dynamic color scaling with 4 intensity levels providing clear visual distinction between low and high activity periods
- Customizable color intensity mapping with smart distribution algorithms for optimal visual contrast
Data Processing
- 5 aggregation methods for handling multiple data points per day:
- Sum: Total of all values (ideal for counts, quantities)
- Count: Number of data points (useful for frequency analysis)
- Average: Mean value (smooths out outliers)
- Maximum: Highest value (highlights peak activity)
- Minimum: Lowest value (identifies baseline activity)
- Intelligent data handling with automatic filtering of null, undefined, and NaN values to prevent visualization errors
- Automatic precision control with rounding to 2 decimal places for clean tooltip display
- Robust timestamp parsing supporting multiple date formats and timezone handling
Customization Options
- Auto-sizing cells that automatically adjust to fit panel width for optimal space utilization
- Manual cell size control with slider range from 8-20 pixels for fine-tuned appearance
- Configurable cell spacing from 1-24 pixels allowing tight or loose grid layouts
- Adjustable corner radius from 0-6 pixels for square to rounded cell appearance
- Optional week day labels (Sun-Sat) with abbreviated or full names
- Optional month labels (Jan-Dec) with intelligent positioning and responsive sizing
- Optional legend display with color intensity scale and value range indicators
User Interaction
- Interactive hover tooltips showing formatted date and aggregated value with customizable precision
- Toggle tooltip visibility for clean screenshots or presentation mode
- Responsive layout that gracefully adapts to various panel dimensions and screen sizes
- Smooth hover animations providing immediate visual feedback
- Accessibility support with proper ARIA labels and keyboard navigation
Technical Implementation
- React 18.3.0 with modern functional components, hooks, and concurrent features
- TypeScript 5.9.2 with strict type checking, ensuring type safety and better developer experience
- Grafana SDK 12.3.1 full compatibility with latest Grafana APIs:
@grafana/datafor DataFrame processing and time series handling@grafana/uifor consistent theme integration and UI components@grafana/runtimefor plugin lifecycle and configuration management@grafana/schemafor type-safe configuration options@grafana/i18nfor internationalization support
- @uiw/react-heat-map 2.3.3 for performant core heatmap visualization engine
- Emotion CSS 11.10.6 for dynamic styling with theme integration and CSS-in-JS benefits
Development Infrastructure
- Webpack 5 build system with modern module federation and tree-shaking optimizations
- SWC compilation for ultra-fast TypeScript/JavaScript transformation
- Jest 29 testing framework with React Testing Library for comprehensive unit test coverage
- Playwright 1.57 for end-to-end testing across multiple browsers and Grafana versions
- ESLint 9 with comprehensive rule sets:
- TypeScript-specific linting for type safety
- React hooks rules for proper hook usage
- JSDoc enforcement for better documentation
- Prettier 3 for consistent code formatting across the entire codebase
- Docker Compose development environment with Grafana Enterprise for realistic testing scenarios
- Plugin signing support for official Grafana plugin catalog distribution
- Automated build pipeline with version management and artifact generation
Plugin Configuration
- Grafana dependency: Compatible with Grafana >=11.6.0
- Plugin ID:
tim012432-calendarheatmap-panelfor unique identification - Plugin type: Panel plugin integrating seamlessly with Grafana's dashboard ecosystem
- Keywords: heatmap, calendar, github, contributions, activity for discoverability
Documentation & Assets
- Comprehensive screenshots demonstrating multiple themes and configurations:
- Light theme with orange color scheme
- Dark theme with green color scheme
- Tron theme with blue color scheme
- Configuration panel overview
- Plugin logo with SVG format for crisp display at any size
- GitHub repository integration with direct links to source code and issue tracking
Performance Optimizations
- Efficient data rendering with virtualized components for large datasets
- Optimized re-rendering using React.memo and useMemo for expensive calculations
- Lazy loading of non-critical components to improve initial load times
- Memory-efficient data structures preventing memory leaks in long-running dashboards
