Skip to main content

​
Heatmap

The Heatmap component visualizes matrix data using color intensity, making it ideal for showing patterns, correlations, and distributions across two categorical dimensions.

​
Props

​
Data Props

​
data
Query | array
required
Query result or array of objects containing the data to visualize
​
x
string
required
Column name for x-axis categories
​
y
string
required
Column name for y-axis categories
​
value
string
required
Column name containing the numeric values to visualize as colors

​
Sorting Props

​
xSort
string
Column to sort x-axis by
​
xSortOrder
string
default:"asc"
Sort order for x-axis: ‘asc’ | ‘desc’
​
ySort
string
Column to sort y-axis by
​
ySortOrder
string
default:"asc"
Sort order for y-axis: ‘asc’ | ‘desc’

​
Formatting Props

​
valueFmt
string
Format string for cell values

​
Label Props

​
valueLabels
boolean
default:true
Show value labels in cells
​
mobileValueLabels
boolean
default:false
Show value labels on mobile devices

​
Chart Layout Props

​
title
string
Chart title displayed at the top
​
subtitle
string
Chart subtitle displayed below the title
​
chartAreaHeight
number
Height of the chart area in pixels
​
cellHeight
number
default:30
Height of each cell in pixels

​
Axis Props

​
xAxisPosition
string
default:"top"
Position of x-axis: ‘top’ | ‘bottom’
​
xTickMarks
boolean
default:false
Show tick marks on x-axis
​
yTickMarks
boolean
default:false
Show tick marks on y-axis
​
xLabelRotation
number
Rotation angle for x-axis labels in degrees

​
Visual Props

​
borders
boolean
default:true
Show borders around cells
​
legend
boolean
default:true
Show color legend
​
filter
boolean
default:false
Enable interactive filtering via the legend

​
Color Props

​
colorScale
string
Color scale name for the heatmap gradient
​
colorPalette
string
Deprecated: Use colorScale instead
​
min
number
Minimum value for color scale
​
max
number
Maximum value for color scale

​
Data Handling Props

​
nullsZero
boolean
default:true
Treat null/missing values as zero
​
zeroDisplay
string
default:"—"
Text to display for zero values

​
Advanced Props

​
echartsOptions
object
Custom ECharts configuration object
​
seriesOptions
object
Custom series configuration
​
printEchartsConfig
boolean
default:false
Print ECharts config to console
​
renderer
string
Renderer type: ‘canvas’ | ‘svg’
​
downloadableData
boolean
default:true
Enable data download
​
downloadableImage
boolean
default:true
Enable image download
​
connectGroup
string
Connect charts for synchronized interactions
​
emptySet
string
Empty data behavior: ‘pass’ | ‘warn’ | ‘error’
​
emptyMessage
string
Custom empty data message
​
leftPadding
number
default:0
Left padding for chart area
​
rightPadding
number
default:2
Right padding for chart area

​
Examples

​
Basic Heatmap

```sql sales_by_day_hour
select 
  day_of_week,
  hour_of_day,
  sum(sales) as total_sales
from orders
group by 1, 2


### Heatmap with Custom Colors

```markdown
<Heatmap 
  data={sales_by_day_hour} 
  x="hour_of_day" 
  y="day_of_week" 
  value="total_sales"
  title="Sales Heatmap by Day and Hour"
  colorScale="reds"
  valueFmt="usd0k"
/>

​
Sorted Heatmap

```sql correlation_matrix
select 
  metric_1,
  metric_2,
  correlation
from correlations


### Heatmap without Labels

```markdown
<Heatmap 
  data={sales_by_day_hour} 
  x="hour_of_day" 
  y="day_of_week" 
  value="total_sales"
  valueLabels="false"
  legend="true"
  filter="true"
/>

​
Custom Size and Styling

<Heatmap 
  data={sales_by_day_hour} 
  x="hour_of_day" 
  y="day_of_week" 
  value="total_sales"
  cellHeight=40
  borders="true"
  title="Hourly Sales Pattern"
  valueFmt="usd0"
  min=0
  max=10000
/>

​
Rotated Labels

<Heatmap 
  data={product_category_sales} 
  x="product_name" 
  y="category" 
  value="sales"
  xLabelRotation=45
  xAxisPosition="bottom"
  title="Product Sales by Category"
/>

Build docs developers (and LLMs) love

Get started for freeTalk to us