---
title: "Waffle Chart Image API — Icon-array part-to-whole | Imejis"
description: "Generate waffle / icon-array chart images — a grid of unit cells showing part-to-whole from a single percentage or category values. Fresh data per API call. Start free."
url: "https://www.imejis.io/components/waffle"
---

# Waffle Chart Image API — Icon-array part-to-whole | Imejis

A waffle / icon-array chart — part-to-whole shown as a grid of unit cells. Far more legible than a pie at social sizes, driven by a single percentage or a few category values.

## Use cases

- Goal / completion progress cards (68% funded)
- Survey and poll result graphics
- Market-share and composition snapshots
- Shareable "X in Y" stat images for social

## Authoring notes

- Single share: send `value` (0–100). Multi-category: send `data` [number, …] and `labels`.
- The grid is rows × columns (default 10 × 10 = 100 cells); each category fills a whole number of cells.
- shape "circle" makes an icon-array (dot-grid) look; showValue prints the % in the middle for single values.
- Use a roughly square box so the cells stay square.

## Properties

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `number[]` | `[]` | Category values; each fills a proportional share of the grid. |
| `value` | `number` | — | Single-category shorthand: percent (0–100) of the grid to fill. |
| `rows` | `number` (min 1) | `10` | Grid rows. |
| `columns` | `number` (min 1) | `10` | Grid columns (rows × columns = total cells). |
| `colors` | `color[]` | `[]` | One color per category (data) or [fill] for a single value. |
| `trackColor` | `color` | `"#e6e6e3"` | Empty / remainder cell color. |
| `labels` | `string[]` | `[]` | Category labels shown in the legend. |
| `showLegend` | `boolean` | `false` | Show the category legend. |
| `legendPosition` | `'top' \| 'right' \| 'bottom'` | `"bottom"` | Where the legend is placed. |
| `shape` | `'square' \| 'circle'` | `"square"` | Cell shape: square or circle (icon array). |
| `cellRadius` | `number` (min 0) | `2` | Corner radius for square cells (px). |
| `gap` | `number` (min 0) | `3` | Gap between cells (px). |
| `showValue` | `boolean` | `false` | Print the percentage in the middle (single value). |
| `valueColor` | `color` | `"#3f3f46"` | Center value / legend text color. |
| `opacity` | `number` | `1` | Overall component opacity from 0 (transparent) to 1 (opaque). |
| `borderWidth` | `number` | `0` | Border thickness in pixels around the component. |
| `borderColor` | `color` | `"transparent"` | Border color (any CSS color). |
| `borderStyle` | `'solid' \| 'dashed' \| 'dotted' \| 'double' \| 'none'` | `"solid"` | Border line style. |
| `borderRadius` | `number` | `0` | Corner radius in pixels. |
| `boxShadow` | `string` | — | CSS box-shadow applied to the component, e.g. "0 4px 6px rgba(0,0,0,0.1)". |

## Sample design JSON

```json
{
  "title": "Waffle sample",
  "description": "A single-value completion waffle",
  "dimensions": {
    "width": 800,
    "height": 420
  },
  "background": {
    "color": "#ffffff"
  },
  "components": [
    {
      "id": "sample-waffle",
      "key": "share",
      "type": "waffle",
      "position": {
        "x": 280,
        "y": 50
      },
      "rotation": 0,
      "size": {
        "width": 240,
        "height": 240
      },
      "dynamic": true,
      "properties": {
        "value": 68,
        "rows": 10,
        "columns": 10,
        "colors": [
          "#6366F1"
        ],
        "trackColor": "#e6e6e3",
        "shape": "square",
        "showValue": true,
        "opacity": 1
      }
    }
  ]
}
```

## Examples

### Goal completion

A single-value waffle at 68% with the number printed in the middle.

API overrides that reproduce this example:

```json
{
  "share.value": 68,
  "share.colors": [
    "#6366F1"
  ],
  "share.shape": "square",
  "share.showValue": true
}
```

### Market share split

Three categories filling the grid by share, with a legend.

API overrides that reproduce this example:

```json
{
  "share.data": [
    52,
    33,
    15
  ],
  "share.labels": [
    "Us",
    "Rival",
    "Other"
  ],
  "share.colors": [
    "#2563eb",
    "#f59e0b",
    "#a1a1aa"
  ],
  "share.showLegend": true
}
```

## API overrides

Push a fresh number per render with '<key>.value' (single percent) or '<key>.data' (category values); labels and colors are overridable too.

Flat override payload (`key.property` addressing) with the sample design's current values — send only the keys you want to change:

```json
{
  "share.value": 68,
  "share.rows": 10,
  "share.columns": 10,
  "share.colors": [
    "#6366F1"
  ],
  "share.trackColor": "#e6e6e3",
  "share.shape": "square",
  "share.showValue": true,
  "share.opacity": 1
}
```

```bash
curl --location 'https://render.imejis.io/v1/{{YOUR_DESIGN_ID}}' \
--header 'dma-api-key: {{YOUR_API_KEY}}' \
--header 'Content-Type: application/json' \
--data '{
    "share.value": 68,
    "share.rows": 10,
    "share.columns": 10,
    "share.colors": [
        "#6366F1"
    ],
    "share.trackColor": "#e6e6e3",
    "share.shape": "square",
    "share.showValue": true,
    "share.opacity": 1
}'
```

`{{YOUR_DESIGN_ID}}` and `{{YOUR_API_KEY}}` are placeholders: first create
the design in your account (paste the sample design JSON above into the
editor at https://app.imejis.io, or create it programmatically via the
imejis MCP server's `create_design` + `update_design` tools), then render
it with the design's id and one of your API keys.

Agents: the MCP server at https://api.imejis.io/api/mcp exposes this same
catalog as structured data via the `list_component_types` tool (property
kinds, allowed values, bounds, ready-to-use sample designs).

## Frequently Asked Questions

### How do I set the fill amount?

For a single share send '<key>.value' as a 0–100 percent. For multiple categories send '<key>.data' as an array of numbers plus '<key>.labels'.

### Can I change the grid size?

Yes — rows and columns set the grid (default 10 × 10 = 100 cells); each category fills a whole number of cells by its share.

### Can it look like an icon / dot array?

Set shape to "circle" for a dot-grid icon-array look; square (the default) gives the classic waffle.

## Variants

- [Icon array](https://www.imejis.io/components/waffle/icon-array.md) — Circular cells for a dot-grid "X in Y" icon-array look.
- [Dark](https://www.imejis.io/components/waffle/dark.md) — Bright cells on a dark canvas for social cards.

All components: https://www.imejis.io/components.md