HeatMap

Color scales

Six built-in scales control how values map to terminal colors:

Constant	Appearance
ColorScaleGreen	Dark → bright green
ColorScaleRed	Dark → bright red
ColorScaleBlue	Dark → bright blue
ColorScaleHeat	Blue → green → yellow → red
ColorScaleTheme	Theme background (low) → theme accent (high)
ColorScaleCustom	Supply your own func(normalized float64) tcell.Color

ColorScaleHeat is the default. Use ColorScaleTheme when you want the heatmap to match the active color theme automatically.

Auto-scaling

By default (autoScale = true) the min/max are computed from the data on each SetCells or SetData call. Call SetRange(min, max) to pin the scale to fixed bounds — useful when comparing multiple heatmaps or when the range has meaningful semantics (e.g. 0–100%).

Value labels

SetShowValues(true) overlays the raw value in each cell. The default format is "%.0f"; override with SetValueFormat using any fmt.Sprintf verb.

catppuccin-frappecatppuccin-lattecatppuccin-macchiatocatppuccin-mochadraculadracula-lighteverforest-darkeverforest-lightgithub-darkgithub-lightgruvbox-darkgruvbox-lightkanagawamonokainordonedarkonelightrosepinerosepine-dawnrosepine-moonsolarized-darksolarized-lighttokyonight-daytokyonight-moontokyonight-nighttokyonight-storm

HeatMap renders a grid with color intensity based on values

Constructor func NewHeatMap() *HeatMap

Usage

hm := components.NewHeatMap().
  SetTitle("Activity").
  SetValues([][]float64{
    {0, 3, 8, 2},
    {5, 9, 1, 6},
  }).
  SetColLabels([]string{"Mon", "Tue", "Wed", "Thu"}).
  SetRowLabels([]string{"AM", "PM"}).
  SetColorScale(components.ColorScaleTheme).
  SetShowValues(true).
  SetValueFormat("%.0f")

fmt.Println(hm != nil)

Methods

Method	Signature	Description
Clear	func (h *HeatMap) Clear() *HeatMap	Clear removes all data
GetFieldHeight	func (h *HeatMap) GetFieldHeight() int	GetFieldHeight returns preferred height
SetAutoScale	func (h *HeatMap) SetAutoScale(enabled bool) *HeatMap	SetAutoScale enables/disables automatic range
SetCellChar	func (h *HeatMap) SetCellChar(char rune) *HeatMap	SetCellChar sets the character used to fill cells
SetCellSize	func (h *HeatMap) SetCellSize(width, height int) *HeatMap	SetCellSize sets cell dimensions
SetColLabels	func (h *HeatMap) SetColLabels(labels []string) *HeatMap	SetColLabels sets labels for columns
SetColorFunc	func (h *HeatMap) SetColorFunc(fn func(normalized float64) tcell.Color) *HeatMap	SetColorFunc sets a custom color function and switches the scale to ColorScaleCustom. The argument is the normalized value in [0.0, 1.0].
SetColorScale	func (h *HeatMap) SetColorScale(scale ColorScale) *HeatMap	SetColorScale sets the color mapping strategy. ColorScaleTheme adapts to the active theme automatically; ColorScaleCustom requires a SetColorFunc.
SetData	func (h *HeatMap) SetData(cells [][]HeatMapCell) *HeatMap	SetData sets the 2D grid data
SetOnHover	func (h *HeatMap) SetOnHover(fn func(row, col int, cell HeatMapCell)) *HeatMap	SetOnHover sets callback for cell hover
SetOnSelect	func (h *HeatMap) SetOnSelect(fn func(row, col int, cell HeatMapCell)) *HeatMap	SetOnSelect sets callback for cell selection
SetRange	func (h *HeatMap) SetRange(min, max float64) *HeatMap	SetRange pins the color scale to a fixed [min, max] range and disables auto-scaling. Use this when comparing multiple heatmaps side-by-side or when the range has domain meaning (e.g., 0–100 for percentages).
SetRowLabels	func (h *HeatMap) SetRowLabels(labels []string) *HeatMap	SetRowLabels sets labels for rows
SetShowValues	func (h *HeatMap) SetShowValues(show bool) *HeatMap	SetShowValues shows/hides values in cells
SetTitle	func (h *HeatMap) SetTitle(title string) *HeatMap	SetTitle sets the chart title
SetValueFormat	func (h *HeatMap) SetValueFormat(format string) *HeatMap	SetValueFormat sets printf format for values
SetValues	func (h *HeatMap) SetValues(values [][]float64) *HeatMap	SetValues sets grid from 2D float array
UpdateCell	func (h *HeatMap) UpdateCell(row, col int, value float64) *HeatMap	UpdateCell updates a single cell value

Types

type ColorScale ColorScale defines how values map to colors

Constant	Description
ColorScaleGreen
ColorScaleRed
ColorScaleBlue
ColorScaleHeat
ColorScaleTheme
ColorScaleCustom

type HeatMapCell struct HeatMapCell represents a single cell in the heat map

Field	Type	Description
Value	float64
Label	string	Optional tooltip/label