# Board Elements

- Human documentation: [https://docs.univer.ai/guides/boards/model/board-elements](https://docs.univer.ai/guides/boards/model/board-elements)

- Agent Markdown: [https://docs.univer.ai/guides/boards/model/board-elements.md](https://docs.univer.ai/guides/boards/model/board-elements.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [boards/model/board-elements.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/boards/model/board-elements.mdx)

---

Board pages store drawable objects in `elements` and their visual order in `elementOrder`. Every element has a stable `id`, a `type`, and a `transform` describing its position and size on the canvas.

## Common element fields

| Field        | Type                       | Description                                                                                    |                               |
| ------------ | -------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------- |
| id           | `string`                   | Element id, unique within the page.                                                            |                               |
| type         | `BoardElementType`         | Element kind, such as `text`, `shape`, `image`, `connector`, `container`, `table`, or `group`. |                               |
| transform    | `IBoardElementTransform`   | Position, size, rotation, scale, skew, and flip values.                                        |                               |
| parentId?    | `string`                   | Parent container or group id.                                                                  |                               |
| laneId?      | `string`                   | Swimlane lane id when the element is inside a swimlane.                                        |                               |
| name?        | `string`                   | Human-readable element name.                                                                   |                               |
| description? | `string`                   | Accessibility or application metadata.                                                         |                               |
| visible?     | `boolean`                  | Whether the element should render.                                                             |                               |
| selectable?  | `boolean`                  | Whether the editor can select the element.                                                     |                               |
| locked?      | `boolean`                  | Whether editing is locked.                                                                     |                               |
| custom?      | \`Record\<string, unknown> | null\`                                                                                         | Application-defined metadata. |

## Element types

| Type        | Extra data                          | Typical use                                                    |
| ----------- | ----------------------------------- | -------------------------------------------------------------- |
| `text`      | `text`, `textStyle`, `textData`     | Sticky notes, labels, and rich text blocks.                    |
| `shape`     | `shapeData`                         | Rectangles, arrows, callouts, and custom shapes.               |
| `image`     | `source`, `imageSourceType`, `crop` | Embedded images.                                               |
| `connector` | `connectorData`                     | Lines and arrows attached to free points or shapes.            |
| `container` | `containerData`                     | Frames, areas, swimlanes, UML packages, and system boundaries. |
| `table`     | `tableId`                           | Board table elements provided by the table plugin.             |
| `chart`     | `chartId`                           | Chart elements.                                                |
| `media`     | `mediaType`, `source`               | Audio and video placeholders.                                  |
| `group`     | `children`                          | Grouped element collections.                                   |

## Containers

Containers define membership behavior with `containerData.behavior` and capture rules with `containerData.capturePolicy`. Use the facade container methods to move elements in and out so ordering and parent relationships stay consistent.

```ts
board.wrapElementsInContainer(['task-1', 'task-2'], {
  title: 'Sprint 1',
})
```

## Swimlanes

A swimlane is a container with `containerData.swimlane`. Lanes have stable ids, titles, order values, sizes, and optional collapsed state.

```ts
board.setSwimlaneLanes('lane-board', {
  orientation: 'horizontal',
  lanes: [
    { id: 'todo', title: 'Todo', order: 0, size: 240 },
    { id: 'doing', title: 'Doing', order: 1, size: 240 },
  ],
})
```

## Connectors

Connectors use endpoints and routing data. Endpoints can be free points, shape boundaries, connection sites, or lifelines. Prefer facade operations or UI actions for connector editing because routing data often depends on geometry.