Web SDK

Shapes

Shapes in Univer Sheets can be used to create flowcharts, annotations, callouts, and visual guides directly on worksheets.

Preview

Preset Mode

The shape feature is included in the @univerjs/preset-sheets-advanced preset.

Installation

The UniverSheetsAdvancedPreset preset from @univerjs/preset-sheets-advanced depends on the UniverSheetsDrawingPreset preset at runtime. Please install @univerjs/preset-sheets-drawing first.

Shell
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced

Usage

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-core/lib/index.css'import '@univerjs/preset-sheets-drawing/lib/index.css'import '@univerjs/preset-sheets-advanced/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      UniverPresetSheetsCoreEnUS,      UniverPresetSheetsDrawingEnUS,       UniverPresetSheetsAdvancedEnUS,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsDrawingPreset(),     UniverSheetsAdvancedPreset(),   ],})

If you have a commercial license for Univer, please refer to Using License in Client for configuration.

Plugin Mode

Installation

Shell
pnpm add @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-ui

The shape plugins depend on the drawing plugins. You must also register UniverDrawingPlugin, UniverSheetsDrawingPlugin, UniverDrawingUIPlugin, and UniverSheetsDrawingUIPlugin before registering the shape plugins.

Usage

TypeScript
import { UniverSheetsShapePlugin } from '@univerjs-pro/sheets-shape'import { UniverSheetsShapeUIPlugin } from '@univerjs-pro/sheets-shape-ui'import SheetsShapeUIEnUS from '@univerjs-pro/sheets-shape-ui/locale/en-US'import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { UniverDrawingPlugin } from '@univerjs/drawing'import { UniverDrawingUIPlugin } from '@univerjs/drawing-ui'import DrawingUIEnUS from '@univerjs/drawing-ui/locale/en-US'import { UniverSheetsDrawingPlugin } from '@univerjs/sheets-drawing'import { UniverSheetsDrawingUIPlugin } from '@univerjs/sheets-drawing-ui'import SheetsDrawingUIEnUS from '@univerjs/sheets-drawing-ui/locale/en-US'import '@univerjs-pro/sheets-shape/facade'import '@univerjs/drawing-ui/lib/index.css'import '@univerjs/sheets-drawing-ui/lib/index.css'import '@univerjs-pro/sheets-shape-ui/lib/index.css'const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DrawingUIEnUS,       SheetsDrawingUIEnUS,       SheetsShapeUIEnUS,     ),  },})univer.registerPlugin(UniverDrawingPlugin)univer.registerPlugin(UniverDrawingUIPlugin)univer.registerPlugin(UniverSheetsDrawingPlugin)univer.registerPlugin(UniverSheetsDrawingUIPlugin)univer.registerPlugin(UniverSheetsShapePlugin)univer.registerPlugin(UniverSheetsShapeUIPlugin)

If you have a commercial license for Univer, please refer to Using License in Client for configuration.

Facade API

Complete Facade API type definitions can be found in the FacadeAPI.

Importing

Plugin mode note

Only plugin mode requires manually importing the Facade package. Preset mode already includes the corresponding Facade package, so no extra import is needed.

TypeScript
import '@univerjs-pro/sheets-shape/facade'

Insert Basic Shapes

Call FWorksheet.insertShape with common shape creation data. It returns a live facade handle.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const rectShape = fWorksheet.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 120, top: 80, width: 240, height: 120 },  shapeData: {    fill: {      fillType: univerAPI.Enum.ShapeFillEnum.SolidFill,      color: '#e6f4ff',    },    stroke: {      lineStrokeType: univerAPI.Enum.ShapeLineTypeEnum.SolidLine,      color: '#1677ff',      width: 2,    },  },})if (!rectShape) throw new Error('Shape could not be inserted.')

Insert and Connect Connector Shapes

Insert a connector with FWorksheet.insertShape, then bind its endpoints through the returned FConnectorShape facade.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const leftShape = fWorksheet.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect,  transform: { left: 80, top: 80, width: 180, height: 100 },})const rightShape = fWorksheet.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Ellipse,  transform: { left: 420, top: 200, width: 180, height: 100 },})const connectorShape = fWorksheet.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.BentConnector3,  transform: { left: 240, top: 130, width: 240, height: 120 },})if (!leftShape || !rightShape || !connectorShape) {  throw new Error('Shapes could not be inserted.')}const startSite = leftShape.getConnectionSites()[0]const rightSites = rightShape.getConnectionSites()const endSite = rightSites[2] ?? rightSites[0]if (!startSite || !endSite) throw new Error('Connection site not found.')connectorShape  .bindStart(leftShape.getId(), startSite.index)  .bindEnd(rightShape.getId(), endSite.index)  .setEndArrow(univerAPI.Enum.ShapeArrowTypeEnum.Arrow)

Update and Remove Shapes

Update and remove a shape directly through its live facade handle.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const firstShape = fWorksheet.getShapes().find(shape => !shape.isConnectorShape())if (firstShape) {  firstShape    .setStrokeColor('#ff4d4f')    .setStrokeWidth(3)    .setSolidFill('#fff1f0')  // Remove the shape later if needed  const removed = firstShape.remove()  console.log(removed)}

How is this guide?

© 2026 DreamNum Co., Ltd.