> ## 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

## `ChartCollection`

`Excel.ChartCollection` of one worksheet.

Import from `@reductoai/xlsx/officejs`.

### ChartCollection properties

| Name | Type | Description |
| - | - | - |
| `count` | `number` | read-only |
| `items` | `ExcelChart[]` | read-only |

### `ChartCollection.add()`

```ts theme={null}
add(type: string, sourceData: string | ExcelRange, seriesBy?: string): ExcelChart
```

A chart of `type` over `sourceData`, laid out as Excel's Insert Chart does: labels in the
first row and columns name the series and categories. It sits one column right of the data.

### `ChartCollection.getCount()`

```ts theme={null}
getCount(): { value: number }
```

### `ChartCollection.getItem()`

```ts theme={null}
getItem(name: string): ExcelChart
```

### `ChartCollection.getItemAt()`

```ts theme={null}
getItemAt(index: number): ExcelChart
```

### `ChartCollection.getItemOrNullObject()`

```ts theme={null}
getItemOrNullObject(name: string): Nullable<ExcelChart>
```

## `ExcelChart`

`Excel.Chart`: a chart frame on a worksheet. Edits apply at once.

Import from `@reductoai/xlsx/officejs`.

### ExcelChart properties

| Name | Type | Description |
| - | - | - |
| `axes` | `ChartAxes` | read-only |
| `chartType` | `string` | The Excel.ChartType name of the first series: "ColumnClustered", "Pie", … |
| `dataLabels` | `ChartDataLabels` | read-only The data labels of every series at once; a read is null where the series differ. |
| `displayBlanksAs` | `ChartDisplayBlanksAs` | |
| `format` | `ChartAreaFormat` | read-only The chart area's fill, border and font; a 2016 chart type has no font. |
| `height` | `number` | |
| `id` | `string` | read-only |
| `left` | `number` | |
| `legend` | `ChartLegend \| ChartExLegend` | read-only |
| `name` | `string` | |
| `pivotOptions` | `ChartPivotOptions` | read-only |
| `plotArea` | `ChartPlotArea` | read-only On a 2016 chart type only `format` works. |
| `plotBy` | `ChartPlotBy` | Whether each series is a row or a column of the source; setting it plots the source again. |
| `plotVisibleOnly` | `boolean` | Hidden rows and columns drop out of the chart. |
| `series` | `ExcelChartSeriesCollection` | read-only On a 2016 chart type the handles carry a subset of members; the rest throw. |
| `showAllFieldButtons` | `boolean` | Every field button of a pivot chart at once: on when all four show. |
| `showDataLabelsOverMaximum` | `boolean` | |
| `style` | `number` | The chart style, 1 to 48; 2 when the chart names none. |
| `title` | `ExcelChartTitle \| ChartExTitle` | read-only |
| `top` | `number` | |
| `width` | `number` | |
| `worksheet` | `ExcelWorksheet` | read-only |

### `ExcelChart.activate()`

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

### `ExcelChart.delete()`

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

Removes the frame and its chart part; the handle stops working.

### `ExcelChart.getDataTable()`

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

### `ExcelChart.getDataTableOrNullObject()`

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

### `ExcelChart.set()`

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

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

### `ExcelChart.setData()`

```ts theme={null}
setData(sourceData: string | ExcelRange, seriesBy?: string): void
```

Plots `sourceData` again; the chart keeps its type, title and legend.

### `ExcelChart.setPosition()`

```ts theme={null}
setPosition(startCell: string | ExcelRange, endCell?: string | ExcelRange): void
```

Top-left at `startCell`; with `endCell`, the bottom-right at that cell's far corner.

## `ExcelChartSeriesCollection`

`Excel.ChartSeriesCollection`.

Import from `@reductoai/xlsx/officejs`.

### ExcelChartSeriesCollection properties

| Name | Type | Description |
| - | - | - |
| `count` | `number` | read-only |
| `items` | `ExcelChartSeries[]` | read-only |

### `ExcelChartSeriesCollection.add()`

