syncfusion-javascript-heat-map

# Implementing Syncfusion HeatMap (TypeScript & JavaScript) The Syncfusion Essential JS 2 HeatMap visualizes two-dimensional data using color-coded cells. It is suitable for identifying patterns, trends, clusters, high values, low values, correlations, and density distributions across rows and columns. This skill covers: - TypeScript applications using npm and module imports. - JavaScript applications using versioned CDN or local global scripts. - Array and JSON data binding. - Category, Numeric, and DateTime axes. - Gradient and fixed color palettes. - Cell labels, borders, highlighting, and conditional styling. - Legends and tooltips. - Cell click and double-click events. - SVG and Canvas rendering. - Bubble HeatMaps. - Runtime data updates. - Responsive layouts. - Accessibility and performance guidance. - Export features when supported by the installed HeatMap version. ## Platform Support ### TypeScript Use TypeScript when the application uses: - The `@syncfusion/ej2-heatmap` npm package. - TypeScript compilation. - Webpack, Vite, or another module bundler. - Strongly typed component configuration. - Explicit feature-module injection. - IDE IntelliSense and compile-time validation. Install the package: ```bash npm install @syncfusion/ej2-heatmap ``` Basic import: ```typescript import { HeatMap } from '@syncfusion/ej2-heatmap'; ``` Import and inject only the feature modules used by the HeatMap. ```typescript import { HeatMap, Legend, Tooltip } from '@syncfusion/ej2-heatmap'; HeatMap.Inject( Legend, Tooltip ); ``` ### JavaScript Use global JavaScript when the application uses: - Versioned CDN scripts. - Locally stored EJ2 global scripts. - Traditional HTML and JavaScript files. - The global `ej` namespace. - No TypeScript compilation. The global HeatMap constructor is: ```javascript ej.heatmap.HeatMap ``` Global JavaScript examples should not call `HeatMap.Inject(...)`. ### JavaScript Language Level The JavaScript examples use ES5-compatible syntax where practical: ```text var declarations Traditional functions No optional chaining No object spread No JavaScript module imports ``` A modern browser is still recommended. ## When to Use This Skill Use this skill when the task requires: - Creating a basic HeatMap. - Visualizing matrix or correlation data. - Identifying hotspots and value patterns. - Displaying performance across two dimensions. - Binding a two-dimensional numeric array. - Binding sparse cell data. - Binding JSON table or cell data. - Loading HeatMap data from an API. - Updating HeatMap data dynamically. - Configuring Category, Numeric, or DateTime axes. - Formatting or rotating axis labels. - Applying gradient or fixed color palettes. - Displaying cell values. - Configuring legends and tooltips. - Handling cell click and double-click events. - Implementing selection when supported by the installed version. - Creating a Bubble HeatMap. - Selecting SVG or Canvas rendering. - Optimizing large matrices. - Creating responsive layouts. - Providing accessible descriptions and data alternatives. - Exporting the rendered HeatMap when supported by the installed version. ## Implementation Rules ### Rule 1: Provide Complete Examples A runnable TypeScript example should include: ```text Imports Required feature-module injection Data source HeatMap configuration HTML host element appendTo call Required CSS ``` A runnable JavaScript example should include: ```text All required global scripts HeatMap host element Data source HeatMap configuration appendTo call Required CSS ``` ### Rule 2: Use Explicit DOM Attachment Preferred TypeScript: ```typescript const heatmap: HeatMap = new HeatMap({ dataSource: [ [10, 20, 30], [40, 50, 60] ] }); heatmap.appendTo('#heatmap'); ``` Preferred JavaScript: ```javascript var heatmap = new ej.heatmap.HeatMap({ dataSource: [ [10, 20, 30], [40, 50, 60] ] }); heatmap.appendTo('#heatmap'); ``` Avoid passing the selector as the second constructor argument. ### Rule 3: Ensure the Host Exists Required HTML: ```html <div id="heatmap"></div> ``` Required attachment: ```typescript heatmap.appendTo('#heatmap'); ``` The host ID and selector must match. ### Rule 4: Inject Every Enabled TypeScript Feature Common feature-module mapping: ```text Legend -> Legend Tooltip -> Tooltip Data adaptor -> Adaptor ``` Example: ```typescript import { HeatMap, Legend, Tooltip, Adaptor } from '@syncfusion/ej2-heatmap'; HeatMap.Inject( Legend, Tooltip, Adaptor ); ``` Inject `Adaptor` only when adaptor-based data binding is used. Do not inject unused modules. ### Rule 5: Keep Imports and Injection Synchronized Incorrect: ```typescript import { HeatMap } from '@syncfusion/ej2-heatmap'; HeatMap.Inject( Legend ); ``` Correct: ```typescript import { HeatMap, Legend } from '@syncfusion/ej2-heatmap'; HeatMap.Inject( Legend ); ``` ### Rule 6: Do Not Inject Modules in Global JavaScript Avoid: ```javascript ej.heatmap.HeatMap.Inject( ej.heatmap.Legend, ej.heatmap.Tooltip ); ``` Use the global constructor directly: ```javascript var heatmap = new ej.heatmap.HeatMap({ legendSettings: { visible: true }, showTooltip: true }); heatmap.appendTo('#heatmap'); ``` ### Rule 7: Keep Matrix Dimensions Synchronized For this matrix: ```typescript const data: number[][] = [ [10, 20, 30], [40, 50, 60] ]; ``` use three X-axis labels: ```typescript xAxis: { labels: [ 'A', 'B', 'C' ] } ``` and two Y-axis labels: ```typescript yAxis: { labels: [ 'X', 'Y' ] } ``` Avoid inconsistent row lengths: ```typescript const invalidData = [ [10, 20, 30], [40, 50] ]; ``` ### Rule 8: Enable Tooltips Explicitly Import and inject `Tooltip`: ```typescript import { HeatMap, Tooltip } from '@syncfusion/ej2-heatmap'; HeatMap.Inject(Tooltip); ``` Enable the feature: ```typescript showTooltip: true ``` Use typed event arguments: ```typescript import { ITooltipEventArgs } from '@syncfusion/ej2-heatmap'; ``` Do not use: ```typescript tooltipSettings: { visible: true } ``` ### Rule 9: Use `dataSourceSettings` for JSON Mapping Do not place JSON field mappings directly on the HeatMap. Incorrect: ```typescript const heatmap: HeatMap = new HeatMap({ dataSource: cellData, xName: 'Month', yName: 'Product', valueName: 'Sales' }); ``` Correct: ```typescript const heatmap: HeatMap = new HeatMap({ dataSource: cellData, dataSourceSettings: { isJsonData: true, adaptorType: 'Cell', xDataMapping: 'Month', yDataMapping: 'Product', valueMapping: 'Sales' } }); ``` TypeScript also requires: ```typescript import { HeatMap, Adaptor } from '@syncfusion/ej2-heatmap'; HeatMap.Inject(Adaptor); ``` ### Rule 10: Use Supported Cell Properties Cell highlighting: ```typescript cellSettings: { enableCellHighlight: true } ``` Do not use: ```typescript enableCellHighlighting: true ``` Cell labels: ```typescript cellSettings: { showLabel: true, textStyle: { size: '12px', color: '#ffffff' } } ``` Cell border: ```typescript cellSettings: { border: { width: 1, color: '#ffffff', radius: 3 } } ``` ### Rule 11: Prefer Public Configuration Over Generated DOM Styling Do not depend on undocumented generated selectors: ```css .e-heatmap-cell { border-radius: 6px; } ``` Do not query assumed attributes: ```typescript document.querySelectorAll( '[data-row]' ); ``` Prefer public configuration: ```typescript cellSettings: { border: { radius: 6 } } ``` ### Rule 12: Use Strings for Component Dimensions Preferred: ```typescript width: '100%', height: '450px' ``` Runtime update: ```typescript heatmap.width = '100%'; heatmap.height = '450px'; ``` Avoid assigning numeric dimensions unless the installed API explicitly supports them. ### Rule 13: Do Not Use Encoded or Editor-Generated Code Executable HTML must use actual tags: ```html <div id="heatmap"></div> ``` Do not use: ```html &lt;div id="heatmap"&gt;&lt;/div&gt; ``` Do not place the following inside source code or CDN URLs: ```text <a> <strong> <br> data-lexical-text Editor-generated class names ``` ## Navigation Guide ### Getting Started Read: ```text references/getting-started.md ``` Use this reference for: - npm installation. - TypeScript imports. - JavaScript CDN setup. - Individual script dependencies. - Combined bundle setup. - HeatMap host creation. - Basic matrix binding. - Legend and tooltip injection. - Running the application. - Initialization troubleshooting. ### Data Binding Read: ```text references/data-binding.md ``` Use this reference for: - Array table binding. - Array cell binding. - JSON table binding. - JSON cell binding. - `Adaptor` injection. - `dataSourceSettings`. - External API loading. - API-response validation. - Real-time data updates. - Missing-value normalization. - Large-data considerations. ### Axes and Labels Read: ```text references/axes-and-labels.md ``` Use this reference for: - Category axes. - Numeric axes. - DateTime axes. - Axis labels. - Numeric ranges and intervals. - Date ranges and interval types. - Axis text styles. - Label formatting. - Label rotation. - Axis inversion. - Opposed positioning. - Axis titles. - RTL layout. ### Appearance and Styling Read: ```text references/appearance-styling.md ``` Use this reference for: - Cell borders and corner radius. - Cell highlighting. - Cell labels. - Conditional cell styling. - Gradient palettes. - Fixed palettes. - Domain-specific palettes. - HeatMap title styling. - Axis-label styling. - Background and margins. - Themes. - Responsive dimensions. - Resize handling. - Color and contrast guidance. ### Legend and Tooltip Read: ```text references/legend-tooltip.md ``` Use this reference for: - Legend module injection. - Legend visibility. - Legend positioning. - Legend labels. - Runtime legend toggling. - Tooltip module injection. - `showTooltip`. - `tooltipRender`. - Numeric formatting. - Conditional tooltip content. - Missing-value handling. - Tooltip performance guidance. ### Events and Interactions Read: ```text references/events-interactions.md ``` Use this reference for: - `cellClick`. - `cellDoubleClick`. - `cellRender`. - Cell selection state. - Cell highlighting. - Interaction details. - Drill-down navigation. - Custom range-selection state. - Comparison logic. - Event performance. - Safe DOM updates. - Accessible interaction alternatives. ### Advanced Features Read: ```text references/advanced-features.md ``` Use this reference for: - SVG rendering. - Canvas rendering. - Rendering-mode selection. - Bubble tile types. - Bubble size and color behavior. - Selection properties. - Clearing selection. - Export validation. - Large-matrix limits. - Efficient batch updates. - Server-side data windows. - API validation. - Resource cleanup. - Accessible descriptions. - Semantic data-table alternatives. - Keyboard-accessible external actions. - High-contrast presentation. ## TypeScript Quick Start ### Required HTML ```html <div class="heatmap-wrapper"> <div id="heatmap"></div> </div> ``` ### Required CSS ```css .heatmap-wrapper { width: 100%; max-width: 900px; margin: 0 auto; box-sizing: border-box; }