MatrixChart

Generic x/y heatmap with categorical axes

Usage

MatrixChart is a heatmap with categorical axes, each cell is colored based on its value:

JamesMaryRobertLindaMichaelSarahDavidEmma
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 that defines the cell color, null for empty cells

Labels

Set withXLabels and withYLabels to display axis labels. Use xLabels and yLabels props to override labels taken from the data. Increase yLabelsWidth and xLabelsHeight if your labels are longer than the reserved space:

MonTueWedThuFriSatSun6 AM8 AM10 AM12 PM2 PM4 PM6 PM8 PM
import { MatrixChart } from '@mantine/charts';
import { data, xLabels, yLabels } from './data';

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

Set xLabelsPosition="top" to display x-axis labels above the chart:

MonTueWedThuFriSatSun6 AM8 AM10 AM12 PM2 PM4 PM6 PM8 PM
import { MatrixChart } from '@mantine/charts';
import { data, xLabels, yLabels } from './data';

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

X-axis labels rotation

Use xLabelsRotation prop to change the angle of x-axis labels, for example, 0 for horizontal labels. Horizontal labels overlap when they are wider than a cell, rotate long labels instead:

MonTueWedThuFriSatSun6 AM8 AM10 AM12 PM2 PM4 PM6 PM8 PM
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:

MonTueWedThuFriSatSun6 AM8 AM10 AM12 PM2 PM4 PM6 PM8 PM
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 change the palette. Each cell is painted with the palette color nearest to its value:

MonTueWedThuFriSatSun6 AM8 AM10 AM12 PM2 PM4 PM6 PM8 PM
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-8)',
      ]}
    />
  );
}

Values domain

By default, the palette spans from the lowest to the highest displayed value. Use domain prop to set a custom [min, max] range. A reversed domain ([max, min]) inverts the colors:

MonTueWedThuFriSatSun6 AM8 AM10 AM12 PM2 PM4 PM6 PM8 PM
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, gap and cellRadius props to change cell size, spacing and border radius:

MonTueWedThuFriSatSun6 AM8 AM10 AM12 PM2 PM4 PM6 PM8 PM
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 to add props to individual cells based on their data:

MonTueWedThuFriSatSun6 AM8 AM10 AM12 PM2 PM4 PM6 PM8 PM
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 change its labels:

MonTueWedThuFriSatSun6 AM8 AM10 AM12 PM2 PM4 PM6 PM8 PMLessMore
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

Use valueFormatter to include units in the chart summary read by screen readers:

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

function Demo() {
  return <MatrixChart data={data} valueFormatter={(value) => `${value} visitors`} />;
}

Set aria-label or aria-labelledby to replace the summary with your own description:

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

function Demo() {
  return <MatrixChart data={data} aria-label="Website visitors by weekday and hour" />;
}