# Pivot Charts

- Human documentation: [https://docs.univer.ai/guides/sheets/features/pivot-chart](https://docs.univer.ai/guides/sheets/features/pivot-chart)

- Agent Markdown: [https://docs.univer.ai/guides/sheets/features/pivot-chart.md](https://docs.univer.ai/guides/sheets/features/pivot-chart.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0`

- Source: [sheets/features/pivot-chart.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/pivot-chart.mdx)

---

Register the [PivotTable](https://docs.univer.ai/guides/sheets/features/pivot-table.md) and [chart](https://docs.univer.ai/guides/sheets/features/charts.md) dependencies, then add the two plugins below before creating the workbook. Merge the UI locale into your `locales` configuration and load its stylesheet. A Pro license is required.

#### npm

```bash
npm install @univerjs-pro/sheets-pivot-chart @univerjs-pro/sheets-pivot-chart-ui
```

#### pnpm

```bash
pnpm add @univerjs-pro/sheets-pivot-chart @univerjs-pro/sheets-pivot-chart-ui
```

#### yarn

```bash
yarn add @univerjs-pro/sheets-pivot-chart @univerjs-pro/sheets-pivot-chart-ui
```

#### bun

```bash
bun add @univerjs-pro/sheets-pivot-chart @univerjs-pro/sheets-pivot-chart-ui
```

```ts
import { UniverSheetsPivotChartPlugin } from '@univerjs-pro/sheets-pivot-chart'
import { UniverSheetsPivotChartUIPlugin } from '@univerjs-pro/sheets-pivot-chart-ui'
import SheetsPivotChartLocale from '@univerjs-pro/sheets-pivot-chart-ui/locale/en-US'
import { LocaleType } from '@univerjs/core'

import '@univerjs-pro/sheets-pivot-chart/facade'
import '@univerjs-pro/sheets-pivot-chart-ui/lib/index.css'

univerAPI.loadLocales(LocaleType.EN_US, SheetsPivotChartLocale)

univer.registerPlugin(UniverSheetsPivotChartPlugin)
univer.registerPlugin(UniverSheetsPivotChartUIPlugin)
```

The advanced Sheets preset already includes both plugins. Use it with the core and drawing presets, and import `@univerjs-pro/sheets-pivot-chart/facade` explicitly for these APIs.

## Independent report

This chart owns its report. Add a row field and a value field after insertion; the example uses the first two source columns.

```ts
const workbook = univerAPI.getActiveWorkbook()
const sheet = workbook?.getActiveSheet()
if (!sheet) throw new Error('No active worksheet')

sheet.getRange('A1:B4').setValues([
  ['Region', 'Sales'], ['East', 100], ['West', 200], ['East', 50],
])
const chart = await sheet.insertPivotChart(
  sheet.newPivotChart(univerAPI.Enum.ChartTypeString.Column)
    .setSource('A1:B4').setPosition('D2').setSize(640, 360).build(),
)
const fields = chart.getSourceFieldsInfo()
await chart.addField(fields[0].id, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0)
await chart.addField(fields[1].id, univerAPI.Enum.PivotTableFiledAreaEnum.Value, 0)
```

## Link to a PivotTable

Field, filter, sort, and collapse edits are shared with the referenced PivotTable and its other linked charts. Appearance and position remain independent. Removing the chart keeps the table; removing the table makes the chart unavailable until the same table is restored.

```ts
const pivotTable = workbook.getPivotTableById('pivot-table-1')
if (!pivotTable) throw new Error('PivotTable not found')

const linkedChart = await sheet.insertPivotChart(
  pivotTable.newChart(univerAPI.Enum.ChartTypeString.Line).setPosition('D22').build(),
)
linkedChart.setFieldButtonsVisible(true).setExpandCollapseButtonsVisible(true)
```

## Supported types and Worker

Line, column, bar, area, pie, doughnut, and combination types are supported, including stacked variants where available. Scatter, bubble, radar, and waterfall types are not supported. Pie uses the first value series; doughnut keeps multiple series. Subtotals and grand totals are excluded from chart categories.

With a [Worker](https://docs.univer.ai/guides/sheets/getting-started/worker.md), use `UniverSheetsAdvancedPreset({ useWorker: true })` on the main thread and `UniverSheetsAdvancedWorkerPreset()` in the Worker. Plugin-mode details are in the [package reference](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-pivot-chart.md#worker-calculation). See [FSheetPivotChart](https://docs.univer.ai/reference/facade/sheet-pivot-chart.md) for field, filter, style, and lifecycle APIs.