Charts
@office-open/core provides chart components shared by @office-open/docx and @office-open/pptx. Charts are defined using ChartSpaceOptions and serialized via chartSpaceDesc. Chart data is collected through ChartCollection.
Chart Types
The type property selects the chart kind:
| Type | Value | Description |
|---|---|---|
| Column | "column" | Vertical bars |
| Bar | "bar" | Horizontal bars |
| Line | "line" | Line series with optional markers |
| Pie | "pie" | Pie chart |
| Area | "area" | Filled area series |
| Scatter | "scatter" | XY scatter plot |
| Doughnut | "doughnut" | Doughnut / ring chart |
| Radar | "radar" | Radar / spider chart |
| Bubble | "bubble" | Bubble chart (requires xValues/yValues/bubbleSize) |
| Stock | "stock" | Stock chart (high-low-close) |
| Surface | "surface" | 3D surface chart |
Set threeD: true to render column, bar, line, pie, or area as 3D variants.
ChartSpaceOptions
ChartSpaceOptions is the options interface for a chart. It specifies the chart type, title, axes, and data:
import type { ChartSpaceOptions } from "@office-open/core";
const chartOptions: ChartSpaceOptions = {
title: "Revenue",
type: "bar",
categories: ["Q1", "Q2", "Q3", "Q4"],
series: [{ name: "2024", values: [10, 20, 30, 40] }],
};
Options
| Option | Type | Description |
|---|---|---|
type | ChartType | Chart type string (see above) |
categories | string[] | Category labels |
series | ChartSeriesData[] | BubbleSeriesData[] | Series data |
title | string | Chart title |
showLegend | boolean | Show legend (default: true) |
style | number | Style preset (2–48) |
threeD | boolean | Enable 3D rendering |
chartSpaceDesc
chartSpaceDesc is the CustomDescriptor<ChartSpaceOptions> that handles serialization and parsing of chart XML (c:chartSpace). It is used internally by the docx and pptx packages:
import { chartSpaceDesc } from "@office-open/core";
import { stringify, parse } from "@office-open/core/descriptor";
// Serialize chart options to XML
const xml = stringify(chartSpaceDesc, chartOptions, writeCtx);
// Parse chart XML back to options
const options = parse(chartSpaceDesc, chartElement, readCtx);
ChartCollection
ChartCollection manages multiple charts within a document or presentation. It stores ChartData entries keyed by ID:
import { ChartCollection } from "@office-open/core";
const charts = new ChartCollection();
charts.addChart("chart1", { key: "chart1", chartSpaceXml: xml });
ChartData
| Property | Type | Description |
|---|---|---|
key | string | Unique chart ID |
chartSpaceXml | string | Serialized chart XML |
Series Data
Each chart type accepts series data with category labels and values. Standard series use ChartSeriesData:
const series: ChartSeriesData[] = [
{ name: "Product A", values: [10, 20, 15] },
{ name: "Product B", values: [5, 12, 8] },
];
ChartSeriesData
| Option | Type | Description |
|---|---|---|
name | string | Series name |
values | number[] | Data values |
trendlines | TrendlineOptions[] | Trendlines for series |
errorBars | ErrorBarOptions | Error bars configuration |
dataLabels | DataLabelsOptions | Data labels configuration |
Bubble charts use BubbleSeriesData instead:
| Option | Type | Description |
|---|---|---|
name | string | Series name |
xValues | number[] | X coordinates |
yValues | number[] | Y coordinates |
bubbleSize | number[] | Bubble sizes |
Axes
Charts that use axes (bar, line, area, scatter) have axes created automatically based on chart type. Axis configuration is handled internally — category axis and value axis XML is generated during serialization.
Usage in Documents
Charts are typically created through the document/presentation API rather than directly. See:
- DOCX Charts for Word chart integration
- PPTX Charts for PowerPoint chart integration