Boards

Packages	`@univerjs-pro/boards`, `@univerjs-pro/boards-ui`, `@univerjs-pro/boards-exchange-client`, `@univerjs-pro/boards-thread-comment`

Facade APIs for creating, querying, laying out, and editing an infinite Board page.

TypeScript

import '@univerjs-pro/boards/facade'import '@univerjs-pro/boards-ui/facade'import '@univerjs-pro/boards-exchange-client/facade'

Unit access

TypeScript

createBoard(data?: Partial<IBoardData>, options?: ICreateUnitOptions): FBoardgetActiveBoard(): FBoard | nullgetBoard(id: string): FBoard | null

TypeScript

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active Board')

Permissions

FBoard.getPermission() exposes unit-level Edit, Copy, Export, and Comment points. getElementPermission(elementId) returns the effective edit permission for a stable Board element.

TypeScript

import { UnitAction } from '@univerjs/protocol'await board.getPermission().setPoint(UnitAction.Export, false)await board.getElementPermission('shape-1').setReadOnly()

Thread comments

Import @univerjs-pro/boards-thread-comment/facade for element and free-position anchors:

TypeScript

import '@univerjs-pro/boards-thread-comment/facade'await board.createElementCommentAsync('shape-1', 'Review this Shape.')await board.createPositionCommentAsync({ x: 320, y: 180 }, 'Review this area.')const comments = await board.listCommentsAsync()

Use getElementComments() or listElementCommentsAsync() to scope results to one element.

Connector routing and animation

When endpoint sides and routing are omitted, connector insertion chooses facing sides and a space-aware persisted route. Animation is opt-in:

TypeScript

board.setConnectorStyle('connector-1', {  animation: { mode: 'gradient', direction: 'forward', speed: 1 },})board.setConnectorStyle('connector-1', { animation: null })

Supported modes are dash, particle, pulse, gradient, particles, and arrows. null disables animation; undefined preserves the current value.

FBoard

Unit and exchange

Category	Methods
Identity and data	`getId`, `getName`, `setName`, `getData`, `save`
History	`undo`, `redo`
Settings and theme	`getSettings`, `setSettings`, `getThemeData`, `setTheme`
Exchange UI	`beginImport`, `beginExport`

TypeScript

getId(): stringgetName(): stringsetName(name: string): thisgetData(): IBoardDatasave(): IBoardDataundo(): booleanredo(): booleangetSettings(): Required<IBoardSettings>setSettings(settings: Partial<IBoardSettings>): booleangetThemeData(): IBoardThemeDatasetTheme(themeIdOrOptions: string | IBoardFacadeSetThemeOptions): booleanbeginImport(sourceType?: string): booleanbeginExport(targetType?: 'image' | 'pdf' | string): boolean

Page background

TypeScript

getBackground(): IBoardBackgroundData | undefinedsetImageBackground(options: {  source: string  imageSourceType?: ImageSourceType  fit?: 'cover' | 'contain' | 'stretch'}): thisclearBackground(): this

setImageBackground() applies an image beneath all elements on the active page. getBackground() returns detached data.

TypeScript

board.setImageBackground({  source: 'https://example.com/background.jpg',  imageSourceType: univerAPI.Enum.ImageSourceType.URL,  fit: 'cover',})

Diagnostics, capture, and UI

The model APIs work without a renderer. The rendered-layout, screenshot, panel, search, and viewport APIs require @univerjs-pro/boards-ui/facade.

TypeScript

analyzeModelLayout(focusPadding?: number): IBoardLayoutAnalysisResult | falseresolveCaptureBounds(options?: IBoardFacadeCaptureBoundsOptions): BoardCaptureBoundsResult | falsenormalizeConnectorRouting(connectorIds: string[]): INormalizeBoardConnectorRoutingResult | falseanalyzeRenderedLayout(focusPadding?: number): IBoardLayoutAnalysisResult | falsegetScreenshot(options: IBoardScreenshotOptions): Promise<IBoardScreenshotResult | false>getObjectListPanelOpen(): booleansetObjectListPanelOpen(open: boolean): booleanfindElementsByText(query: string): IBoardElementFindResult[]focusElement(elementId: string, viewportPoint: IBoardViewportPoint): booleangetElementViewportPoint(elementId: string): IBoardViewportPoint | null

TypeScript

const analysis = board.analyzeModelLayout(48)if (analysis) {  const connectorIds = Array.from(new Set(analysis.issues.flatMap((issue) => issue.connectorIds)))  board.normalizeConnectorRouting(connectorIds)}

Exchange

TypeScript

insertMermaidAsync(code: string, options?: IBoardMermaidOptions): Promise<boolean>// univerAPIexportBoardByUnitIdAsync(unitId: string): Promise<File | undefined>exportBoardBySnapshotAsync(snapshot: IBoardData): Promise<File | undefined>transformSnapshotJsonToBoardDataAsync(json: ISnapshotBlockJsonResponse): Promise<IBoardData>transformBoardDataToSnapshotJsonAsync(boardData: IBoardData): Promise<ISnapshotBlockJson>

