> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Charts

## `Chart`

A chart in a PowerPoint graphic frame. Read it with `Shape.getChart()`.

Import from `@reductoai/pptx/officejs`.

### Chart properties

| Name | Type | Description |
| - | - | - |
| `frameNoun` | `"shape"` | read-only What removing the whole chart means in this host: "paragraph", "shape". |
| `axes` | `ChartAxes` | read-only Excel.Chart.axes. |
| `categoryAxisTitle` | `string \| undefined` | The primary category-axis title the chart paints; undefined when the axis is absent, deleted, or untitled. Write "" or undefined to remove it. |
| `chartType` | `string` | read-only Plot families in document order, deduplicated: "bar", "bar+line" (combo). |
| `displayBlanksAs` | `ChartDisplayBlanksAs` | How blank cells plot: "NotPlotted" (a gap), "Zero" or "Interplotted" (joined). |
| `format` | `ChartAreaFormat` | read-only Excel.Chart.format: the chart area's fill, border and default font. |
| `legend` | `ChartLegend` | read-only Excel.Chart.legend. |
| `legendPosition` | `string` | Where the legend sits: bottom, top, left, right, topRight, or "none" when the chart has no legend. Writing creates the legend when absent; writing "none" removes it. |
| `plotArea` | `ChartPlotArea` | read-only Excel.Chart.plotArea. |
| `secondaryValueAxisMaximum` | `number \| undefined` | |
| `secondaryValueAxisMinimum` | `number \| undefined` | |
| `secondaryValueAxisTitle` | `string \| undefined` | The secondary value axis' title; refuses when no plot references one. |
| `series` | `HandleCollection<ChartSeries>` | read-only |
| `shapes` | `ChartShapes` | read-only Extension (VBA `Chart.Shapes`): text boxes, shapes and lines drawn on the chart. |
| `title` | `string \| undefined` | |
| `titleFormat` | `ChartTitleFormat` | read-only Extension (Excel's `chart.title.format`; `title` here is the text): the title's fill, border and font. The font lives on the title's own text, or its `c:txPr` while Word words it. |
| `valueAxisMaximum` | `number \| undefined` | |
| `valueAxisMinimum` | `number \| undefined` | The primary value axis' pinned minimum in data units; undefined = auto-scale. A pin crossing the other pinned end refuses. |
| `valueAxisTitle` | `string \| undefined` | The primary value-axis title; same contract as `categoryAxisTitle`. |

### `Chart.addSeries()`

```ts theme={null}
addSeries(options: AddSeriesOptions): ChartSeries
```

Append a series, modelled on the target plot's last one (axis wiring and
cache structure are cloned; the theme's accent cycle colours it). For a
combo chart, `plotKind` picks the family ("column", "line", …); default
is the first plot. Omitting `name` leaves the legend entry blank.

### `Chart.assertLive()`

```ts theme={null}
assertLive(): void
```

Throws when the frame left its part.

### `Chart.chartRoot()`

```ts theme={null}
chartRoot(): XElement
```

The live `c:chartSpace` root.

### `Chart.colorStyle()`

```ts theme={null}
colorStyle(): XElement | undefined
```

The chart's `cs:colorStyle` part; a host that keeps none reads as Excel's default.

### `Chart.detached()`

```ts theme={null}
detached(noun: string): Error
```

### `Chart.embeddedWorkbook()`

```ts theme={null}
embeddedWorkbook(): Uint8Array<ArrayBufferLike> | undefined
```

The workbook the chart embeds, as Edit Data opens it; undefined for a linked or missing one.

### `Chart.embedWorkbook()`

```ts theme={null}
embedWorkbook(bytes: Uint8Array): void
```

Embeds a workbook in a chart that has none; its references must already read it.

### `Chart.frameSizePt()`

```ts theme={null}
frameSizePt(): { height: number; width: number } | undefined
```

The frame's size in points, for plot-area geometry.

### `Chart.getDataTable()`

```ts theme={null}
getDataTable(): ChartDataTable
```

Excel.Chart.getDataTable(): throws when the chart type cannot show one.

### `Chart.getDataTableOrNullObject()`

```ts theme={null}
getDataTableOrNullObject(): ChartDataTable
```

Excel.Chart.getDataTableOrNullObject(): `isNullObject` when the chart type cannot show one.

### `Chart.keepingWorkbook()`

```ts theme={null}
keepingWorkbook(run: () => void): void
```

Runs an edit that leaves the data alone; the embedded workbook is not rebuilt for it.

### `Chart.linkedWorkbook()`

```ts theme={null}
linkedWorkbook(): string | undefined
```

The file the chart links its data to, when it lives outside the deck.

### `Chart.noteChange()`

```ts theme={null}
noteChange(): void
```

### `Chart.seal()`

```ts theme={null}
seal(handle: object): void
```

### `Chart.setColorStyle()`

```ts theme={null}
setColorStyle(root: XElement): void
```

### `Chart.setEmbeddedWorkbook()`

```ts theme={null}
setEmbeddedWorkbook(bytes: Uint8Array): void
```

Replaces the embedded workbook; save keeps it as it is.

### `Chart.styleAxisTitle()`

```ts theme={null}
styleAxisTitle(title: XElement): void
```

The look a new axis title takes: Office's 10pt grey on a styled chart.

### `Chart.textRef()`

```ts theme={null}
textRef(_formula: string): XElement | undefined
```

A `c:strRef` with its cache for a cell formula; a host without cells leaves it empty.

### `Chart.themePalette()`

```ts theme={null}
themePalette(): ThemePalette | undefined
```

## `ChartSeries`

Import from `@reductoai/pptx/officejs`.

### ChartSeries properties

| Name | Type | Description |
| - | - | - |
| `dataLabels` | `ChartDataLabels` | read-only |
| `format` | `ChartSeriesFormat` | read-only |
| `index` | `number` | read-only |
| `points` | `ChartPointsCollection` | read-only |
| `trendlines` | `ChartTrendlineCollection` | read-only |
| `xErrorBars` | `ChartErrorBars` | read-only |
| `yErrorBars` | `ChartErrorBars` | read-only |
| `axisGroup` | `"Primary" \| "Secondary"` | |
| `bubbleScale` | `number` | Bubble plots: bubble size as a percent of the default (0–300); plot-wide. |
| `bubbleSizes` | `(number \| null)[] \| undefined` | Extension: a bubble series' sizes, one per point; undefined for other families. Excel sets them from a range (`setBubbleSizes`). |
| `categories` | `(string \| null)[]` | Category labels from the cache; null is a blank cell. |
| `chartType` | `string` | Excel.ChartType name this series paints as: "ColumnStacked", "LineMarkers", … |
| `color` | `string \| undefined` | The color the series PAINTS as, canonical `#RRGGBB`: an area kind's fill or a stroke kind's line color — explicit `c:spPr` when present, else the theme accent the automatic cycle gives this series' position. Writing pins an explicit color (a line's separately-styled markers keep theirs). Pie-family charts color per slice and refuse this property. |
| `doughnutHoleSize` | `number` | Doughnut plots: hole diameter, percent (10–90). |
| `explosion` | `number` | Pie and doughnut series: how far slices pull out, percent of the radius. |
| `firstSliceAngle` | `number` | Pie and doughnut plots: angle of the first slice, degrees clockwise from 12 o'clock. |
| `gapWidth` | `number` | Bar plots: space between clusters, percent of a bar width; pie of pie: space between the two plots (0–500). |
| `hasDataLabels` | `boolean` | On shows values; off hides this series' labels even when the plot shows them. |
| `invertIfNegative` | `boolean` | Bar series: negative bars paint inverted. |
| `markerBackgroundColor` | `string \| undefined` | Marker fill, `#RRGGBB`; undefined is automatic. |
| `markerForegroundColor` | `string \| undefined` | Marker outline, `#RRGGBB`; undefined is automatic. |
| `markerSize` | `number \| undefined` | Marker size in points (2–72); undefined is automatic. |
| `markerStyle` | `ChartMarkerStyle` | |
| `name` | `string \| undefined` | |
| `onSecondaryAxis` | `boolean` | True when this series' plot is wired to a secondary value axis (a combo chart's % line, typically). `addSeries` clones the plot's wiring, so a series added to such a plot scales against that axis, not the primary. |
| `overlap` | `number` | Bar plots: overlap of bars in a cluster, percent (-100–100). |
| `plotKind` | `string` | read-only `c:*Chart` family this series is plotted as: bar, line, pie, … |
| `secondPlotSize` | `number` | Pie of pie and bar of pie: second plot size, percent of the primary pie (5–200). |
| `showLeaderLines` | `boolean` | The series' data labels' `showLeaderLines`. |
| `smooth` | `boolean` | Line and scatter series: a smoothed curve. |
| `splitType` | `"SplitByPosition" \| "SplitByValue" \| "SplitByPercentValue" \| "SplitByCustomSplit" \| undefined` | Pie of pie and bar of pie: how points move to the second plot; undefined while Word picks the split. |
| `splitValue` | `number \| undefined` | Pie of pie and bar of pie: the split threshold (a point count, value or percent, by splitType). |
| `values` | `(number \| null)[]` | Cached numeric values; null is a blank cell (not a zero). Scatter/bubble y values. |
| `varyByCategories` | `boolean` | One colour per point (`c:varyColors`); plot-wide. |
| `xValues` | `(number \| null)[] \| undefined` | A scatter/bubble series' numeric x values; undefined for category families (and for text-cached x values, plotted 1..N like categories). Category families refuse writes by name. |

### `ChartSeries.delete()`

```ts theme={null}
delete(): void
```

Remove this series from its plot. The handle is dead afterwards.

### `ChartSeries.moveTo()`

```ts theme={null}
moveTo(index: number): void
```

Move this series to chart-space position `index` (the order
`chart.series` lists). Paint stacking, legend order and the automatic
accent cycle follow. A series never changes plot families. The frozen
`index` snapshot does not renumber; re-read `chart.series`.

### `ChartSeries.set()`

```ts theme={null}
set(properties: ChartSeries | UpdateData<ChartSeries>, options?: UpdateOptions): void
```

Sets several properties at once; a navigation member takes a nested batch.

## `ChartAddOptions`

`addChart` options: the chart data plus the frame's box in points.

Import from `@reductoai/pptx/officejs`.

```ts theme={null}
type ChartAddOptions = Omit<ChartCreateSpec, "widthPt" | "heightPt"> & { height?: number; left?: number; top?: number; width?: number }
```
