Matrix Chart — cinder playground

Overview

Categorical × categorical heatmap for dense analytics, confusion matrices, and correlation grids.

Usage

<script lang="ts">
  import MatrixChart from '@lostgradient/cinder/matrix-chart';

  const data = [
    { actual: 'Cat', predicted: 'Cat', count: 50 },
    { actual: 'Cat', predicted: 'Dog', count: 5 },
    { actual: 'Cat', predicted: 'Bird', count: 2 },
    { actual: 'Dog', predicted: 'Cat', count: 3 },
    { actual: 'Dog', predicted: 'Dog', count: 42 },
    { actual: 'Dog', predicted: 'Bird', count: 1 },
    { actual: 'Bird', predicted: 'Cat', count: 4 },
    { actual: 'Bird', predicted: 'Dog', count: 2 },
    { actual: 'Bird', predicted: 'Bird', count: 38 },
  ];
</script>

<MatrixChart
  label="Confusion matrix — Animal classifier"
  description="Rows are actual classes; columns are predicted classes. Diagonal cells are correct predictions."
  {data}
  xField="predicted"
  yField="actual"
  valueField="count"
  colorScale="sequential"
  dataTableVisibility="visible"
/>

Guidance

Use When

Showing density or magnitude across two categorical dimensions simultaneously.
Rendering a confusion matrix where rows are actual classes and columns are predicted classes.

Avoid When

Showing a continuous trend over time — use line-chart instead.
Comparing discrete category totals — use bar-chart instead.

Rendering and theming

MatrixChart uses SVG and derives its plot margins from the category labels instead of fixed offsets. The default foreground follows currentColor, the chart background remains transparent, and heatmap colors resolve through --cinder-chart-series-* against the semantic inset surface. Pass a partial theme to override the palette or chart colors. The semantic data table remains the exact, non-color representation of every cell.

Live preview

When to use

Use when

Showing density or magnitude across two categorical dimensions simultaneously.
Rendering a confusion matrix where rows are actual classes and columns are predicted classes.

Avoid when

Showing a continuous trend over time — use line-chart instead.
Comparing discrete category totals — use bar-chart instead.

Examples

Confusion matrix

A 3-class confusion matrix showing predicted vs actual classification results.

Performance heatmap

Team performance scores across quarters, colored with a diverging scale.

Props

Props for matrix-chart
Name	Type	Default	Description
`label` required	`text`		Accessible label for the chart. Required for screen readers.
`description`	`text`		Optional description rendered below the label.
`data` required	`MatrixChartDatum[]`		Rows of data. Each row must include the keys named by the `xField`, `yField`, and `valueField` props.
`xField` required	`text`		Key on each datum used for the x-axis (columns).
`yField` required	`text`		Key on each datum used for the y-axis (rows).
`valueField` required	`text`		Key on each datum used for the numeric cell value.
`colorScale`	`'sequential' \| 'diverging'`	`'sequential'`	Color interpolation scale. Default `sequential`.
`cellLabelsVisible`	`boolean`	`true`	Show cell value labels. Default `true`.
`height`	`number`	`280`	Pixel height of the chart viewport. Default `280`.
`loading`	`boolean`	`false`	Whether the chart is in a loading state.
`dataTableCaption`	`text`		Custom data table caption; falls back to `label`.
`dataTableVisibility`	`'screen-reader-only' \| 'visible' \| 'hidden'`	`'screen-reader-only'`	Controls data table visibility. Default `screen-reader-only`.
`theme`	`ChartTheme`		Partial visual theme override.
`empty`	`snippet`		Snippet rendered when the chart has no data.
`loadingContent`	`snippet`		Snippet rendered while the chart is loading.
`id`	`text`