Query and geometry

Category	Methods
Elements	`getElement`, `getElements`, `getElementsByIds`, `findElements`, `getElementIdsInOrder`
Description	`describeElement`, `describeElements`, `describeElementsByIds`
Geometry	`getElementLayout`, `getElementBounds`, `getElementCenter`, `getElementGeometry`, `getElementsBoundsByIds`, `getElementsCentersByIds`, `getElementsGeometryByIds`, `getElementsGeometry`, `getElementsBoundingRect`, `getElementsBoundingRectByIds`
Validation	`checkElementIds`, `checkElementIdTypes`
Placement	`getNextAvailableBounds`, `resolveContainerAtPoint`, `resolveDropTargetAtPoint`
Metadata and order	`getElementMetadata`, `getElementsMetadataByIds`, `getElementOrder`
Containers	`getContainerChildren`, `getContainerDescendants`, `getElementParentChain`

Query methods return detached snapshots. Mutation methods below route through Board commands and participate in undo/redo and collaboration.

TypeScript

const cards = board.findElements({ elementTypes: [univerAPI.Enum.BoardElementType.Shape] })const bounds = board.getElementsBoundingRectByIds(cards.map((card) => card.id))

Insert elements

Method	Use
`insertText`	Insert a Board text element.
`insertImage`	Insert an image from a URL, UUID, or other supported source.
`insertShape`, `insertShapes`	Insert common Shape API objects and return live `FShape` / `FConnectorShape` handles.
`getShape`, `getShapes`	Resolve live common Shape handles.
`insertShapeAtPoint`	Place a Board-native shape at a coordinate and resolve its container or swimlane lane.
`insertConnector`, `insertConnectors`	Insert Board-native connectors with optional endpoint attachment.
`addElement`, `addElements`	Insert complete low-level `IBoardPageElement` snapshots.
`createContainer`, `createSwimlane`	Create semantic Board containers.

Prefer semantic insert methods over constructing raw page-element snapshots.

TypeScript

const shape = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect,  transform: { left: 80, top: 80, width: 180, height: 100 },  name: 'Review card',})if (!shape) throw new Error('Cannot insert shape')shape.getText().setText('Review')shape.setRotation(6)const sameShape = board.getShape(shape.getId())

insertShape() accepts the common IShapeCreateInput: geometry belongs under transform. Use insertShapeAtPoint() when you need Board-specific drop-target attachment or textBox options.

Transform and arrange

Category	Methods
Transform	`setElementTransform`, `setElementsTransform`, `translateElement`, `translateElements`
Alignment	`alignElements`, `distributeElements`
Layout	`arrangeElements`, `arrangeElementsInGrid`, `arrangeElementsInLayers`, `arrangeElementsInCircle`, `fitElementsIntoBounds`

TypeScript

const nodes = board.insertShapes([  { shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect, transform: { left: 80, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Diamond, transform: { left: 280, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 480, top: 80 } },])if (  !nodes ||  !board.arrangeElementsInLayers([[nodes[0].getId()], [nodes[1].getId()], [nodes[2].getId()]], {    direction: 'horizontal',    layerGap: 120,  }))  throw new Error('Cannot arrange nodes')

Content and connector APIs

Category	Methods
Metadata	`setElementMetadata`, `setElementsMetadata`
Text	`getTextContent`, `setTextContent`
Connector style	`getConnectorStyle`, `setConnectorStyle`
Connector label	`getConnectorLabelText`, `setConnectorLabelText`, `getConnectorLabelStyle`, `setConnectorLabelStyle`, `removeConnectorLabel`
Connector endpoints	`getConnectorConnection`, `setConnectorConnection`
Container style	`getContainerStyle`, `setContainerStyle`

Order, update, and removal

Category	Methods
Z-order	`reorderElements`, `bringElementsToFront`, `bringElementsForward`, `sendElementsBackward`, `sendElementsToBack`
Update	`updateElement`
Remove	`removeElement`, `removeElements`

Containers and swimlanes

Category	Methods
Membership	`wrapElementsInContainer`, `reparentElements`, `moveElementsToContainer`, `moveElementsOutOfContainer`, `disbandContainer`
Container behavior	`fitContainerToContent`, `setContainerMembershipLocked`, `setContainerAutoResize`
Swimlanes	`setSwimlaneLanes`, `setSwimlaneLaneSize`, `addSwimlaneLane`, `removeSwimlaneLane`, `reorderSwimlaneLane`, `setSwimlaneLaneCollapsed`, `renameSwimlaneLane`

Shape for live common Shape and Connector handles.
Chart for Board chart APIs.
Mind Maps for structured mind-map insertion and reflow.
Print for Board printing and PNG/JPEG export.

Source: @univerjs-pro/boards

How is this guide?