Heatmap

A heatmap paints a cell for each row. The position is the category. The color is the number. You read a pattern across the grid, not a length.

When to use it

Use a heatmap when the question is which combinations stand out. Requests by hour is a week of hours. The dark cells are the busy ones. Load by service is four services across five weekdays. Jobs on Thursday and Auth on Friday carry the load. Commit calendar is the same idea on dates: twelve weeks, one cell per day.

A bar ranks one list. The length is the number, and the categories sit on a straight axis. A heatmap of every hour and day would be dozens of bars. The color is the comparison when the matrix is the point.

A table is for reading the number in a cell. Load by service looks like a table, and the cells line up in rows and columns, but the fill is the encoding. Use a table when the reader needs the exact figure first. Use a heatmap when they need the pattern. The tooltip still carries the number.

Heatmap, bar, and a table

type: "heatmap" binds the number to encoding.color. encoding.x is the column. encoding.y, when you set it, is the row. Omit y and pass dates, and the chart is a calendar.

type: "bar" binds the number to encoding.y and draws a length. A heatmap does not. Putting the calendar's number on y repairs it onto color. On a grid, y stays the row, and a missing color is an error.

grid-heatmap repairs to a grid. calendar-heatmap repairs to a calendar. rect repairs to heatmap. The type string is heatmap either way. There is no second chart type for the calendar.

Data

Each row is one cell. Requests by hour uses hour, day, and value. Load by service uses day, service, and load. Commit calendar uses date and value, and it does not have a row field.

For a grid, set encoding.x, encoding.y, and encoding.color. Omit mark.layout and the y field selects the grid. Set mark.layout to grid when you want that written down. Requests by hour and Load by service both do.

For a calendar, point encoding.x at a date and encoding.color at the number. Set mark.layout to calendar. A missing y also selects the calendar, which is why the smallest grid on this page includes y. mark.weeks is how many weeks to show, ending on the week of the latest day. Commit calendar sets 12. The default is 52. On a grid, weeks warns CK3012 and is ignored.

A cell with no number is a hatch, not the low end of the ramp, so a gap does not look like a quiet hour. Categories keep the order they first appear in.

a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.

A spec that renders

This is the smallest heatmap. version, type, and a11y.alt are required. Two cells share a row, so encoding.y makes a grid and mark can be omitted. The ramp is blue until you name a scheme.

spec.json
{
  "version": "1",
  "type": "heatmap",
  "data": [
    {
      "x": "A",
      "y": "Low",
      "v": 1
    },
    {
      "x": "B",
      "y": "Low",
      "v": 4
    }
  ],
  "encoding": {
    "x": "x",
    "y": "y",
    "color": "v"
  },
  "a11y": {
    "alt": "B is darker than A on the same row."
  }
}

Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.

Import@chartkitdev/core/charts/heatmapBundle@chartkitdev/core/allFamilyCore
React
npm install @chartkitdev/core
npm install @chartkitdev/react

import { Chart } from "@chartkitdev/react";

export function Panel() {
  return <Chart spec={spec} />;
}
Vanilla
npm install @chartkitdev/core
npm install @chartkitdev/vanilla

import { mount } from "@chartkitdev/vanilla";

const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);
Vue
npm install @chartkitdev/core
npm install @chartkitdev/vue

<script setup>
import { Chart } from "@chartkitdev/vue";
</script>

<template>
  <Chart :spec="spec" />
</template>
Svelte
npm install @chartkitdev/core
npm install @chartkitdev/svelte

<script>
  import { Chart } from "@chartkitdev/svelte";
</script>

<Chart {spec} />
Astro
npm install @chartkitdev/core
npm install @chartkitdev/astro

---
import { Chart } from "@chartkitdev/astro";
---

<Chart spec={spec} />
Solid
npm install @chartkitdev/core
npm install @chartkitdev/solid

import { Chart } from "@chartkitdev/solid";

export function Panel() {
  return <Chart spec={spec} />;
}
Qwik
npm install @chartkitdev/core
npm install @chartkitdev/qwik

import { component$ } from "@builder.io/qwik";
import { Chart } from "@chartkitdev/qwik";

export const Panel = component$(() => {
  return <Chart spec={spec} />;
});
Angular
npm install @chartkitdev/core
npm install @chartkitdev/angular

import { Component } from "@angular/core";
import { Chart } from "@chartkitdev/angular";

@Component({
  standalone: true,
  imports: [Chart],
  template: `<ck-chart [spec]="spec" />`,
})
export class Panel {
  spec = spec;
}
Custom element
npm install @chartkitdev/core
npm install @chartkitdev/element

import "@chartkitdev/element";

const chart = document.querySelector("chart-kit");
chart.spec = spec;

Heatmap ships in @chartkitdev/core/all. createRenderer([heatmap]) from @chartkitdev/core/charts/heatmap is the one-chart build.

Each option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.

Examples

Requests by hour is the gallery grid: seven days, eight hours. Load by service is the smaller matrix, services by weekday. Commit calendar is the date layout. The layout is part of the example, because a calendar has no row field and a category grid has no dates. Switching one into the other does not produce the other chart.

Layout

mark.layout is grid or calendar. It wins when you set it. Otherwise encoding.y means grid, and a missing y means calendar.

mark.layout grid
{
  "mark": { "layout": "grid" }
}
mark.layout calendar
{
  "encoding": { "x": { "field": "date", "type": "temporal" }, "color": "value" },
  "mark": { "layout": "calendar", "weeks": 12 }
}

There is no layout control on this page. Pick the example that matches the table you have. Requests by hour and Load by service are grids. Commit calendar sets calendar and weeks.

Scheme

encoding.color.scale.scheme is the ramp. blue, teal, orange, or violet. Omit it and the ramp is blue. The low end is light and the high end is dark on a light page. A dark theme uses a brighter ramp of the same name.

encoding.color.scale.scheme
{
  "encoding": {
    "color": { "field": "value", "scale": { "scheme": "teal" } }
  }
}

The field, the title, and any other scale keys stay. Requests by hour sets title to Requests, and the ramp draws that label. validate() also warns CK3012 on a color title, the note it uses when a title belongs on an axis. The heatmap still paints it on the ramp. Load by service stores the measure as the field name load. Choosing blue again puts that channel back, including a bare field name. A range of two or more colors replaces the named scheme. Set that in the playground.

The ramp is drawn under the cells. That strip is the color legend. The legend key is the series legend used by bars and lines. It does not replace this ramp.

Tooltip

tooltip is on for a heatmap when the key is omitted. Hovering a cell shows its categories and its value. tooltip: false turns the card off. tooltip: true turns it on.

tooltip false
{
  "tooltip": false
}
tooltip true
{
  "tooltip": true
}

tooltip.fields chooses the rows in the card, and tooltip.position places it. Change those in the playground. Turning the card off and on again puts that object back. An example that omitted tooltip gets the key removed, so the default stays on.

The rest of the spec

mark.gap is the space between cells, as a fraction of the band. Omit it and a grid uses a small gap. mark.cornerRadius rounds the cells. mark.weeks belongs on a calendar. Sequential is the default scale. Diverging, quantize, threshold, and an explicit domain live on encoding.color.scale in the playground, with the theme presets.