# WaffleChart
Package: @mantine/charts
Import: import { WaffleChart } from '@mantine/charts';
Description: Part-to-whole grid chart with colored cells

## Usage

`WaffleChart` displays parts of a whole as a grid of colored cells. Each segment
of the `data` array is allocated a number of cells proportional to its `value`,
which makes proportions easier to compare than in a pie or donut chart.

Unlike most charts in `@mantine/charts`, `WaffleChart` does not use
[recharts](https://recharts.org/) – the grid is rendered as a plain `svg` element.

```tsx
// Demo.tsx
import { WaffleChart } from '@mantine/charts';
import { data } from './data';

function Demo() {
  return <WaffleChart data={data} />;
}

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

export const data: WaffleChartCell[] = [
  { name: 'Chrome', value: 65, color: 'blue' },
  { name: 'Safari', value: 19, color: 'teal' },
  { name: 'Firefox', value: 10, color: 'orange' },
  { name: 'Other', value: 6, color: 'gray' },
];
```


## Total

By default, the sum of all `value` fields is treated as 100% and the entire grid
is filled. Set `total` to a larger number to leave the remaining cells empty –
this is useful to display progress towards a goal. Values smaller than the sum of
the data are ignored.

## Tooltip

Set `withTooltip` to display a tooltip when a cell is hovered. Use `getTooltipLabel`
to customize its content – the function receives the segment and the number of cells
allocated to it:

```tsx
// Demo.tsx
import { WaffleChart } from '@mantine/charts';
import { data } from './data';

function Demo() {
  return (
    <WaffleChart
      data={data}
      withTooltip
      getTooltipLabel={(cell) => `${cell.name}: ${cell.value}%`}
    />
  );
}

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

export const data: WaffleChartCell[] = [
  { name: 'Chrome', value: 65, color: 'blue' },
  { name: 'Safari', value: 19, color: 'teal' },
  { name: 'Firefox', value: 10, color: 'orange' },
  { name: 'Other', value: 6, color: 'gray' },
];
```


## Legend

Legend is displayed at the bottom of the chart by default. Use `legendPosition`
to move it to the `top`, `left` or `right` side, or set `withLegend={false}` to hide it:

```tsx
// Demo.tsx
import { WaffleChart } from '@mantine/charts';
import { data } from './data';

function Demo() {
  return <WaffleChart data={data}  legendPosition="bottom" />;
}

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

export const data: WaffleChartCell[] = [
  { name: 'Chrome', value: 65, color: 'blue' },
  { name: 'Safari', value: 19, color: 'teal' },
  { name: 'Firefox', value: 10, color: 'orange' },
  { name: 'Other', value: 6, color: 'gray' },
];
```


## Gap and grid size

`rows` and `columns` control the number of cells in the grid (10 × 10 by default),
`gap` controls the distance between them and `cellRadius` the border radius of each cell.
Set `size` to control the width of the chart – if it is not set, the width is calculated
from the number of columns.

```tsx
// Demo.tsx
import { WaffleChart } from '@mantine/charts';
import { data } from './data';

function Demo() {
  return <WaffleChart data={data}  gap={2} columns={10} rows={10} />;
}

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

export const data: WaffleChartCell[] = [
  { name: 'Chrome', value: 65, color: 'blue' },
  { name: 'Safari', value: 19, color: 'teal' },
  { name: 'Firefox', value: 10, color: 'orange' },
  { name: 'Other', value: 6, color: 'gray' },
];
```


## Fill direction

`fillDirection` controls the order in which cells are filled:

```tsx
// Demo.tsx
import { WaffleChart } from '@mantine/charts';
import { data } from './data';

function Demo() {
  return <WaffleChart data={data}  fillDirection="left-to-right" />;
}

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

export const data: WaffleChartCell[] = [
  { name: 'Chrome', value: 65, color: 'blue' },
  { name: 'Safari', value: 19, color: 'teal' },
  { name: 'Firefox', value: 10, color: 'orange' },
  { name: 'Other', value: 6, color: 'gray' },
];
```


## Empty cells color

Cells that are not allocated to any segment use `--waffle-empty-color` – set the
`emptyColor` prop to change it:

```tsx
import { WaffleChart } from '@mantine/charts';

function Demo() {
  return (
    <WaffleChart
      data={[{ name: 'Completed', value: 68, color: 'teal' }]}
      total={100}
      emptyColor="gray.3"
    />
  );
}
```


## Accessibility

The grid is exposed to screen readers as a single image labelled with every segment name and value,
so the data is available whether or not the legend is displayed. The legend itself is `aria-hidden`
because it repeats those names visually.

Set `aria-label` (or `aria-labelledby`) to describe what the values represent. The chart root then
becomes a labelled group – a plain `div` cannot carry an accessible name – and your label is
announced alongside the generated data summary rather than replacing it.


#### Props

**WaffleChart props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| cellRadius | number | - | Cell border radius, |
| columns | number | - | Number of columns, |
| data | WaffleChartCell[] | required | Array of data segments with name, value, and color |
| emptyColor | MantineColor | - | Color of empty (unfilled) cells |
| fillDirection | "right-to-left" \| "left-to-right" \| "top-to-bottom" \| "bottom-to-top" | - | Fill direction, |
| gap | number | - | Gap between cells in px, |
| getTooltipLabel | (cell: WaffleChartCell & { count: number; }) => ReactNode | - | Custom tooltip label formatter |
| legendPosition | "left" \| "right" \| "bottom" \| "top" | - | Legend position, |
| rows | number | - | Number of rows, |
| size | number | - | Chart size (width), auto-calculated from columns if not set |
| total | number | - | Total value for the chart, determines how many cells are filled vs empty, sum of all values by default |
| withLegend | boolean | - | Whether to show legend, |
| withTooltip | boolean | - | Whether to show tooltip on hover, |


#### Styles API

WaffleChart component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**WaffleChart selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| root | .mantine-WaffleChart-root | Root container element |
| grid | .mantine-WaffleChart-grid | SVG grid element |
| cell | .mantine-WaffleChart-cell | Individual cell rect |
| legend | .mantine-WaffleChart-legend | Legend container |
| legendItem | .mantine-WaffleChart-legendItem | Legend item wrapper |
| legendSwatch | .mantine-WaffleChart-legendSwatch | Legend color swatch |
| legendLabel | .mantine-WaffleChart-legendLabel | Legend text label |

**WaffleChart CSS variables**

| Selector | Variable | Description |
|----------|----------|-------------|
| root | --waffle-cell-radius | Controls cell and legend swatch border radius |
| root | --waffle-empty-color | Controls empty cell background color |