0
# Heatmap Visualization
1

2
Core D3.js-based heatmap visualization component that renders data as color-coded cells in a grid format with interactive features.
3

4
## Capabilities
5

6
### Heatmap Function (Internal)
7

8
Internal D3.js visualization function that renders the heatmap. This function is wrapped by the React component and used automatically by the plugin framework.
9

10
```javascript { .api }
11
/**
12
 * Internal function that renders a heatmap visualization in the specified DOM element
13
 * Used automatically by the ReactHeatmap component wrapper
14
 * @param element - DOM element to render the heatmap into
15
 * @param props - Configuration properties for the visualization
16
 */
17
function Heatmap(element: HTMLElement, props: HeatmapProps): void;
18
```
19

20
### Heatmap Props Interface
21

22
Complete configuration interface for the heatmap visualization.
23

24
```javascript { .api }
25
interface HeatmapProps {
26
  /** Data structure containing records and value bounds */
27
  data: {
28
    records: HeatmapRecord[];
29
    extents: [number, number];
30
  };
31
  /** Chart width in pixels */
32
  width: number;
33
  /** Chart height in pixels */  
34
  height: number;
35
  /** Bottom margin configuration (auto or pixel value) */
36
  bottomMargin: string | number;
37
  /** Canvas image rendering mode */
38
  canvasImageRendering: 'pixelated' | 'auto';
39
  /** Color scheme identifier */
40
  colorScheme: string;
41
  /** X-axis column name */
42
  columnX: string;
43
  /** Y-axis column name */
44
  columnY: string;
45
  /** Left margin configuration (auto or pixel value) */
46
  leftMargin: string | number;
47
  /** Metric configuration (string name or object) */
48
  metric: string | { label: string; [key: string]: any };
49
  /** Whether to use normalized values for coloring */
50
  normalized: boolean;
51
  /** Number format string for value display */
52
  numberFormat: string;
53
  /** Whether to show color legend */
54
  showLegend: boolean;
55
  /** Whether to show percentage in tooltips */
56
  showPercentage: boolean;
57
  /** Whether to show values inside cells */
58
  showValues: boolean;
59
  /** X-axis sorting method */
60
  sortXAxis: 'alpha_asc' | 'alpha_desc' | 'value_asc' | 'value_desc';
61
  /** Y-axis sorting method */
62
  sortYAxis: 'alpha_asc' | 'alpha_desc' | 'value_asc' | 'value_desc';
63
  /** X-axis scale interval for tick marks */
64
  xScaleInterval: number;
65
  /** Y-axis scale interval for tick marks */
66
  yScaleInterval: number;
67
  /** Value bounds for color scale [min, max] */
68
  yAxisBounds: [number | null, number | null];
69
}
70

71
interface HeatmapRecord {
72
  /** X-axis category value */
73
  x: string;
74
  /** Y-axis category value */
75
  y: string;
76
  /** Numeric value for the cell */
77
  v: number;
78
  /** Percentage value (0-1) */
79
  perc: number;
80
  /** Rank value for normalization (0-1) */
81
  rank: number;
82
}
83
```
84

85
### React Wrapper Component
86

87
Styled React component that wraps the D3 heatmap using the `reactify` pattern with emotion CSS-in-JS theming.
88

89
```javascript { .api }
90
/**
91
 * React wrapper component created using reactify pattern
92
 * Converts the D3 Heatmap function into a React component
93
 */
94
const ReactComponent = reactify(Component);
95

96
/**
97
 * Main React Heatmap component with styling and theming
98
 * @param props - React props including className and heatmap properties
99
 * @returns Styled React component with Global emotion styles
100
 */
101
function ReactHeatmap(props: ReactHeatmapProps): React.ReactElement;
102

103
interface ReactHeatmapProps extends HeatmapProps {
104
  /** CSS class name for styling */
105
  className?: string;
106
}
107
```
108

109
### PropTypes Definition
110

111
The D3 Heatmap component uses PropTypes for runtime type checking:
112

113
```javascript { .api }
114
const propTypes = {
115
  data: PropTypes.shape({
116
    records: PropTypes.arrayOf(
117
      PropTypes.shape({
118
        x: PropTypes.string,
119
        y: PropTypes.string,
120
        v: PropTypes.number,
121
        perc: PropTypes.number,
122
        rank: PropTypes.number,
123
      }),
124
    ),
125
    extents: PropTypes.arrayOf(PropTypes.number),
126
  }),
127
  width: PropTypes.number,
128
  height: PropTypes.number,
129
  bottomMargin: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
130
  colorScheme: PropTypes.string,
131
  columnX: PropTypes.string,
132
  columnY: PropTypes.string,
133
  leftMargin: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
134
  metric: PropTypes.oneOfType([PropTypes.string, PropTypes.object]),
135
  normalized: PropTypes.bool,
136
  numberFormat: PropTypes.string,
137
  showLegend: PropTypes.bool,
138
  showPercentage: PropTypes.bool,
139
  showValues: PropTypes.bool,
140
  sortXAxis: PropTypes.string,
141
  sortYAxis: PropTypes.string,
142
  xScaleInterval: PropTypes.number,
143
  yScaleInterval: PropTypes.number,
144
  yAxisBounds: PropTypes.arrayOf(PropTypes.number),
145
};
146
```
147

