# Charts

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-sheets-advanced",
      "locale": "@univerjs/preset-sheets-advanced/locales/en-US",
      "style": "@univerjs/preset-sheets-advanced/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs-pro/chart-ui",
      "locale": "@univerjs-pro/chart-ui/locale/en-US",
      "style": "@univerjs-pro/chart-ui/lib/index.css"
    },
    {
      "client": "@univerjs-pro/sheets-chart",
      "locale": "@univerjs-pro/sheets-chart/locale/en-US",
      "facade": "@univerjs-pro/sheets-chart/facade"
    },
    {
      "client": "@univerjs-pro/sheets-chart-ui",
      "locale": "@univerjs-pro/sheets-chart-ui/locale/en-US",
      "style": "@univerjs-pro/sheets-chart-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

Charts visualize worksheet data with the chart model and UI packages.

> Interactive example: [Open the playground](/playground/sheets/charts)

## Preset Mode

The chart feature is included in `@univerjs/preset-sheets-advanced`. It requires the drawing preset at runtime.

#### npm

```bash
npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### bun

```bash
bun add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

```ts
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'
import UniverPresetSheetsAdvancedEnUS from '@univerjs/preset-sheets-advanced/locales/en-US'
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'
import UniverPresetSheetsDrawingEnUS from '@univerjs/preset-sheets-drawing/locales/en-US'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-advanced/lib/index.css'
import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css'

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsDrawingEnUS,
      UniverPresetSheetsAdvancedEnUS,
    ),
  },
  presets: [UniverSheetsCorePreset(), UniverSheetsDrawingPreset(), UniverSheetsAdvancedPreset()],
})
```

## Plugin Mode

#### npm

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

#### pnpm

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

#### yarn

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

#### bun

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

```ts
import ChartUIEnUS from '@univerjs-pro/chart-ui/locale/en-US'
import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart'
import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui'
import SheetsChartUIEnUS from '@univerjs-pro/sheets-chart-ui/locale/en-US'
import SheetsChartEnUS from '@univerjs-pro/sheets-chart/locale/en-US'
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

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

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(ChartUIEnUS, SheetsChartEnUS, SheetsChartUIEnUS),
  },
})

univer.registerPlugin(UniverSheetsChartPlugin)
univer.registerPlugin(UniverSheetsChartUIPlugin)
```

## Create and update charts

`worksheet.newChart(type)` creates a detached builder. Nothing is added to the worksheet until you build the chart information and pass it to `worksheet.insertChart(info)`.

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

const worksheet = workbook.getActiveSheet()
const info = worksheet
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource({
    range: 'A1:D6',
    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
  })
  .setPosition('F2')
  .setSize(640, 360)
  .setCategoryField(0)
  .setValueFields([1, 2, 3])
  .setTitle('Quarterly revenue')
  .build()

const chart = await worksheet.insertChart(info)
chart.setLegend({ visible: true }).bringToFront()

const updatedInfo = chart.toBuilder(univerAPI.Enum.ChartTypeString.Line).setSubtitle('FY 2026').build()
await chart.update(updatedInfo)

const svg = await chart.exportImage({ format: 'svg' })
```

Setters on the inserted `chart` update it immediately. Use `toBuilder(type)` with `update(info)` when you need a complete detached copy or want to change the chart type. `exportImage()` returns `undefined` when no UI renderer can provide an image.

Use `worksheet.getCharts()` and `worksheet.getChart(id)` to resolve live charts. Call `await chart.remove()` when you want to delete one, and register shared ECharts themes with `univerAPI.registerTheme(name, theme)`.

## Multi-level category axes

When adjacent source columns form a hierarchy, pass their zero-based indexes to `setCategoryFields()` in root-to-leaf order and enable the multi-level axis.

```ts
const info = worksheet
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource({
    range: 'A1:D7',
    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
  })
  .setCategoryFields([0, 1])
  .setMultiLevelCategoryAxis(true)
  .setValueFields([2, 3])
  .setPosition('F2')
  .build()

const chart = await worksheet.insertChart(info)
chart.setCategoryFields([0, 1]).setMultiLevelCategoryAxis(true)
```

Call `clearCategoryFields()` to remove the ordered mapping. `setMultiLevelCategoryAxis(false)` keeps the selected fields and only disables hierarchical rendering.

## Supported chart types

Use `univerAPI.Enum.ChartTypeString` for `Line`, `Column`, `ColumnStacked`, `ColumnPercentStacked`, `Bar`, `BarStacked`, `BarPercentStacked`, `Pie`, `Donut`, `Area`, `AreaStacked`, `AreaPercentStacked`, `Radar`, `Scatter`, `Combination`, `WordCloud`, `Funnel`, `Bubble`, `Relation`, `Waterfall`, `Pareto`, `Sankey`, `Heatmap`, `Boxplot`, `Candlestick`, `Histogram`, `Treemap`, `Sunburst`, `Gauge`, and `Chord`.

See the [Chart Facade reference](https://docs.univer.ai/reference/facade/chart.md) for the shared builder configuration API.