2DIssue triageGuide 06

Label co-occurrence heatmaps for issue triage

Find which labels appear together so maintainers can simplify taxonomies and route work faster.

Use this pattern Open playground

authapiuidbperfdocscia11y

lessmore

8 labels · pair countsHover or focus a cell for details

Rows: Issue label
Columns: Paired label
Value: Shared issue count

The pattern

What the data tells you

The matrix is symmetric. The empty diagonal removes self-pairs so relationships between labels take focus.

A co-occurrence matrix shows how often two labels share the same issue, pull request, or document. Hide the diagonal when self-pairs carry no information and use a quantile scale when the distribution is uneven.

Label systems grow organically and become hard to reason about. A symmetric heatmap turns the hidden relationships into a surface that a maintainer can inspect, discuss, and use to consolidate labels.

Build it in React

From data to heatmap

TypeScript / React

Prepare your data

A square matrix where each cell contains the count for a pair of categories. Sort both axes with the same label order to preserve symmetry.

Make the component yours

Start with this example. Adjust the labels, colours, and tooltips to fit your product.

label-co-occurrence.tsx

import { Heatmap } from "@thilakbhat/heatmap-ui";
import "@thilakbhat/heatmap-ui/styles.css";

const labels = ["auth", "api", "ui", "db", "docs"];
// How often each pair of labels shares an issue. Symmetric; the diagonal is unused.
const overlap = [
  [0, 18, 4, 12, 6],
  [18, 0, 9, 22, 3],
  [4, 9, 0, 7, 15],
  [12, 22, 7, 0, 5],
  [6, 3, 15, 5, 0],
];

export function LabelMatrix() {
  return (
    <Heatmap
      rows={labels.length}
      columns={labels.length}
      values={overlap}
      shape="square"
      scale="quantile"
      isSlotHidden={(row, column) => row === column}
      rowLabels={labels}
      columnLabels={labels.map((text, column) => ({ column, text }))}
      tooltip={(cell) => `${labels[cell.row]} + ${labels[cell.column]}: ${cell.value} issues`}
    />
  );
}

Key props

Heatmapscale="quantile"isSlotHiddenshape="square"

API reference

A few more details

Common questions

Label co-occurrence heatmaps, explained.

What does a label co-occurrence heatmap reveal?

It shows how often two labels appear on the same issue, pull request, ticket, or document, making redundant, coupled, or unexpectedly related categories easier to find.

How do I build a co-occurrence matrix from issues?

For each record, count every pair of labels that appears together, write the counts into a square matrix, and use the same ordered label list for both axes.

Why hide the diagonal in a label matrix?

The diagonal represents a label paired with itself, which usually adds no triage insight. Hiding it gives more visual emphasis to relationships between different labels.

When should I use a quantile scale for co-occurrence data?

Use a quantile scale when a few label pairs are much more common than the rest. It preserves useful contrast across the long tail instead of flattening most cells near the minimum colour.