```ts theme={null}
add(name?: string): ExcelChartSeries
```

An empty series; give it cells with `setValues`.

### `ExcelChartSeriesCollection.getCount()`

```ts theme={null}
getCount(): { value: number }
```

### `ExcelChartSeriesCollection.getItemAt()`

```ts theme={null}
getItemAt(index: number): ExcelChartSeries
```

## `ExcelChartSeries`

`Excel.ChartSeries`: the shared series handle plus Excel's range setters.

Import from `@reductoai/xlsx/officejs`.

### ExcelChartSeries 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. |
| `invertColor` | `string` | The fill of a negative point when `invertIfNegative` is on; "" when none is set. |
| `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` | A typed name replaces a reference to a cell, as in Excel. |
| `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, … |
| `plotOrder` | `number` | The position the series plots at in its chart group. |
| `secondPlotSize` | `number` | Pie of pie and bar of pie: second plot size, percent of the primary pie (5–200). |
| `showConnectorLines` | `boolean` | Only a waterfall series has connector lines. |
| `showLeaderLines` | `boolean` | The series' data labels' `showLeaderLines`. |
| `showShadow` | `boolean` | Whether the series casts an outer shadow. |
| `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. |

### `ExcelChartSeries.delete()`

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

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

### `ExcelChartSeries.getDimensionDataSourceString()`

```ts theme={null}
getDimensionDataSourceString(dimension: ChartSeriesDimension): ClientResult<string>
```

### `ExcelChartSeries.getDimensionDataSourceType()`

```ts theme={null}
getDimensionDataSourceType(
  dimension: ChartSeriesDimension,
): ClientResult<ChartDataSourceType>
```

### `ExcelChartSeries.getDimensionValues()`

```ts theme={null}
getDimensionValues(dimension: ChartSeriesDimension): ClientResult<string[]>
```

### `ExcelChartSeries.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`.

### `ExcelChartSeries.set()`

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

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

### `ExcelChartSeries.setBubbleSizes()`

```ts theme={null}
setBubbleSizes(sourceData: string | ExcelRange): void
```

A bubble series' sizes come from `sourceData`.

### `ExcelChartSeries.setName()`

```ts theme={null}
setName(sourceData: string | ExcelRange): void
```

Extension: the series name comes from a cell.

### `ExcelChartSeries.setValues()`

```ts theme={null}
setValues(sourceData: string | ExcelRange): void
```

The values come from `sourceData`.

### `ExcelChartSeries.setXAxisValues()`

```ts theme={null}
setXAxisValues(sourceData: string | ExcelRange): void
```

The categories, or a scatter's x values, come from `sourceData`.

## `ExcelChartTitle`

`Excel.ChartTitle`.

Import from `@reductoai/xlsx/officejs`.

### ExcelChartTitle properties

| Name | Type | Description |
| - | - | - |
| `format` | `ChartTitleFormat` | read-only |
| `horizontalAlignment` | `ChartTextHorizontalAlignment` | |
| `left` | `number \| undefined` | Points from the chart area's left edge; undefined while Excel places the title. |
| `overlay` | `boolean` | |
| `showShadow` | `boolean` | Whether the title casts an outer shadow. |
| `text` | `string` | |
| `textOrientation` | `number` | Degrees from -90 to 90, positive turning the text up; 180 stacks the letters. |
| `top` | `number \| undefined` | |
| `verticalAlignment` | `ChartTextVerticalAlignment` | |
| `visible` | `boolean` | |

### `ExcelChartTitle.delete()`

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

### `ExcelChartTitle.getSubstring()`

```ts theme={null}
getSubstring(start: number, length?: number): ChartFormatString
```

The font of `length` characters from `start` (to the end when omitted).

### `ExcelChartTitle.set()`

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

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

### `ExcelChartTitle.setFormula()`

```ts theme={null}
setFormula(formula: string): void
```

Shows a cell's text (`=Sheet1!$A$1`); a string without "=" is the title's own text.