148
## Visualization Features
149

150
### Canvas Rendering
151

152
The heatmap uses HTML5 Canvas for efficient rendering of large datasets:
153

154
- **Pixel-Perfect Rendering**: Each data point maps to individual pixels
155
- **Color Interpolation**: Smooth color gradients based on data values
156
- **Performance Optimization**: Canvas rendering handles thousands of data points
157
- **Image Smoothing Control**: Configurable pixelated or smooth rendering
158

159
### Interactive Tooltips
160

161
Hover tooltips display detailed information for each cell:
162

163
- **Position-Aware**: Tooltips adjust position to stay within viewport
164
- **Rich Content**: Shows X/Y values, metric value, and optional percentage
165
- **Dynamic Visibility**: Tooltips hide over empty cells
166
- **Styled with Theme**: Uses Superset theme colors and typography
167

168
### Axis Management
169

170
Smart axis labeling with overflow handling:
171

172
- **Dynamic Margins**: Automatically adjusts margins based on label lengths
173
- **Label Rotation**: Rotates X-axis labels if they don't fit
174
- **Tick Intervals**: Configurable intervals to prevent overcrowding
175
- **Sorting Options**: Multiple sorting methods for both axes
176

177
### Color Legend
178

179
Optional color legend showing value-to-color mapping:
180

181
- **Scale Representation**: Shows color gradient with value markers
182
- **Formatted Values**: Uses configured number format for legend labels
183
- **Positioned Layout**: Automatically positioned to avoid overlap
184

185
## Usage Examples
186

187
### Basic Heatmap
188

189
```javascript
190
// Note: Heatmap function is not directly exported - it's used through ReactHeatmap
191
import ReactHeatmap from '@superset-ui/legacy-plugin-chart-heatmap';
192

193
const element = document.getElementById('heatmap-container');
194
const props = {
195
  data: {
196
    records: [
197
      { x: 'Product A', y: 'Region 1', v: 100, perc: 0.2, rank: 0.5 },
198
      { x: 'Product B', y: 'Region 2', v: 150, perc: 0.3, rank: 0.7 },
199
    ],
200
    extents: [0, 200]
201
  },
202
  width: 600,
203
  height: 400,
204
  colorScheme: 'schemeBlues',
205
  columnX: 'Product',
206
  columnY: 'Region',
207
  metric: 'Sales',
208
  showLegend: true,
209
  showValues: false,
210
  normalized: false,
211
  numberFormat: '.2f',
212
  sortXAxis: 'alpha_asc',
213
  sortYAxis: 'value_desc',
214
  xScaleInterval: 1,
215
  yScaleInterval: 1,
216
  leftMargin: 'auto',
217
  bottomMargin: 'auto',
218
  yAxisBounds: [null, null]
219
};
220

221
// For direct D3 usage, you would need to import the internal component
222
// This is not the recommended approach - use ReactHeatmap instead
223
```
224

225
### React Component Usage
226

227
```javascript
228
import ReactHeatmap from '@superset-ui/legacy-plugin-chart-heatmap';
229

230
function MyComponent() {
231
  return (
232
    <ReactHeatmap
233
      data={{
234
        records: [
235
          { x: 'Mon', y: 'Hour 9', v: 25, perc: 0.15, rank: 0.4 },
236
          { x: 'Tue', y: 'Hour 10', v: 40, perc: 0.25, rank: 0.6 },
237
        ],
238
        extents: [0, 100]
239
      }}
240
      width={800}
241
      height={600}
242
      colorScheme='schemeReds'
243
      columnX='Day'
244
      columnY='Time'
245
      metric='Activity'
246
      showLegend={true}
247
      showValues={true}
248
      showPercentage={true}
249
      normalized={false}
250
    />
251
  );
252
}
253
```
254

255
### Advanced Configuration
256

257
```javascript
258
// Complex heatmap with custom styling and normalization
259
const advancedProps = {
260
  data: correlationMatrix, // Large dataset
261
  width: 1000,
262
  height: 800,
263
  colorScheme: 'schemePiYG', // Diverging color scheme
264
  normalized: true, // Use rank-based coloring
265
  showLegend: true,
266
  showValues: false, // Too many cells for values
267
  showPercentage: true,
268
  leftMargin: 120, // Fixed margin for long labels
269
  bottomMargin: 80,
270
  xScaleInterval: 2, // Show every 2nd label
271
  yScaleInterval: 3, // Show every 3rd label
272
  sortXAxis: 'value_desc', // Sort by correlation strength
273
  sortYAxis: 'value_desc',
274
  yAxisBounds: [-1, 1], // Correlation bounds
275
  numberFormat: '.3f', // 3 decimal places
276
  canvasImageRendering: 'pixelated' // Sharp edges
277
};
278
```