Shapes
Shapes in Univer Sheets can be used to create flowcharts, annotations, callouts, and visual guides directly on worksheets.
Plugin Mode
Installation
pnpm add @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-uinpm install @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-uiyarn add @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-uibun add @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-uiShapes also require UniverProFormulaEnginePlugin from @univerjs-pro/engine-formula. Replace the existing UniverFormulaEnginePlugin import and registration in your base initialization with this plugin. Do not register both formula engines; otherwise, shape insertion can fail with a missing dependency error.
The shape plugins depend on the drawing plugins. You must also register UniverDrawingPlugin, UniverSheetsDrawingPlugin, UniverDrawingUIPlugin, and UniverSheetsDrawingUIPlugin before registering the shape plugins.
Usage
import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula'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(UniverProFormulaEnginePlugin)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.
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.
| Package | Desktop registration | Mobile registration |
|---|---|---|
@univerjs/drawing-ui | UniverDrawingUIPlugin | UniverDrawingMobileUIPlugin |
@univerjs/sheets-drawing-ui | UniverSheetsDrawingUIPlugin | UniverSheetsDrawingMobileUIPlugin |
@univerjs-pro/sheets-shape-ui | UniverSheetsShapeUIPlugin | UniverSheetsShapeMobileUIPlugin |
Preset Mode
The shape feature is included in the @univerjs/preset-sheets-advanced preset. This preset already registers UniverProFormulaEnginePlugin, so no manual formula engine replacement is needed.
Installation
The UniverSheetsAdvancedPreset preset from @univerjs/preset-sheets-advanced depends on the UniverSheetsDrawingPreset preset at runtime. Please install @univerjs/preset-sheets-drawing first.
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancednpm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedyarn add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedbun add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedUsage
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.
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.
import '@univerjs-pro/sheets-shape/facade'Insert Basic Shapes
Call FWorksheet.insertShape with common shape creation data. It returns a live facade handle.
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.')Edit shape text
Use the shape returned by insertShape() below or in the preceding example. getText() returns a live FShapeText handle. Read plain text with getPlainText(), replace the entire text with setText(), and format it with font, color and alignment methods.
if (!rectShape) throw new Error('Shape is not available')const shapeText = rectShape.getText()console.log(shapeText.getPlainText())shapeText .setText('Quarterly review') .setFontSize(18) .setColor('#2563eb') .setBold(true) .setHorizontalAlign(univerAPI.Enum.HorizontalAlign.CENTER) .setVerticalAlign(univerAPI.Enum.VerticalAlign.MIDDLE)setText() replaces the existing text; use setRichText() when you need multiple styles in one shape. To modify existing rich text, call getRichText()?.copy(), edit the builder, then pass it to setRichText(). Changes to that detached builder are not applied automatically. See text style and text box padding and layout for more options.
const richText = univerAPI.newRichText() .text('Quarterly ') .bold('review')shapeText.setRichText(richText)Insert and Connect Connector Shapes
Insert a connector with FWorksheet.insertShape, then bind its endpoints through the returned FConnectorShape facade.
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.
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)}Shape format painter
Select a shape, activate the format painter, then select the target shape. It copies fill, stroke, effects, and supported text formatting while keeping the target’s identity, geometry, text content, and formula bindings. Clear formatting restores insertion defaults. SmartArt is excluded. The corresponding shape UI plugin registers this behavior automatically.
How is this guide?