@univerjs-pro/engine-shape

Introduction

Engine Shape is the core shape definition and rendering engine for Univer. It provides 180+ preset shapes compatible with Excel/OOXML, covering basic shapes, arrows, flowcharts, callouts, connectors, and more. This package handles shape geometry computation, path rendering, fill/stroke styling, adjust points, connection sites, and connector routing.

Usage

Installation

# Using npm
npm install @univerjs-pro/engine-shape

# Using pnpm
pnpm add @univerjs-pro/engine-shape

Features

Preset Shapes

The library provides 180+ preset shape types organized into the following categories:

| Category | Examples | |---|---| | Basic Shapes | Rectangle, RoundRectangle, Ellipse, Diamond, Triangle, Hexagon, Octagon, Star, etc. | | Arrows | RightArrow, LeftArrow, UpArrow, BentArrow, CurvedArrow, StripedRightArrow, Chevron, etc. | | Flowcharts | Process, Decision, InputOutput, Document, Terminator, Preparation, ManualInput, etc. | | Callouts | WedgeRectCallout, WedgeEllipseCallout, CloudCallout, BorderCallout, AccentCallout, etc. | | Stars & Ribbons | Star4–Star32, Ribbon, EllipseRibbon, VerticalScroll, HorizontalScroll, Wave, etc. | | Math | MathPlus, MathMinus, MathMultiply, MathDivide, MathEqual, MathNotEqual | | Connectors | StraightConnector, BentConnector (2–5), CurvedConnector (2–5), Line | | Action Buttons | Home, Help, Information, Return, BackPrevious, ForwardNext, etc. | | Others | Cube, Can, Heart, Sun, Moon, SmileyFace, Cloud, Funnel, Gear, etc. |

Fill & Stroke

All shapes support three fill modes:

• No fill — transparent background.
• Solid fill — a single solid color.
• Gradient fill — linear or radial gradients.

Stroke styling is fully configurable, including color, width, dash patterns (solid, dash, dot, etc.), and line join/cap styles.

Text in Shapes

Most shapes support inline text editing via double-click. Rich text formatting is supported within shape text, including font size, color, bold, italic, and alignment.

Adjust Points

Adjust points provide parameterized editing of shape geometry. Each shape may have zero or more adjust points, which fall into the following types:

• XY adjust points — control position offsets along the X/Y axes.
• Angle adjust points — control angular parameters.
• Radius adjust points — control radial dimensions.

Adjust points can be manipulated through the UI (drag handles) or programmatically via API. For example, the SmileyFace shape has an adjust point that controls the mouth curvature — dragging it can turn a smile into a frown.

Connection Sites

Connection sites are predefined anchor points on a shape's boundary, used for snapping connectors. When a connector is attached to a connection site, moving the shape automatically updates the connector's path.

Connectors

Three connector line types are supported:

• Straight — a direct line between two points.
• Bent (elbow) — an orthogonal polyline with right-angle bends.
• Curved — a smooth Bezier curve.

All connectors feature:

• Auto-routing — automatically computes the optimal path around obstacles, similar to Excel.
• Shape binding — attach connector endpoints to connection sites on shapes; moving the shape updates the connector path automatically. Dragging the connector itself detaches it from the bound shape.
• Arrow heads — configurable start and end arrow styles.
• Dash styles — solid, dashed, dotted, and other dash patterns.
• Adjust points — fine-tune the connector path by dragging intermediate control points.