Charts

ScaiScribe emits charts in two ways: as native OOXML chart parts (so the recipient can double-click and edit chart data in Word/Excel/PowerPoint), or as rendered images (an ECharts-generated SVG embedded as an image). The right choice depends on the format, the chart kind, and your preference.

The chart element#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "type": "chart",
  "kind": "column",
  "title": "Quarterly revenue",
  "render_mode": "auto",
  "data": {
    "categories": ["Q1", "Q2", "Q3", "Q4"],
    "series": [
      { "name": "EMEA", "values": [1200, 1450, 1600, 1800] },
      { "name": "AMER", "values": [1000, 1100, 1300, 1400] }
    ]
  }
}

kind ∈ bar | column | line | area | pie | doughnut | scatter | bubble | radar | combo | stacked_bar | stacked_column | sankey | treemap | sunburst | heatmap | waterfall | gauge.

render_mode ∈ auto | native | image:

• auto (default) — native if the format + kind supports it; ECharts SVG fallback otherwise.
• native — force native. If the format+kind doesn't support it, you get a placeholder paragraph and a NATIVE_FALLBACK fidelity warning.
• image — force ECharts SVG. Useful when the native rendering disappoints visually (some kinds are markedly better in ECharts than in pptxgenjs).

Support matrix#

Native means: editable chart in the recipient's Office app. Series data lives inside the OOXML zip and survives round-trip through ingestion.

Image means: high-quality ECharts SVG rendered server-side, embedded as a normal image. Looks great, but the recipient can't edit the underlying data without re-rendering.

Why some kinds are native and others aren't#

Two factors:

1. What the underlying library supports natively. pptxgenjs covers most chart kinds via addChart. dolanmiu/docx and exceljs have no chart-write API at all, so the DOCX/XLSX "Native" cells above are hand-emitted OOXML — we write word/charts/chartN.xml (or xl/charts/chartN.xml + a drawing anchor) directly and patch them into the zip.
2. What's worth hand-emitting. Bar, column, line, pie cover most business documents. Hand-emitting every variant (area, doughnut, sankey, gauge, …) duplicates work ECharts already does. So we drew the line at the four high-traffic kinds; the rest fall through to the image fallback by design.

The image fallback isn't a placeholder. It's a real chart, themed with the document's chart_palette, rendered at native resolution. Visually you can't tell it from a native chart; the only difference is whether the recipient can double-click to edit data.

Theming#

Series colours come from the active theme's components.chart_palette. For native charts (DOCX/XLSX), the palette is passed through to the OOXML emitter as <a:srgbClr val="..."> on each series. For image charts, the palette is baked into the compiled ECharts theme that the SVG renderer consumes.

Override per-series colours by setting series[i].color. Override the title and axis colours via the optional axes and legend blocks (see Reference → API).

Data shapes by kind#

Most kinds use categorical data:

1

{ "categories": [...], "series": [{ "name": "...", "values": [...] }, ...] }

scatter and bubble use point data:

1

{ "series": [{ "name": "...", "points": [{ "x": 1, "y": 2 }, { "x": 3, "y": 4, "size": 5 }] }] }

Hierarchical kinds (sankey, treemap, sunburst) mirror ECharts' native option shape — see the ECharts docs and pass the option through verbatim.

Charts in PPTX slides#

Chart on a slide:

1
2
3
4
5
6
7

{
  "layout": "content",
  "elements": [
    { "type": "slide_title", "text": "Revenue" },
    { "type": "chart", "kind": "column", "title": "By region", "data": {...} }
  ]
}

Charts in PPTX honour their slide's layout: the chart sizes itself to fill the layout's content placeholder.

Charts in XLSX sheets#

Sheet charts anchor to a cell:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "charts": [
    {
      "anchor": "E2",
      "kind": "column",
      "title": "Sales",
      "data": {...}
    }
  ]
}

The chart spans 9 columns × 15 rows from the anchor (a reasonable default for an inline chart). Native-kind charts emit xl/charts/chartN.xml + xl/drawings/drawingN.xml; image-kind charts use exceljs.addImage to embed the SVG.

What happens on ingest#

When you ingest an external document containing charts:

• PPTX: the OOXML walker detects chart placeholders and emits a chart element where it can extract kind + data; otherwise emits an image element + a INGEST_CHART_REDUCED_TO_IMAGE warning.
• DOCX/XLSX: charts surface as image elements (mammoth/exceljs surface drawings as images on read). The original chart spec doesn't round-trip for externally-authored documents.
• ScaiScribe-authored documents: the JSON breadcrumb in the zip restores the full chart element exactly as authored — no information loss. See Ingestion.

Where to next#

• Tutorials → Charts — concrete examples for each kind.
• Themes — chart_palette and how it propagates.
• Reference → API — full Chart schema.