Heatmap

Use a heatmap to show values at the intersections of two categorical dimensions.

Every preview on this page is generated from the YAML shown below it using a fixed documentation dataset.

Basic matrix

Provide two dimensions for the row and column axes and one measure for cell intensity, creating a compact comparison across both categories.

Key fields

visuals:
  state_status_heatmap:
    title: State by order status
    description: Shows order status concentration by customer state.
    type: heatmap
    query:
      dimensions:
        state: orders.state
        status: orders.status
      measures:
        order_count: null
      sort:
        - field: state
          direction: asc
        - field: status
          direction: asc
      limit: 120

Alternate dimensions

Replace the row dimension with product category to reuse the same matrix contract for a different categorical relationship.

Key fields

visuals:
  category_status_heatmap:
    title: Category by order status
    type: heatmap
    query:
      dimensions:
        category: orders.category
        status: orders.status
      measures:
        order_count: null
      sort:
        - field: value
          direction: desc
      limit: 120

Cell labels

Enable presentation.show_labels when exact cell values matter in addition to color intensity and the matrix remains sparse enough to read.

Key fields

visuals:
  category_status_heatmap_labels:
    title: Labeled category status heatmap
    type: heatmap
    presentation:
      show_labels: true
    query:
      dimensions:
        category: orders.category
        status: orders.status
      measures:
        order_count: null
      sort:
        - field: value
          direction: desc
      limit: 80

API reference

Kind: chart. Renderer: echarts. Supported result shapes: matrix.

Field	Type	Default	Allowed values	Description
`query.dimensions`	`field mapping`	—	—	Groups query results and supplies category, hierarchy, matrix, graph, or geographic labels.
`query.limit`	`integer`	`no limit`	`positive integer`	Caps the number of rows returned to the renderer.
`query.measures`	`measure mapping`	—	—	Selects the governed semantic measures consumed by the visual shape.
`query.sort`	`sort list`	—	—	Orders query results by a returned field or measure alias.
`presentation.show_labels`	`boolean`	`false`	`true` `false`	Shows value labels directly on chart marks.

Accessibility. Use a descriptive title and unit, and do not rely on color alone to distinguish series or values.