# 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 cells. Each segment gets a number of cells proportional to its `value`:

```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 values fills the entire grid. Set `total` to a larger number to leave the remaining cells empty,
for example, to display progress towards a goal. A `total` smaller than the sum of values is ignored.
Use `emptyColor` to change the color of empty cells:

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

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


## Tooltip

Set `withTooltip` to display the segment name and value on cell hover. Use `getTooltipLabel` to change the tooltip content:

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

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

// 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

Use `legendPosition` to move the legend or set `withLegend={false}` to hide it.
Like `fillDirection`, `left` and `right` positions do not flip in right-to-left direction:

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

function Demo() {
  return <WaffleChart legendPosition="bottom" 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' },
];
```


## Gap and grid size

Use `rows` and `columns` props to change the number of cells, `gap` and `cellRadius` to change their spacing and border radius:

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

function Demo() {
  return <WaffleChart gap={2} cellRadius={0} columns={10} rows={10} 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' },
];
```


## 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 fillDirection="left-to-right" 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' },
];
```


## Value formatter

Use `valueFormatter` to format values and the total in the tooltip and in the label announced by screen readers:

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

function Demo() {
  return <WaffleChart data={data} withTooltip valueFormatter={(value) => `${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' },
];
```


## Accessibility

Set `aria-label` to summarize the chart in your own words:

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

function Demo() {
  return (
    <WaffleChart
      data={[{ name: 'Occupied', value: 75, color: 'blue' }]}
      total={100}
      aria-label="75 of 100 seats are occupied"
    />
  );
}
```


#### Props

**WaffleChart props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| cellRadius | number | 0 | Cell border radius, |
| columns | number | 10 | 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" | 'left-to-right' | Fill direction, |
| gap | number | 2 | Gap between cells in px, |
| getTooltipLabel | (cell: WaffleChartCell & { count: number; }) => ReactNode | - | Custom tooltip label formatter |
| legendPosition | "left" \| "right" \| "bottom" \| "top" | 'bottom' | Legend position, `left` and `right` are physical sides and do not flip in RTL, |
| rows | number | 10 | 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 |
| valueFormatter | (value: number) => string | - | Function to format values and the total in the default tooltip and the accessible label |
| withLegend | boolean | true | Whether to show legend, |
| withTooltip | boolean | false | 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 |

**WaffleChart data attributes**

| Selector | Attribute | Condition | Value |
|----------|-----------|-----------|-------|
| root | data-legend-position | `legendPosition` prop value, set when `withLegend` is true | - |
| root | data-vertical | `legendPosition` is left or right | - |
| cell | data-empty | Cell is not filled by any segment | - |
| cell | data-dimmed | A legend item of another segment is hovered | - |
| legendItem | data-dimmed | Another legend item is hovered | - |
