Heatmap
- Recommended field configuration: 1 measure, 2 dimensions
- Supports data reshaping: at least 1 measure, 0 dimensions
The heatmap supports the following visual channels:
xAxis : x-axis channel, supports multiple dimensions, maps dimension values to the x-axis
yAxis : y-axis channel, supports multiple dimensions, maps dimension values to the y-axis
detail : detail channel, supports multiple dimensions, used to display finer-grained data within the same color series
color : color channel, supports one measure, maps measure values to color
tooltip: tooltip channel, supports multiple dimensions and multiple measures, displayed when hovering over a data point
label : label channel, supports multiple dimensions and multiple measures, displays data labels on data points
Heatmap, showing data distribution and intensity through color depth in a two-dimensional matrix.
Applicable scenarios:
- Density and intensity display for large-scale two-dimensional data
- Correlation analysis between categories and numeric values
- Cross-comparison between time series and categories
Data requirements:
- At least 2 dimension fields, used to determine the rows and columns of the heatmap
- At least 1 numeric field (measure), used to map color depth
- When multiple measures are supported, one measure is usually selected for color mapping
Features enabled by default:
- Legend, axes, data labels, tooltips, and numeric scaling are enabled by default
chartType
Type: "heatmap"
Heatmap
Heatmap, showing data distribution and intensity through color depth in a two-dimensional matrix.
Example 'heatmap'
dataset
Type: Record[]
Dataset
A TidyData-compliant, already aggregated dataset used to define the chart data source and structure. User input does not need any preprocessing; VSeed has powerful data reshaping capabilities and reshapes the data automatically. Heatmap data is ultimately converted into 2 dimensions and 1 measure.
Example [{month:'Jan', value:100}, {month:'Feb', value:150}, {month:'Mar', value:120}]
dimensions
Type: HeatmapDimension[] | undefined
Dimensions
For heatmaps, the first dimension is mapped to the angle axis, while the remaining dimensions are merged with measure names when multiple measures exist and displayed as legend items.
Example [{id: 'category', alias: 'Category'}]
id
Type: string
Field ID corresponding to the dimension
alias
Type: string | undefined
Dimension alias
timeFormat
Type: TimeFormat | undefined
Dimension date format configuration
type
Type: "year" | "quarter" | "month" | "week" | "day" | "hour" | "minute" | "second"
Time granularity, determines the date display precision
encoding
Type: "xAxis" | "tooltip" | "label" | "row" | "column" | "yAxis" | undefined
Channel to which the dimension is mapped
- xAxis: supports mapping multiple dimensions to the x-axis
- yAxis: supports mapping multiple dimensions to the Y-axis
- tooltip: supports mapping multiple dimensions to the tooltip channel
- label: supports mapping multiple dimensions to the label channel
- row: supports mapping multiple dimensions to the row channel
- column: supports mapping multiple dimensions to the column channel
measures
Type: HeatmapMeasure[] | undefined
Measures
Heatmap measures are automatically merged into one measure and mapped to the radius axis. When multiple measures exist, measure names are merged with the remaining dimensions and displayed as legend items.
Example [{id: 'value', alias: 'Value'}]
id
Type: string
Measure ID, must be unique
alias
Type: string | undefined
Measure alias, duplicates allowed; when not set, alias defaults to id
autoFormat
Type: boolean | undefined
Automatic number formatting, enabled by default, highest priority
When autoFormat=true, it overrides all numFormat configurations
When enabled, chart data labels and tooltips will automatically select the appropriate formatting based on measure values and locale
Formatting rules: decimal numbers with compact notation enabled, minimum 0 decimal places, maximum 2 decimal places, automatic rounding, using the browser's Intl.NumberFormat implementation
For example:
- locale=zh-CN: 749740.264 → 74.45万
- locale=en-US: 749740.264 → 744.5K
numFormat
Type: NumFormat | undefined
Custom number formatting for measures; automatically applied to labels and tooltips
Note: To use custom formatting, you must explicitly set autoFormat=false; otherwise autoFormat will override this config
type
Type: "number" | "percent" | "permille" | "scientific" | undefined
Number format type, supports: number (decimal), percent (%), permille (‰), scientific notation
ratio
Type: number | undefined
Number format ratio, cannot be 0
Example - 100000 converts to 10万, ratio:10000, symbol:"万" - 100000 converts to 10K, ratio:1000, symbol:"K"
symbol
Type: string | undefined
Number format symbol, e.g. %, ‰
Example - 100000 converts to 10万, ratio:10000, symbol:"万" - 100000 converts to 10K, ratio:1000, symbol:"K"
thousandSeparator
Type: boolean | undefined
Thousands separator for number formatting
suffix
Type: string | undefined
Number format suffix
prefix
Type: string | undefined
Number format prefix
fractionDigits
Type: number | undefined
Decimal places for number formatting, using the browser's Intl.NumberFormat minimumFractionDigits and maximumFractionDigits; lower priority than significantDigits
Example - 1234.5678 converts to 1235, fractionDigits:0 (roundingMode:halfCeil) - 1234.5678 converts to 1234.6, fractionDigits:1 (roundingMode:halfCeil) - 1234.5678 converts to 1234.57, fractionDigits:2 (roundingMode:halfCeil) - 1234.5678 converts to 1230.568, fractionDigits:3 (roundingMode:halfCeil) - 1234.5678 converts to 1234.5678, fractionDigits:4 (roundingMode:halfCeil) - 1234.5678 converts to 1234.56780, fractionDigits:5 (roundingMode:halfCeil)
significantDigits
Type: number | undefined
Significant digits for number formatting, using the browser's Intl.NumberFormat minimumSignificantDigits and maximumSignificantDigits; higher priority than fractionDigits
Example - 1234.5678 converts to 1000, significantDigits:1 - 1234.5678 converts to 1200, significantDigits:2 - 1234.5678 converts to 1230, significantDigits:3 - 1234.5678 converts to 1234, significantDigits:4 - 1234.5678 converts to 1234.6, significantDigits:5 (roundingMode:halfCeil) - 1234.5678 converts to 1234.57, significantDigits:6 (roundingMode:halfCeil) - 1234.5678 converts to 1234.568, significantDigits:7 (roundingMode:halfCeil) - 1234.5678 converts to 1234.5678, significantDigits:8 (roundingMode:halfCeil)
roundingPriority
Type: "morePrecision" | "lessPrecision" | undefined
Rounding priority for number formatting when both significantDigits and fractionDigits are set; uses the browser's Intl.NumberFormat, following the same rules as Intl.NumberFormat's roundingPriority
Example - 1234.5678 converts to 1230, significantDigits:3 (roundingPriority:lessPrecision) - 1234.5678 converts to 1234.5678, significantDigits:3 (roundingPriority:morePrecision)
roundingMode
Type: "floor" | "ceil" | "expand" | "trunc" | "halfCeil" | "halfFloor" | "halfExpand" | "halfTrunc" | "halfEven" | undefined
Rounding mode for number formatting, using the browser's Intl.NumberFormat, following the same rules as Intl.NumberFormat's roundingMode
format
Type: NumFormat | undefined
type
Type: "number" | "percent" | "permille" | "scientific" | undefined
Number format type, supports: number (decimal), percent (%), permille (‰), scientific notation
ratio
Type: number | undefined
Number format ratio, cannot be 0
Example - 100000 converts to 10万, ratio:10000, symbol:"万" - 100000 converts to 10K, ratio:1000, symbol:"K"
symbol
Type: string | undefined
Number format symbol, e.g. %, ‰
Example - 100000 converts to 10万, ratio:10000, symbol:"万" - 100000 converts to 10K, ratio:1000, symbol:"K"
thousandSeparator
Type: boolean | undefined
Thousands separator for number formatting
suffix
Type: string | undefined
Number format suffix
prefix
Type: string | undefined
Number format prefix
fractionDigits
Type: number | undefined
Decimal places for number formatting, using the browser's Intl.NumberFormat minimumFractionDigits and maximumFractionDigits; lower priority than significantDigits
Example - 1234.5678 converts to 1235, fractionDigits:0 (roundingMode:halfCeil) - 1234.5678 converts to 1234.6, fractionDigits:1 (roundingMode:halfCeil) - 1234.5678 converts to 1234.57, fractionDigits:2 (roundingMode:halfCeil) - 1234.5678 converts to 1230.568, fractionDigits:3 (roundingMode:halfCeil) - 1234.5678 converts to 1234.5678, fractionDigits:4 (roundingMode:halfCeil) - 1234.5678 converts to 1234.56780, fractionDigits:5 (roundingMode:halfCeil)
significantDigits
Type: number | undefined
Significant digits for number formatting, using the browser's Intl.NumberFormat minimumSignificantDigits and maximumSignificantDigits; higher priority than fractionDigits
Example - 1234.5678 converts to 1000, significantDigits:1 - 1234.5678 converts to 1200, significantDigits:2 - 1234.5678 converts to 1230, significantDigits:3 - 1234.5678 converts to 1234, significantDigits:4 - 1234.5678 converts to 1234.6, significantDigits:5 (roundingMode:halfCeil) - 1234.5678 converts to 1234.57, significantDigits:6 (roundingMode:halfCeil) - 1234.5678 converts to 1234.568, significantDigits:7 (roundingMode:halfCeil) - 1234.5678 converts to 1234.5678, significantDigits:8 (roundingMode:halfCeil)
roundingPriority
Type: "morePrecision" | "lessPrecision" | undefined
Rounding priority for number formatting when both significantDigits and fractionDigits are set; uses the browser's Intl.NumberFormat, following the same rules as Intl.NumberFormat's roundingPriority
Example - 1234.5678 converts to 1230, significantDigits:3 (roundingPriority:lessPrecision) - 1234.5678 converts to 1234.5678, significantDigits:3 (roundingPriority:morePrecision)
roundingMode
Type: "floor" | "ceil" | "expand" | "trunc" | "halfCeil" | "halfFloor" | "halfExpand" | "halfTrunc" | "halfEven" | undefined
Rounding mode for number formatting, using the browser's Intl.NumberFormat, following the same rules as Intl.NumberFormat's roundingMode
encoding
Type: "color" | "tooltip" | "label" | undefined
Channel to which the measure is mapped
- color: measure mapped to the color channel
- label: measure mapped to the label channel
- tooltip: measure mapped to the tooltip channel
parentId
Type: string | undefined
In flat measure configuration form, builds a tree-shaped measure group. parentId points to the id of the parent measure group, used for building the measure tree
There are two ways to configure the measure tree: Option 1 is directly configuring a measure tree with children; Option 2 is configuring a flat measure list with parentId. These two methods cannot be used simultaneously
page
Type: Page | undefined
Pagination configuration
field
Type: string
Pagination field; specifies the field name for pagination, must be a dimension
currentValue
Type: string
Current pagination value; specifies the value used to determine the current page
Example '2023-01-01'
backgroundColor
Type: BackgroundColor
Chart background color
Background color can be a color string (e.g. 'red', 'blue'), or a hex, rgb, or rgba value (e.g. '#ff0000', 'rgba(255,0,0,0.5)')
color
Type: Color | undefined
Color
Color configuration for defining the chart's color scheme, including color lists, color mappings, and color gradients.
colorScheme
Type: string[] | undefined
Discrete color scheme used to define the colors of different elements in the chart
Example ['#FFCDD2,#F8BBD0,#E1BEE7,#D1C4E9,#C5CAE9,#BBDEFB,#B3E5FC,#B2EBF2,#B2DFDB,#C8E6C9,#DCEDC8,#F0F4C3,#FFF9C4,#FFECB3,#FFE0B2']
linearColorScheme
Type: string[] | undefined
Linear gradient color scheme used to define the colors of different elements in the chart
Example ['#FFCDD2, #F8BBD0]
colorMapping
Type: Record<string, string> | undefined
Color mapping used to map data values to specific colors
Example { 'profit': 'red', 'sales': 'blue', }
positiveColor
Type: string | undefined
Positive/negative color configuration; defines the color for positive values in the chart
negativeColor
Type: string | undefined
Positive/negative color configuration; defines the color for negative values in the chart
label
Type: Label | undefined
Heatmap label configuration, used to define chart data labels. Label color inversion is enabled automatically to ensure readability.
enable
Type: false | true
Whether label functionality is enabled
wrap
Type: boolean | undefined
Whether labels wrap to the next line
showValue
Type: boolean | undefined
Whether labels display measure values
In multi-measure scenarios, there is no concern about conflicting values, because all plot-related measures go through foldMeasures processing and are merged into one measure representing a single data point
Note: encoding's label has higher priority; this config does not affect encoding's label
showValuePercent
Type: boolean | undefined
Whether labels display the percentage of measure values
In multi-measure scenarios, there is no concern about conflicting values, because all plot-related measures go through foldMeasures processing and are merged into one measure representing a single data point
Note: encoding's label has higher priority; this config does not affect encoding's label
showDimension
Type: boolean | undefined
Whether labels display dimension labels
Display all dimension labels
Note: encoding's label has higher priority; this config does not affect encoding's label
autoFormat
Type: boolean | undefined
Whether label values are automatically formatted; when autoFormat is true, numFormat configuration is ignored
numFormat
Type: NumFormat | undefined
Label value format configuration; merged with the format in measure, where measure's format has higher priority. numFormat priority is lower than autoFormat
type
Type: "number" | "percent" | "permille" | "scientific" | undefined
Number format type, supports: number (decimal), percent (%), permille (‰), scientific notation
ratio
Type: number | undefined
Number format ratio, cannot be 0
Example - 100000 converts to 10万, ratio:10000, symbol:"万" - 100000 converts to 10K, ratio:1000, symbol:"K"
symbol
Type: string | undefined
Number format symbol, e.g. %, ‰
Example - 100000 converts to 10万, ratio:10000, symbol:"万" - 100000 converts to 10K, ratio:1000, symbol:"K"
thousandSeparator
Type: boolean | undefined
Thousands separator for number formatting
suffix
Type: string | undefined
Number format suffix
prefix
Type: string | undefined
Number format prefix
fractionDigits
Type: number | undefined
Decimal places for number formatting, using the browser's Intl.NumberFormat minimumFractionDigits and maximumFractionDigits; lower priority than significantDigits
Example - 1234.5678 converts to 1235, fractionDigits:0 (roundingMode:halfCeil) - 1234.5678 converts to 1234.6, fractionDigits:1 (roundingMode:halfCeil) - 1234.5678 converts to 1234.57, fractionDigits:2 (roundingMode:halfCeil) - 1234.5678 converts to 1230.568, fractionDigits:3 (roundingMode:halfCeil) - 1234.5678 converts to 1234.5678, fractionDigits:4 (roundingMode:halfCeil) - 1234.5678 converts to 1234.56780, fractionDigits:5 (roundingMode:halfCeil)
significantDigits
Type: number | undefined
Significant digits for number formatting, using the browser's Intl.NumberFormat minimumSignificantDigits and maximumSignificantDigits; higher priority than fractionDigits
Example - 1234.5678 converts to 1000, significantDigits:1 - 1234.5678 converts to 1200, significantDigits:2 - 1234.5678 converts to 1230, significantDigits:3 - 1234.5678 converts to 1234, significantDigits:4 - 1234.5678 converts to 1234.6, significantDigits:5 (roundingMode:halfCeil) - 1234.5678 converts to 1234.57, significantDigits:6 (roundingMode:halfCeil) - 1234.5678 converts to 1234.568, significantDigits:7 (roundingMode:halfCeil) - 1234.5678 converts to 1234.5678, significantDigits:8 (roundingMode:halfCeil)
roundingPriority
Type: "morePrecision" | "lessPrecision" | undefined
Rounding priority for number formatting when both significantDigits and fractionDigits are set; uses the browser's Intl.NumberFormat, following the same rules as Intl.NumberFormat's roundingPriority
Example - 1234.5678 converts to 1230, significantDigits:3 (roundingPriority:lessPrecision) - 1234.5678 converts to 1234.5678, significantDigits:3 (roundingPriority:morePrecision)
roundingMode
Type: "floor" | "ceil" | "expand" | "trunc" | "halfCeil" | "halfFloor" | "halfExpand" | "halfTrunc" | "halfEven" | undefined
Rounding mode for number formatting, using the browser's Intl.NumberFormat, following the same rules as Intl.NumberFormat's roundingMode
labelFontSize
Type: number | undefined
Label font size
labelFontWeight
Type: string | number | undefined
Label font weight
labelBackgroundColor
Type: string | undefined
Label background color
labelStroke
Type: string | undefined
Label stroke color
labelColor
Type: string | undefined
Label font color
labelColorSmartInvert
Type: boolean | undefined
Whether the label font color automatically inverts based on the graphic element color
labelPosition
Type: "inside" | "outside" | undefined
label position
labelOverlap
Type: boolean | undefined
Whether the label anti-overlap feature is enabled
selector
Type: Selector | Selectors | undefined
Label filtering; the default relationship between selectors is OR
field
Type: string
Dimension field, the id of one item in dimensions
operator
Type: "in" | "not in" | undefined
Dimension field; the ID of an item in dimensions
Operator
- in: Select data items where the value of the dimension field is in 'value'
op
Type: "in" | "not in" | undefined
- not in: Select data items where the value of the dimension field is not in 'value'
Operator
- in: Select data items where the value of the dimension field is in 'value'
- not in: Select data items where the value of the dimension field is not in 'value'
value
Type: string | number | (string | number)[]
Select dimension field values; arrays are supported
dynamicFilter
Type: ChartDynamicFilter | undefined
Dynamic filter (AI-generated code execution)
Implement complex data filtering logic via AI-generated JavaScript code.
Key capabilities:
-
Supports arbitrarily complex data filtering conditions
-
Uses built-in utility functions for data operations
-
Executes safely in the browser environment (Web Worker sandbox)
Environment requirement: only browser environments are supported; Node.js environments use fallback
Note: selector and dynamicFilter cannot be used at the same time; dynamicFilter has higher priority
Chart dynamic filter configuration
Filters chart marks (bars, points, etc.) via AI-generated JavaScript code
type
Type: "row-with-field"
description
Type: string | undefined
Description of the user's filtering requirements (natural language)
Example "Highlight bars with sales > 1000"
"Highlight the bar with the highest profit rate in each region"
code
Type: string
AI-generated JavaScript filtering code
- Only built-in utility functions can be used (accessed via _ or R)
- Input parameters: data (array), each item contains a __row_index field representing the row number
- Must return an array of row index and field combinations: Array<{ __row_index: number, field: string }>
- __row_index represents the row number of the original data item, and field represents the field to be illuminated
- Prohibited: eval, Function, asynchronous operations, DOM API, network requests
Example Highlight the 'sales' field for data items with sales greater than 1000
Highlight the data item with the highest profit rate in each region
Highlight data items filtered by multiple conditions
fallback
Type: Selector | Selectors | undefined
Fallback solution when code execution fails or the environment is not supported
field
Type: string
Dimension field, the id of one item in dimensions
operator
Type: "in" | "not in" | undefined
Dimension field; the ID of an item in dimensions
Operator
- in: Select data items where the value of the dimension field is in 'value'
op
Type: "in" | "not in" | undefined
- not in: Select data items where the value of the dimension field is not in 'value'
Operator
- in: Select data items where the value of the dimension field is in 'value'
- not in: Select data items where the value of the dimension field is not in 'value'
value
Type: string | number | (string | number)[]
Select dimension field values; arrays are supported
result
Type: DynamicFilterExecutionResult<RowWithFieldRes> | undefined
Dynamic filter execution result (runtime field)
Written during the prepare() phase; read-only at runtime
success
Type: false | true
data
Type: T[] | undefined
error
Type: string | undefined
legend
Type: ColorLegend | undefined
Legend
Heatmap color legend configuration, used to define the chart legend, including legend position, format, style, and more.
position
Type: "left" | "leftTop" | "leftBottom" | "lt" | "lb" | "top" | "topLeft" | "topRight" | "tl" | "tr" | "right" | "rightTop" | "rightBottom" | "rt" | "rb" | "bottom" | "bottomLeft" | "bottomRight" | "bl" | "br" | undefined
Legend position
Example position: 'rightTop'
enable
Type: boolean | undefined
Whether the legend feature is enabled
Example enable: true
labelColor
Type: string | undefined
Legend font color
labelFontColor
Type: string | undefined
Legend font color
labelFontSize
Type: number | undefined
Legend font size
Example labelFontSize: 10
labelFontWeight
Type: string | number | undefined
Legend font weight
Example labelFontWeight: 400
railBackgroundColor
Type: string | undefined
handlerBorderColor
Type: string | undefined
tooltip
Type: Tooltip | undefined
Tooltips
Heatmap tooltip configuration, used to define chart tooltip information, including tooltip position, format, style, and more.
enable
Type: false | true
Whether the tooltips feature is enabled
brush
Type: Brush | undefined
Brush selection
Brush configuration; used to enable/disable brush selection capabilities.
Chart brush configuration
enable
Type: boolean | undefined
Whether to enable brush selection
brushType
Type: "rect" | "x" | "y" | "polygon" | undefined
Brush type
Defines the shape and direction of the selection box.
- rect: Rectangular selection; selection can be made in both X and Y directions simultaneously.
- polygon: Polygon selection; perform selection by clicking multiple points to draw an arbitrary polygon.
- x: X-axis selection; selection only in the X direction, with no limits in the Y direction.
- y: Y-axis selection; selection only in the Y direction, with no limits in the X direction.
brushMode
Type: "single" | "multiple" | undefined
Brush selection mode: single or multiple.
Defines the selection mode.
- single: Single selection mode; only one selection box can exist at a time.
- multiple: Multiple selection mode; multiple selection boxes can exist simultaneously.
removeOnClick
Type: boolean | undefined
Whether to clear the selection box after the brush selection ends
inBrushStyle
Type: { opacity?: number; stroke?: string; lineWidth?: number; } | undefined
Style for selected data items
Defines the style of the selected data points.
opacity
Type: number | undefined
Opacity
Opacity of the selected data points, ranging from 0 to 1
stroke
Type: string | undefined
Stroke color
lineWidth
Type: number | undefined
Stroke width
outOfBrushStyle
Type: { opacity?: number; stroke?: string; lineWidth?: number; } | undefined
Style for unselected data items
Defines the style of the unselected data points.
opacity
Type: number | undefined
Opacity
Opacity of unselected data points, ranging from 0 to 1
stroke
Type: string | undefined
Stroke color
lineWidth
Type: number | undefined
Stroke width
theme
Type: Theme | undefined
Chart theme; themes are lower-priority configurations containing general settings shared by all chart types as well as settings shared by specific chart categories.
Built-in light and dark themes; users can customize themes via the Builder.
Theme
Built-in light and dark themes; new themes can be customized via registerTheme.
Example 'dark'
'light'
'customThemeName'
length
Type: number
brand
Type: brand
locale
Type: "zh-CN" | "en-US" | "ja-JP" | "de-DE" | "id-ID" | "fr-FR" | "ko-KR" | "vi-VN" | undefined
Locale
Chart locale configuration; supports 'zh-CN' and 'en-US'. You can also call intl.setLocale('zh-CN') to set the language.