---
title: "Gantt Chart Image API — Roadmap & timeline images | Imejis"
description: "Generate Gantt / timeline chart images — tasks as bars across a time axis with progress fills — for roadmaps, project status and schedules. Fresh data on every API call. Start free with Imejis."
url: "https://www.imejis.io/components/gantt"
---

# Gantt Chart Image API — Roadmap & timeline images | Imejis

A Gantt / timeline chart — horizontal bars across a shared time axis, one per task, with optional progress fills. Key each task by { label, start, end } and swap the data on every API call to build roadmap, project-status and schedule images.

## Use cases

- Product roadmaps and release timelines
- Project and sprint status for reports
- Schedules and plans in slides and emails
- Content and campaign calendars
- Year-in-review and milestone graphics

## Authoring notes

- data is [{ label, start, end }] — start/end are ISO dates ("2026-01-15") or plain numbers (day/week index); mixing is fine but pick one per chart.
- Give each task a progress (0–100) to draw a filled portion of its bar; leave it off for a plain bar.
- Set a per-task color to group bars by workstream or owner; otherwise every bar uses barColor.
- Use a wide box (~2:1) and keep task labels short — the label column takes rowLabelWidth of the width.
- Tasks render top-to-bottom in data order, so sort by start date before sending if you want a staircase.

## Properties

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `object[]` | `[]` | Tasks: array of { label, start, end, color?, progress? }. start/end are ISO dates ("2026-01-15") or numbers. |
| `barColor` | `color` | `"#4f46e5"` | Default bar fill. |
| `barRadius` | `number` (min 0) | `4` | Bar corner radius (px). |
| `showProgress` | `boolean` | `true` | Draw the completed portion of a bar from each task's `progress`. |
| `showGrid` | `boolean` | `true` | Draw vertical time gridlines. |
| `gridColor` | `color` | `"#e5e7eb"` | Gridline color. |
| `labelColor` | `color` | `"#334155"` | Task-label + axis text color. |
| `axisColor` | `color` | `"#94a3b8"` | Time-axis line and tick color. |
| `rowLabelWidth` | `number` (min 0, max 0.6) | `0.26` | Fraction of width reserved for the task-label column (0–0.6). |
| `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": "Gantt sample",
  "description": "A project timeline with progress bars",
  "dimensions": {
    "width": 860,
    "height": 420
  },
  "background": {
    "color": "#ffffff"
  },
  "components": [
    {
      "id": "sample-gantt",
      "key": "gantt",
      "type": "gantt",
      "position": {
        "x": 20,
        "y": 20
      },
      "rotation": 0,
      "size": {
        "width": 820,
        "height": 380
      },
      "dynamic": true,
      "properties": {
        "data": [
          {
            "label": "Research",
            "start": "2026-01-05",
            "end": "2026-01-23",
            "progress": 100
          },
          {
            "label": "Design",
            "start": "2026-01-19",
            "end": "2026-02-13",
            "progress": 100
          },
          {
            "label": "Build",
            "start": "2026-02-09",
            "end": "2026-03-27",
            "progress": 55
          },
          {
            "label": "QA",
            "start": "2026-03-16",
            "end": "2026-04-10",
            "progress": 20
          },
          {
            "label": "Launch",
            "start": "2026-04-06",
            "end": "2026-04-17",
            "progress": 0
          }
        ],
        "barColor": "#4f46e5",
        "barRadius": 4,
        "showProgress": true,
        "showGrid": true,
        "opacity": 1
      }
    }
  ]
}
```

## Examples

### Product launch plan

Five phases with progress, from research to launch.

API overrides that reproduce this example:

```json
{
  "gantt.data": [
    {
      "label": "Research",
      "start": "2026-01-05",
      "end": "2026-01-23",
      "progress": 100
    },
    {
      "label": "Design",
      "start": "2026-01-19",
      "end": "2026-02-13",
      "progress": 100
    },
    {
      "label": "Build",
      "start": "2026-02-09",
      "end": "2026-03-27",
      "progress": 55
    },
    {
      "label": "QA",
      "start": "2026-03-16",
      "end": "2026-04-10",
      "progress": 20
    },
    {
      "label": "Launch",
      "start": "2026-04-06",
      "end": "2026-04-17",
      "progress": 0
    }
  ],
  "gantt.barColor": "#4f46e5"
}
```

