Web SDK

Charts

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

Plugin Mode

Shell
pnpm add @univerjs-pro/chart-ui @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui
TypeScript
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)

Mobile support

First configure the mobile editor. In this page’s plugin-mode setup, replace the desktop registrations below with their mobile exports from the same packages, before opening a document. Keep the model plugins, styles, locales and Facade imports; do not register both variants.

PackageDesktop registrationMobile registration
@univerjs-pro/sheets-chart-uiUniverSheetsChartUIPluginUniverSheetsChartMobileUIPlugin

Preset Mode

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

Shell
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
TypeScript
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()],})

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).

TypeScript
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.

TypeScript
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 for the shared builder configuration API.

Hidden data and independent categories

setPlotVisibleOnly(false) includes values from hidden rows and columns; use getPlotVisibleOnly() to inspect the setting. For sources with separate category columns, setSeriesToCategory() maps each value-field index to its category-field indexes. Indexes refer to the physical source vectors, not the filtered visible series. Missing entries inherit the shared categories; {} clears the overrides.

For example, with columns A:D, the value series in D can use C as its category while B keeps the shared category in A.

TypeScript
const chart = worksheet.getCharts()[0]if (!chart) throw new Error('No chart')chart.setPlotVisibleOnly(false)chart.setSeriesToCategory({ 3: [2] })

For aggregated interactive reports, see PivotCharts.

How is this guide?

© 2026 DreamNum Co., Ltd.