Shapes

Univer Pro

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

Playground

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

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

Usage

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

npm install @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-ui

Usage

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 '@univerjs-pro/sheets-shape/facade'

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

const univer = new Univer({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      SheetsShapeUIEnUS, 
    ),
  },
})

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

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

Use FWorksheet.newShape to create a shape builder, then call FWorksheet.insertShape to insert it.

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

const rectShape = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setPosition(1, 1, 0, 0)
  .setWidth(240)
  .setHeight(120)
  .setShapeSolidFill('#e6f4ff')
  .setStrokeColor('#1677ff')
  .setStrokeWidth(2)
  .build()

await fWorksheet.insertShape(rectShape)

Insert and Connect Connector Shapes

Use FWorksheet.newConnector to create connector lines, and FWorksheet.connectShapes to attach both ends to shape connection sites.

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

const leftShape = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.RoundRect)
  .setPosition(1, 1, 0, 0)
  .setWidth(180)
  .setHeight(80)
  .setShapeSolidFill('#f6ffed')
  .setStrokeColor('#52c41a')
  .build()
await fWorksheet.insertShape(leftShape)

const rightShape = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Diamond)
  .setPosition(1, 5, 0, 0)
  .setWidth(180)
  .setHeight(120)
  .setShapeSolidFill('#fffbe6')
  .setStrokeColor('#faad14')
  .build()
await fWorksheet.insertShape(rightShape)

const connector = fWorksheet.newConnector()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.StraightConnector1)
  .setPosition(2, 3, 0, 0)
  .setWidth(220)
  .setHeight(40)
  .setStartArrowType(univerAPI.Enum.ShapeArrowTypeEnum.Arrow)
  .setEndArrowType(univerAPI.Enum.ShapeArrowTypeEnum.Arrow)
  .setStrokeColor('#595959')
  .setStrokeWidth(2)
  .build()
await fWorksheet.insertShape(connector)

const shapes = fWorksheet.getShapes()
const basicShapes = shapes.filter(shape => !shape.isLineShape())
const connectorShape = shapes.find(shape => shape.isLineShape())

if (connectorShape && basicShapes.length >= 2) {
  await fWorksheet.connectShapes({
    connector: connectorShape,
    startTarget: { shape: basicShapes[0], connectionSiteIndex: 0 },
    endTarget: { shape: basicShapes[1], connectionSiteIndex: 2 },
  })
}

Update and Remove Shapes

Use FWorksheet.updateShape to update an existing shape and FWorksheet.removeShape to remove it.

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

const shapes = fWorksheet.getShapes()
const firstShape = shapes.find(shape => !shape.isLineShape())

if (firstShape) {
  const updatedShape = fWorksheet.newShape(firstShape)
    .setStrokeColor('#ff4d4f')
    .setStrokeWidth(3)
    .setShapeSolidFill('#fff1f0')
    .build()

  await fWorksheet.updateShape(updatedShape)

  // Remove the shape after update if needed
  await fWorksheet.removeShape(firstShape)
}

FShape: shape builder and shape instance methods.
FConnectorShape: connector-specific methods (arrow and relation data).
FShapeEnum: shape-related enums exposed on univerAPI.Enum.
FWorksheetShapeMixin: worksheet-level shape operations.

Table of Contents