# Boards

- Human documentation: [https://docs.univer.ai/reference/facade/boards](https://docs.univer.ai/reference/facade/boards)

- Agent Markdown: [https://docs.univer.ai/reference/facade/boards.md](https://docs.univer.ai/reference/facade/boards.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/boards.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/boards.mdx)

---

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

```ts
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): FBoard
getActiveBoard(): FBoard | null
getBoard(id: string): FBoard | null
```

```ts
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(): string
getName(): string
setName(name: string): this
getData(): IBoardData
save(): IBoardData
undo(): boolean
redo(): boolean
getSettings(): Required<IBoardSettings>
setSettings(settings: Partial<IBoardSettings>): boolean
getThemeData(): IBoardThemeData
setTheme(themeIdOrOptions: string | IBoardFacadeSetThemeOptions): boolean
beginImport(sourceType?: string): boolean
beginExport(targetType?: 'image' | 'pdf' | string): boolean
```

### Page background

```typescript
getBackground(): IBoardBackgroundData | undefined
setImageBackground(options: {
  source: string
  imageSourceType?: ImageSourceType
  fit?: 'cover' | 'contain' | 'stretch'
}): this
clearBackground(): this
```

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

```ts
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 | false
resolveCaptureBounds(options?: IBoardFacadeCaptureBoundsOptions): BoardCaptureBoundsResult | false
normalizeConnectorRouting(connectorIds: string[]): INormalizeBoardConnectorRoutingResult | false
analyzeRenderedLayout(focusPadding?: number): IBoardLayoutAnalysisResult | false
getScreenshot(options: IBoardScreenshotOptions): Promise<IBoardScreenshotResult | false>
getObjectListPanelOpen(): boolean
setObjectListPanelOpen(open: boolean): boolean
findElementsByText(query: string): IBoardElementFindResult[]
focusElement(elementId: string, viewportPoint: IBoardViewportPoint): boolean
getElementViewportPoint(elementId: string): IBoardViewportPoint | null
```

```ts
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>

// univerAPI
exportBoardByUnitIdAsync(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.

```ts
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.

```ts
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` |

```ts
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` |

## Related Facades

* [Shape](https://docs.univer.ai/reference/facade/shape.md) for live common Shape and Connector handles.
* [Chart](https://docs.univer.ai/reference/facade/chart.md) for Board chart APIs.
* [Mind Maps](https://docs.univer.ai/guides/boards/features/mind-maps.md) for structured mind-map insertion and reflow.
* [Print](https://docs.univer.ai/guides/boards/features/print.md) for Board printing and PNG/JPEG export.

Source: 

`@univerjs-pro/boards`