Shapes

The shape feature allows you to insert and edit shapes and drawings within a document, including basic geometric shapes, arrows, and flowchart elements.

Introduction

In Univer Docs, shapes enable you to:

• Insert geometric shapes: Add rectangles, circles, arrows, and more.
• Customize appearance: Adjust fill colors, borders, and text.
• Position freely: Place shapes anywhere in the document.

Plugin Mode

Installation

pnpm add @univerjs-pro/engine-formula @univerjs-pro/docs-shape @univerjs-pro/docs-shape-ui

npm install @univerjs-pro/engine-formula @univerjs-pro/docs-shape @univerjs-pro/docs-shape-ui

yarn add @univerjs-pro/engine-formula @univerjs-pro/docs-shape @univerjs-pro/docs-shape-ui

bun add @univerjs-pro/engine-formula @univerjs-pro/docs-shape @univerjs-pro/docs-shape-ui

Usage

import { UniverDocsShapePlugin } from '@univerjs-pro/docs-shape'import { UniverDocsShapeUIPlugin } from '@univerjs-pro/docs-shape-ui'import DocsShapeUIEnUS from '@univerjs-pro/docs-shape-ui/locale/en-US'import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula'import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import '@univerjs-pro/docs-shape-ui/lib/index.css'const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DocsShapeUIEnUS,     ),  },})univer.registerPlugin(UniverProFormulaEnginePlugin)univer.registerPlugin(UniverDocsShapePlugin)univer.registerPlugin(UniverDocsShapeUIPlugin)

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.

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.

import '@univerjs-pro/docs-shape/facade'const document = univerAPI.getActiveDocument()const paragraph = document?.getParagraphs()[0]if (!document || !paragraph) throw new Error('No active document paragraph')const shape = document.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  placement: {    wrappingStyle: univerAPI.Enum.TextWrappingStyle.INLINE,    anchor: { paragraphId: paragraph.getId(), segmentId: paragraph.getSegmentId() },  },})if (!shape) throw new Error('Shape is not available')const shapeText = shape.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)

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.