### Roadmap in teal

The same plan in a single teal hue.

API overrides that reproduce this example:

```json
{
  "gantt.data": [
    {
      "label": "Research",
      "start": "2026-01-05",
      "end": "2026-01-23",
      "progress": 100
    },
    {
      "label": "Design",
      "start": "2026-01-19",
      "end": "2026-02-13",
      "progress": 100
    },
    {
      "label": "Build",
      "start": "2026-02-09",
      "end": "2026-03-27",
      "progress": 55
    },
    {
      "label": "QA",
      "start": "2026-03-16",
      "end": "2026-04-10",
      "progress": 20
    },
    {
      "label": "Launch",
      "start": "2026-04-06",
      "end": "2026-04-17",
      "progress": 0
    }
  ],
  "gantt.barColor": "#0d9488"
}
```

## API overrides

Push fresh tasks per render with '<key>.data' (or just '<key>') as [{ label, start, end, progress? }]; start/end are ISO dates or numbers, and the timeline re-lays-out to fit.

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

```json
{
  "gantt.data": [
    {
      "label": "Research",
      "start": "2026-01-05",
      "end": "2026-01-23",
      "progress": 100
    },
    {
      "label": "Design",
      "start": "2026-01-19",
      "end": "2026-02-13",
      "progress": 100
    },
    {
      "label": "Build",
      "start": "2026-02-09",
      "end": "2026-03-27",
      "progress": 55
    },
    {
      "label": "QA",
      "start": "2026-03-16",
      "end": "2026-04-10",
      "progress": 20
    },
    {
      "label": "Launch",
      "start": "2026-04-06",
      "end": "2026-04-17",
      "progress": 0
    }
  ],
  "gantt.barColor": "#4f46e5",
  "gantt.barRadius": 4,
  "gantt.showProgress": true,
  "gantt.showGrid": true,
  "gantt.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 '{
    "gantt.data": [
        {
            "label": "Research",
            "start": "2026-01-05",
            "end": "2026-01-23",
            "progress": 100
        },
        {
            "label": "Design",
            "start": "2026-01-19",
            "end": "2026-02-13",
            "progress": 100
        },
        {
            "label": "Build",
            "start": "2026-02-09",
            "end": "2026-03-27",
            "progress": 55
        },
        {
            "label": "QA",
            "start": "2026-03-16",
            "end": "2026-04-10",
            "progress": 20
        },
        {
            "label": "Launch",
            "start": "2026-04-06",
            "end": "2026-04-17",
            "progress": 0
        }
    ],
    "gantt.barColor": "#4f46e5",
    "gantt.barRadius": 4,
    "gantt.showProgress": true,
    "gantt.showGrid": true,
    "gantt.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 pass the tasks?

Send '<key>.data' as an array of { label, start, end } objects, with an optional progress (0–100) and color per task. start and end are ISO dates like "2026-01-15" or plain numbers; the timeline scales to fit.

### Can bars show progress?

Yes. Give a task a progress from 0 to 100 and the bar draws a filled portion for the completed part over a lighter track. Leave progress off and the bar is a solid block.

### Do I have to use dates?

No. start and end can be ISO date strings for a real calendar axis, or plain numbers (like a day or week index) for a generic timeline. The axis labels adapt to which you use.

### Can I color bars by workstream or owner?

Yes. Add a color to any task and that bar uses it; tasks without a color fall back to barColor. It is an easy way to group a plan by team, owner or phase.

## Variants

- [By workstream](https://www.imejis.io/components/gantt/workstream.md) — Per-task colors to group a plan by team, owner or phase.
- [Dark](https://www.imejis.io/components/gantt/dark.md) — A timeline on a dark card with bright bars — built for social.

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