Skip to main content

Heatmap

<Heatmap 
data={orders}
x=day
y=category
value=order_count
valueFmt=usd
/>

Data Structure

Heatmap requires your data to contain 2 categorical columns (1 for the x-axis and 1 for the y-axis) and 1 numeric column.

Example

regionproductsales
WestA120
WestB200
WestC150
EastA110
EastB315
EastC450

Unpivoting your Data

If you have data spread across columns, you can use the UNPIVOT feature in your SQL query to prepare the data for the heatmap.

Example

If you have a query result called region_sales:

regionabc
West120200150
East110315450

You can use UNPIVOT like so:

UNPIVOT ${region_sales}
on COLUMNS(* EXCLUDE(region))
INTO
NAME product
VALUE sales

Which will return this table, which can be passed into the Heatmap:

regionproductsales
WestA120
WestB200
WestC150
EastA110
EastB315
EastC450
Note on Date Columns

Heatmap currently only works with string columns. If you would like to use a date column, cast it to a string in your SQL query before passing it into the Heatmap

Examples

Basic Heatmap

<Heatmap 
data={orders}
x=day
y=category
value=order_count
valueFmt=usd
/>

Custom Color Palette

<Heatmap 
data={orders}
x=day
y=category
value=order_count
colorPalette={['white', 'green']}
title="Weekday Orders"
subtitle="By Category"
/>

Rotated Labels

<Heatmap 
data={item_state}
x=item
y=state
value=orders
xLabelRotation=-45
colorPalette={['white', 'maroon']}
title="Item Sales"
subtitle="By State"
rightPadding=40
cellHeight=25
/>

Options

Data

Name Description Required? Options Default
data Query name, wrapped in curly braces Yes query name -
x Categorical column to use for the x-axis. If you want to use dates, cast them to strings in your query first Yes column name -
y Categorical column to use for the y-axis. If you want to use dates, cast them to strings in your query first Yes column name -
value Numeric column to use for the y-axis Yes column name -
min Minimum number for the heatmap's color scale - number min of value column
max Maximum number for the heatmap's color scale - number max of value column
emptySet Sets behaviour for empty datasets. Can throw an error, a warning, or allow empty. When set to 'error', empty datasets will block builds in build:strict. Note this only applies to initial page load - empty datasets caused by input component changes (dropdowns, etc.) are allowed. - error | warn | pass error
emptyMessage Text to display when an empty dataset is received - only applies when emptySet is 'warn' or 'pass', or when the empty dataset is a result of an input component change (dropdowns, etc.). - string No records

Formatting & Styling

Name Description Required? Options Default
colorPalette Array of colors to form the gradient for the heatmap. Remember to wrap your array in curly braces. - array of color codes - e.g., colorPalette={['navy', 'white', '#c9c9c9']} -
valueFmt Format to use for value column (see available formats) - Excel-style format | built-in format name | custom format name -
cellHeight Number representing the height of cells in the heatmap - number 30
leftPadding Number representing the padding (whitespace) on the left side of the chart. Useful to avoid labels getting cut off - number 0
rightPadding Number representing the padding (whitespace) on the left side of the chart. Useful to avoid labels getting cut off - number 0
valueLabels Turn on or off value labels in the heatmap cells - true | false true
mobileValueLabels Turn on or off value labels in the heatmap cells when app is viewed on a mobile device screen size - true | false false
borders Turn on or off borders around cells. Default is to show light grey border around each cell. To customize border appearance, use echartsOptions - true | false true

Axes

Name Description Required? Options Default
xTickMarks Turns on/off tick marks for the x-axis labels - true | false false
yTickMarks Turns on/off tick marks for the y-axis labels - true | false false
xLabelRotation Degrees to rotate the labels on the x-axis. Can be negative number to reverse direction. 45 and -45 are common options - number 0
xAxisPosition Position of x-axis and labels. Can be top or bottom. top recommended for longer charts - top | bottom top

Chart

Name Description Required? Options Default
title Chart title. Appears at top left of chart. - string -
subtitle Chart subtitle. Appears just under title. - string -
chartAreaHeight Minimum height of the chart area (excl. header and footer) in pixels. Adjusting the height affects all viewport sizes and may impact the mobile UX. - number auto set based on y-axis values
legend Turn on or off the legend - true | false true
filter Allow draggable filtering on the legend. Must be used with legend=true - true | false false
renderer Which chart renderer type (canvas or SVG) to use. See ECharts' documentation on renderers: https://echarts.apache.org/handbook/en/best-practices/canvas-vs-svg/ - canvas | svg canvas

Custom Echarts Options

Name Description Required? Options Default
echartsOptions Custom Echarts options to override the default options. See reference page for available options. - {{exampleOption:'exampleValue'}} -
seriesOptions Custom Echarts options to override the default options for all series in the chart. This loops through the series to apply the settings rather than having to specify every series manually using echartsOptions See reference page for available options. - {{exampleSeriesOption:'exampleValue'}} -
printEchartsConfig Helper prop for custom chart development - inserts a code block with the current echarts config onto the page so you can see the options used and debug your custom options - true | false false