MatrixChart | Mantine

Usage

MatrixChart is a generic x/y heatmap with categorical axes. Each cell is colored based on a value. Data is an array of objects with x, y, and value properties.

import { MatrixChart } from '@mantine/charts';
import { data } from './data';

function Demo() {
  return (
    <MatrixChart
      data={data}
      yLabels={['James', 'Mary', 'Robert', 'Linda', 'Michael', 'Sarah', 'David', 'Emma']}
      withYLabels
      withTooltip
      getTooltipLabel={({ x, y, value }) =>
        `${y}, Mar ${x}: ${value === null ? 'No contributions' : `${value} contribution${value > 1 ? 's' : ''}`}`
      }
    />
  );
}

Data format

Data is an array of MatrixChartCell objects:

interface MatrixChartCell {
  x: string;
  y: string;
  value: number | null;
}

x – column identifier
y – row identifier
value – numeric value for color interpolation, null for empty cells

Use xLabels and yLabels props to provide axis labels. Set withXLabels to display x-axis labels along the bottom (or top with xLabelsPosition="top"), and withYLabels to display y-axis labels on the left side. Both label arrays are optional – when they are not provided, the labels are taken from the x and y values of data in the order they first appear.

import { MatrixChart } from '@mantine/charts';
import { data, xLabels, yLabels } from './data';

function Demo() {
  return <MatrixChart data={data} xLabels={xLabels} yLabels={yLabels} withYLabels withXLabels />;
}

X-axis labels rotation

By default, x-axis labels are rotated -90 degrees. Use xLabelsRotation prop to change the angle. Set it to 0 for horizontal labels or -45 for angled labels.

import { MatrixChart } from '@mantine/charts';
import { data, xLabels, yLabels } from './data';

function Demo() {
  return (
    <MatrixChart
      data={data}
      xLabels={xLabels}
      yLabels={yLabels} withYLabels
      withXLabels
      xLabelsRotation={-45}
    />
  );
}

Tooltip

Set withTooltip prop and provide getTooltipLabel function to display a tooltip on cell hover.

import { MatrixChart } from '@mantine/charts';
import { data, xLabels, yLabels } from './data';

function Demo() {
  return (
    <MatrixChart
      data={data}
      xLabels={xLabels}
      yLabels={yLabels} withYLabels
      withXLabels
      withTooltip
      getTooltipLabel={({ x, y, value }) =>
        `${y} ${x}: ${value === null ? 'No data' : `${value} visitors`}`
      }
    />
  );
}

Colors

Use colors prop to customize the color palette. Colors are interpolated based on the cell value within the domain range.

import { MatrixChart } from '@mantine/charts';
import { data, xLabels, yLabels } from './data';

function Demo() {
  return (
    <MatrixChart
      data={data}
      xLabels={xLabels}
      yLabels={yLabels} withYLabels
      withXLabels
      colors={[
        'var(--mantine-color-orange-2)',
        'var(--mantine-color-orange-4)',
        'var(--mantine-color-orange-6)',
        'var(--mantine-color-orange-9)',
      ]}
    />
  );
}

Values domain

By default, domain is auto-calculated from data min/max values. Use domain prop to set a custom [min, max] range for color interpolation.

import { MatrixChart } from '@mantine/charts';
import { data, xLabels, yLabels } from './data';

function Demo() {
  return (
    <MatrixChart
      data={data}
      xLabels={xLabels}
      yLabels={yLabels} withYLabels
      withXLabels
      domain={[0, 50]}
    />
  );
}

Cell size and gap

Use cellSize and gap props to control cell dimensions and spacing. cellRadius controls the border radius of cells.

import { MatrixChart } from '@mantine/charts';
import { data, xLabels, yLabels } from './data';

function Demo() {
  return (
    <MatrixChart
      data={data}
      xLabels={xLabels}
      yLabels={yLabels} withYLabels
      withXLabels
      cellSize={30}
      gap={3}
      cellRadius={4}
    />
  );
}

Pass props to cells

Use getCellProps callback to add custom props to individual cells based on their data.

import { MatrixChart } from '@mantine/charts';
import { data, xLabels, yLabels } from './data';

function Demo() {
  return (
    <MatrixChart
      data={data}
      xLabels={xLabels}
      yLabels={yLabels} withYLabels
      withXLabels
      getCellProps={(cell) => {
        if (cell.value === null) {
          return {};
        }

        if (cell.value >= 25) {
          return { fill: 'var(--mantine-color-teal-6)' };
        }

        if (cell.value >= 15) {
          return { fill: 'var(--mantine-color-yellow-6)' };
        }

        return { fill: 'var(--mantine-color-red-6)' };
      }}
    />
  );
}

Legend

Set withLegend prop to display a color legend below the chart. Use legendLabels prop to customize the legend text.

import { MatrixChart } from '@mantine/charts';
import { data, xLabels, yLabels } from './data';

function Demo() {
  return (
    <MatrixChart
      data={data}
      xLabels={xLabels}
      yLabels={yLabels} withYLabels
      withXLabels
      withLegend
    />
  );
}

Accessibility

Matrix cells are decorative rect elements – they carry no text for screen readers. Set aria-label (or aria-labelledby) to describe what the chart shows; the chart is then exposed as a single labelled image instead of a grid of anonymous shapes:

import { MatrixChart } from '@mantine/charts';

function Demo() {
  return <MatrixChart data={[]} aria-label="Deployments per service and weekday" />;
}

SankeyChart

Getting started