MindmapNode

Mindmap.MindmapNode

Experimental feature Experimental

MindmapNode

Represents a mind map node on a board.

// Create mind map root node
const root = await miro.board.experimental.createMindmapNode({
  nodeView: {
    content: '<p>Mind map root node.</p>',
  },
  x: -300,
  y: 400,
});

// Create mind map child node A
const childA = await miro.board.experimental.createMindmapNode({
  nodeView: {
    content: '<p>Mind map child node A.</p>',
  },
  x: -300,
  y: 400,
});

// Create mind map child node B
const childB = await miro.board.experimental.createMindmapNode({
  nodeView: {
    content: '<p>Mind map child node B.</p>',
  },
  x: 300,
  y: 400,
});

// Add  node A and node B as child nodes to the root node
await root.add(childA);
await root.add(childB);

// Output the mind map nodes to the developer console
console.log(root, childA, childB);

MindmapNode item
Figure 1. MindmapNode item.

Table of contents

Properties

Methods

Properties

type

Readonly type: "mindmap_node"

Experimental feature Experimental

Defines the type of item.
Item type is useful to retrieve specific items from a board.

Example:

// Get all mind map nodes from the board
const items = await miro.board.experimental.get({type: 'mindmap_node'});

// Output to the console the total number of mind map nodes
console.log(`The current board has ${items.length} mind map nodes.`);

Overrides

BaseItem.type


nodeView

nodeView: MindmapNodeView

This property represents the visual representation of the node.

Currently, we support two types of node views -- text and shape:

Text

await miro.board.experimental.createMindmapNode({
  nodeView: {
    type: 'text',
    content: 'Hello world',
  },
});

type

type: text

Node view type

content

content: string

Text content for the mind map node

Shape

await miro.board.experimental.createMindmapNode({
  nodeView: {
    type: 'text',
    content: 'Hello world',
  },
});

type

type: shape

Node view type

content

content: string

Text content for the mind map node

shape

shape: 'pill' | 'rectangle' | 'round_rectangle'

The visual shape of the mind map node displayed on a board.

style: `Object``

color

Hex value representing the color of the node.

fillOpacity

fillOpacity works similarly to the opacity property in CSS.
It sets the opacity level of the background fill color defined in the fillColor property of the board item.

Allowed values: any number between 0.0 and 1.0 included.

  • If the value is 0.0, the background fill color is completely transparent or invisible.
  • If the value is 1.0, the background fill color is completely opaque or solid.

Default: 0.0 (transparent)


width

width: number

Width of the item in dp.

See also:


layout

layout: "vertical" | "horizontal"

Indicates the layout of the mind map.

Layout accepts two properties: vertical and horizontal.

Layout can only be set for the root mind map node. For all other nodes, the layout property is always read-only.


direction

direction: undefined | "start" | "end"

Indicates the current direction of the mind map node relative to the root node.

Direction accepts two values: start and end. The direction value's representation changes based on the layout of the mind map:

  • When the layout is horizontal, start represents the left and end represents the right side of the mind map root node.
  • When the layout is vertical, start represents the top and end represents the bottom side of the mind map root node.

direction property can only be set for immediate children of the root node. This property is read-only for all other child nodes, and is undefined for the root mind map node.


height

Readonly height: number

Height of the item in dp.

See also:


childrenIds

Readonly childrenIds: string[]

An array of unique identifiers.
The IDs represent child items inside an item.
You can programmatically retrieve child items inside a parent item by specifying their ID.

The children can be only be of type mindmap_node

ℹ️ Note:


isRoot

Readonly isRoot: boolean

Determines if a mindmap node is a root node or not.

  • If value is true, the mindmap node is root node.
  • If value is false, the mindmap node is descendant node

id

Readonly id: string

Unique ID of the item, assigned automatically upon creation.

Example: 3658432978520043388


origin

origin: "center"

origin marks:

  • The positioning reference point of a board item.
    This is the point used to calculate the x and y coordinates of an item when it's positioned on the board, or when it's a child inside a parent item.
  • The rotation pivot point of a board item that supports rotation.

origin accepts only one value: center.
Any other value throws an error.


relativeTo

relativeTo: RelativeTo

The relativeTo property affects the x and y coordinate values of a board item.
relativeTo defines the positioning reference of a board item, which can be:

Depending on whether an item is a child of a parent item or not, relativeTo can have one of the following values:

ValueDescriptionOn the board UI
canvas_centerThe item is positioned on the board, and it's not a child of another item.
The x and y coordinate values of the item are relative to the center of the board.

Figure 1. The relativeTo property of the board item—a sticky note in the example image—is set to canvas_center. The same mechanism applies to and works in the same way for all supported board items.
parent_top_leftThe item is positioned on the board, and it is a child of a parent item. For example, a parent frame.
The x and y coordinate values of the child item are relative to the top-left corner of the parent item).

Figure 2. The relativeTo property of the board item—a sticky note in the example image—is set to parent_top_left. The same mechanism applies to and works in the same way for all supported board items.
parent_centerExperimental feature Experimental feature

The item is positioned on the board, and it is a child of a parent mind map node.
The x and y coordinate values of the item are relative to the center of the parent mind map node item.

Figure 3. The relativeTo property of the child mind map nodes is set to parent_center.

See also:


parentId

Readonly parentId: null | string

Mind map node's parentId property can be one of the following:

  • The parentId of a child mind map node is always a mind map node ID.
  • If a root mind map node is inside a frame, parentId is the frame ID.
  • If a root mind map node is not inside a frame, parentId is null.

createdAt

Readonly createdAt: string

Timestamp

Date and time when the item was created.

Format: UTC, ISO 8601.
Includes a trailing Z offset.

Example: 2021-05-18T07:59:01Z

ℹ️ Note:

  • Timestamps indicating creation and update times are always in UTC time, regardless of the time offset configured on the machine where the app runs or where the code is executed.

createdBy

Readonly createdBy: string

Miro users are automatically assigned a unique ID.

createdBy contains the ID of the user who created the item.

Example: 3658432978520043388


modifiedAt

Readonly modifiedAt: string

Timestamp

Date and time when the item was last modified.

Format: UTC, ISO 8601.
Includes a trailing Z offset.

Example: 2021-05-18T07:59:01Z

ℹ️ Note:

  • Timestamps indicating creation and update times are always in UTC time, regardless of the time offset configured on the machine where the app runs or where the code is executed.

modifiedBy

Readonly modifiedBy: string

Miro users are automatically assigned a unique ID.

modifiedBy contains the ID of the user who applied the most recent edit to the item.

Example: 3658432978520043388


x

x: number

The x-axis coordinate of an item is the horizontal distance in dp of the center point of the item from the center point of the board.

The center point of the board has x: 0 and y: 0 coordinates.

Default: 0

See also:


y

y: number

The y-axis coordinate of an item is the vertical distance in dp of the center point of the item from the center point of the board.

The center point of the board has x: 0 and y: 0 coordinates.

Default: 0

See also:


linkedTo

Optional linkedTo: string

linkedTo is the namespace that enables links to be associated to items on the board.

When this property is utilized, the associated item will display an arrow icon on its top right corner. On click, this icon will navigate to the associated link.

For links that point to another item on the same board, the viewport will automatically move to that item when true is returned.

For links that point to an item on a separate board or an external url, a new tab tab will be opened.

Note: Items of type tag do not support the linkedTo property.

To link an item to another item on the same board, a valid url with an item id must be specified:

const [geoCard] = await miro.board.get({type: 'card'});

const widgetId = `00000000000000000`;
const boardId = 'xxxxxxxxxxx';

// Generate url based on boardId and widgetId
geoCard.linkedTo = `https://miro.com/app/board/${xxxxxxxxxxx}/?moveToWidget=${widgetId}`;

// OR you can use relative URL
geoCard.linkedTo = `/app/board/${xxxxxxxxxxx}/?moveToWidget=${widgetId}`;

// OR you can generate url based on current URL by simply change of query param
const searchParams = new URLSearchParams(window.location.search);
searchParams.set('moveToWidget', widgetId);
const newRelativePathQuery = `${window.location.pathname}?${searchParams.toString()}`;
geoCard.linkedTo = newRelativePathQuery;

To unlink an item to the provided url, set the property to undefined or pass an empty string "":

const [geoCard] = await miro.board.get({type: 'card'});
// Unlink the widget
geoCard.linkedTo = '';
// or
geoCard.linkedTo = undefined;

await geoCard.sync();

console.log(geoCard.linkedTo); // will return empty string: ''

connectorIds

Optional Readonly connectorIds: string[]

connectorIds is an array that contains the ids of the connectors attached to the current item.

ℹ️ Note: Items of type tag and frame do not support the connectorIds property.

Methods

sync

sync(): Promise<void>

Experimental feature Experimental

sync propagates to the board any changes to item and tag properties.
After updating the properties of an item or a tag, sync it with the board to:

  • Propagate to the board the changes applied to the item or to the tag.
  • Make the changes visible on the board.

All board items and tags require sync to make any changes to their properties visible on the board.

For more information and examples, see Update and sync item properties.

Example:
(The code example updates a mind map node item using sync.
The same mechanism applies to and works in the same way for all supported board items.)

// Create a new mind map node.
const mindmapNode = await miro.board.experimental.createMindmapNode();

mindmapNode.nodeView.content = 'This is a mindmap node';

// Call 'sync' to make the changed mind map node item properties visible on the board.
await mindmapNode.sync();

// Output the updated mind map node item to the developer console.
console.log(mindmapNode);

Returns

Promise<void>

Overrides

BaseItem.sync


add

add(item): Promise<MindmapNode>

Experimental feature Experimental

Adds a child node to a mind map node.

To add a child node to a mind map node with add(), the child node:

  • Must exist on the board.
  • Must be of type mindmap_node.
  • Must not be the parent or ancestor of the mind map node. For example, given the mind map structure Root 1 -> A1 -> B1 -> C1. You cannot add A1 under B1 or C1.

add() establishes a parent/child relationship between mind map nodes. After calling add():

  • The parentId of the child item corresponds to the parent mind map node ID.
  • The child mind map node ID is added to the parent mind map node's childrenIds array.
  • The child node is automatically repositioned relative to the parent node depending on the initial position of the child node. For example, if the a mind map node is located on the left of the parent node before adding it as a child node, the child node is added to the left of the parent node.
  • The child node's position is returned relative to its parent, calculated from the center of the parent node.
  • If a mind map node is already a child of another mind map node, add() will reparent the child node to the new parent node.

When adding a mind map node to a root mind map node (isRoot: true), the position of the child node with regards to the root mind map node depends on the initial position of the child node, based on the following:

  • If the initial position of the child node is to the left of the root mind map node, the child node is attached to the left of the root node.
  • If the initial position of the child node is to the right of the root mind map node, the child node is attached to the right of the root node.
// Create two mind map items, specifically one root node and one child node
const root = await miro.board.experimental.createMindmapNode({nodeView: {content: 'Root'}});
const child = await miro.board.experimental.createMindmapNode({nodeView: {content: 'Child'}});

// Add the child node to the root node
await root.add(child);

console.log(root, child);

Parameters

NameType
itemMindmapNode

Returns

Promise<MindmapNode>


getChildren

getChildren(): Promise<MindmapNode[]>

Experimental feature Experimental

Returns an array containing children of mindmap item.
If a mind map item has no children, the method returns an empty array.

The children can be only be of type mindmap_node

ℹ️ Note:

// Create three mind map items
const root = await miro.board.experimental.createMindmapNode({nodeView: {content: 'Root'}});
const child1 = await miro.board.experimental.createMindmapNode({nodeView: {content: 'Child 1'}});
const child2 = await miro.board.experimental.createMindmapNode({nodeView: {content: 'Child 2'}});

// Add Child 1 and Child 2 nodes to the root node
await root.add(child1);
await root.add(child2);

// Get all children nodes
const children = await root.getChildren();

console.log(children);

Returns

Promise<MindmapNode[]>


getMetadata

getMetadata(): Promise<AppData>

Experimental feature Experimental

Fetches board item metadata, stored per app, for the specified metadata key.
The response contains the metadata value assigned to the requested key.

To fetch all the metadata for a board item, invoke the method without passing any arguments.
The response contains all the metadata associated with the board item as key/value pairs.

An app can access only the metadata that it sets.
It cannot access metadata set by other apps.

ℹ️ Note:

⚠️ Warning:

  • Use AppMetadata to store limited amounts of metadata.
    Recommended: < 6 KB.
  • When updating metadata, limit the data size of the update payload.
    Recommended: < 6 KB.
  • Don't use AppMetadata as a file storage solution (< 300 KB).

Example:

// Create new mind map node
const root = await miro.board.experimental.createMindmapNode({nodeView: {content: 'Root'}});

// Set item metadata for an imaginary geocaching game, and store it in the created mind map item
await root.setMetadata('leaderboard', ['Ziltoid', 'Howard', 'Paul']);
await root.setMetadata('scores', [10, 20, 30]);

// Get all metadata items by not passing any parameter
const metadata = await root.getMetadata();

console.log(metadata.leaderboard, metadata.scores);

// Get specific metadata by passing metadata key as argument
const leaderboard = await geoCard.getMetadata('leaderboard');
const scores = await geoCard.getMetadata('scores');

console.log(leaderboard, scores);

// Clear metadata
await mindmapNode.setMetadata('leaderboard', {});
await mindmapNode.setMetadata('scores', {});

Returns

Promise<AppData>

getMetadata<T>(key): Promise<T>

Type parameters

NameType
Textends Json

Parameters

NameType
keystring

Returns

Promise<T>


setMetadata

setMetadata<T>(key, value): Promise<T>

Experimental feature Experimental

Adds board item metadata to make it available on the board that the app runs on.
An app can access only the board item metadata that it sets.
It cannot access metadata set by other apps.

Board item metadata is stored in the item it refers to. Therefore:

  • When duplicating an item, the metadata is copied to the new item.
  • When deleting an item, the corresponding metadata is removed with the deleted item.

Board item metadata is synced across, and available to, all the users who can:

  • Access and view the board that the app is running on, AND
  • Run the app on the board.

AppMetadata is a key/value-pair object. It can contain values with the following data types:

  • string
  • number
  • boolean
  • Object
  • Array
  • null
  • undefined

To overwrite an existing key inside AppMetadata:

  • Pass the same key multiple times with different values. Only the last/most recent value is stored with the key.

To remove a key from AppMetadata:

  • Set the value of the existing key to either null, or undefined.
    This clears the key. If you call getMetadata(key) to retrieve a key that has been set to null or undefined, the method returns undefined.

ℹ️ Note:

⚠️ Warning:

  • Use AppMetadata to store limited amounts of metadata.
    Recommended: < 6 KB.
  • When updating metadata, limit the data size of the update payload.
    Recommended: < 6 KB.
  • Don't use AppMetadata as a file storage solution (< 300 KB).

Example:

// Create new mind map node
const root = await miro.board.experimental.createMindmapNode({nodeView: {content: 'Root'}});

// Set item metadata for an imaginary geocaching game and store it in the mind map item created
await root.setMetadata('leaderboard', ['Ziltoid', 'Howard', 'Paul']);
await root.setMetadata('scores', [10, 20, 30]);

// Get all metadata items by not passing any parameter
const metadata = await root.getMetadata();

console.log(metadata.leaderboard, metadata.scores);

// Get specific metadata by passing metadata key as argument
const leaderboard = await geoCard.getMetadata('leaderboard');
const scores = await geoCard.getMetadata('scores');

console.log(leaderboard, scores);

// Clear metadata in one of the following ways:
// 1. Assign the metadata an empty object.
await mindmapNode.setMetadata('leaderboard', {});
await mindmapNode.setMetadata('scores', {});
// 2. Set the metadata to 'undefined'.
await mindmapNode.setMetadata('leaderboard', undefined);
await mindmapNode.setMetadata('scores', undefined);
// 3. Set the metadata to 'null'.
await mindmapNode.setMetadata('leaderboard', null);
await mindmapNode.setMetadata('scores', null);

Type parameters

NameType
Textends AppData

Parameters

NameType
keystring
valueJson

Returns

Promise<T>


goToLink

goToLink(): Promise<boolean>

Experimental feature Experimental

goToLink navigates to the provided link associated with the item on a board.

For links that point to another item on the same board, the viewport will automatically move to that item when true is returned.

For links that point to an item on a separate board or an external url, a new tab tab will be opened.

Returns:

Promise<boolean>

  • true: Link is successfully associated with the item, navigation is triggered, and the linkedTo property contains a valid value.
  • false: Link is not successfully associated to the item due to an invalid or missing linkedTo property, and no navigation is triggered.

Example:

const [geoCard] = await miro.board.get({type: 'card'});

// Link item to some url
geoCard.linkedTo = 'https://google.com';

// Update widget props and apply changes
await geoCard.sync();

// Navigate to https://google.com (value of `linkedTo` property)
await geoCard.goToLink();

Returns

Promise<boolean>


bringToFront

bringToFront(): Promise<void>

In a stack of items, this method brings an item to the front so that it is at the top of the stack.
When the item is at the front, it is fully visible; The item can partially or completely hide underlying items in the same stack.

ℹ️ Note:

  • Frame items don't support the bringToFront() method.
    As a frame item acts as a parent that can contain other items, a frame item is always at the back, relative to any other items on the board.
    The only object behind a frame is the board itself.

Example:

// Create three sticky notes
const first = await miro.board.createStickyNote({
  content: 'first',
});

const second = await miro.board.createStickyNote({
  content: 'second',
});

const third = await miro.board.createStickyNote({
  content: 'third',
});

// Bring the first sticky note to the front of the board.
await first.bringToFront();

Returns

Promise<void>


sendToBack

sendToBack(): Promise<void>

In a stack of items, it sends an item to the back so that it is at the bottom of the stack.
When it is at the back, item is partially or completely hidden by overlying items in the same stack.

ℹ️ Note:

  • Frame items don't support the sendToBack() method.
    As a frame item acts as a parent that can contain other items, a frame item is always at the back, relative to any other items on the board.
    The only object behind a frame is the board itself.

Example:

// Create three sticky notes
const first = await miro.board.createStickyNote({
  content: 'first',
});

const second = await miro.board.createStickyNote({
  content: 'second',
});

const third = await miro.board.createStickyNote({
  content: 'third',
});

// Send the third sticky note to the back of the board
await third.sendToBack();

Returns

Promise<void>


bringInFrontOf

bringInFrontOf(target): Promise<void>

In a stack of items, this method sends an item in front of another item (target).
When an item is moved to the front, the item can partially or completely hide underlying items in the same stack. \

ℹ️ Note:

  • As this method implements relative positioning, you can use this method to place items in front or behind other items.
    If you want to send an item all the way to the front,
    you can use the method bringToFront(), which places the item at the top of the stack.
  • Frame items don't support the bringInFrontOf() method.
    As a frame item acts as a parent that can contain other items, a frame item is always at the back, relative to any other items on the board.
    The only object behind a frame is the board itself.

Example:

// Create three sticky notes
const first = await miro.board.createStickyNote({
  content: 'first',
});

const second = await miro.board.createStickyNote({
  content: 'second',
});

const third = await miro.board.createStickyNote({
  content: 'third',
});

// Bring the first sticky note in front of second.
await first.bringInFrontOf(second);

Parameters

NameType
targetBaseMixin

Returns

Promise<void>


sendBehindOf

sendBehindOf(target): Promise<void>

In a stack of items, this method sends an item behind another item (target).
When an item is moved to the back, the item can be partially or completely hidden by the overlying items in the top of the same stack.

ℹ️ Note:

  • As this method implements relative positioning, you can use this method to place items in front or behind other items.
    If you want to send an item all the way to the back,
    you can use the method sendToBack(), which places the item at the bottom of the stack.
  • Frame items don't support the sendBehindOf() method.
    As a frame item acts as a parent that can contain other items, a frame item is always at the back, relative to any other items on the board.
    The only object behind a frame is the board itself.

Example:

// Create three sticky notes
const first = await miro.board.createStickyNote({
  content: 'first',
});

const second = await miro.board.createStickyNote({
  content: 'second',
});

const third = await miro.board.createStickyNote({
  content: 'third',
});

// Send the third sticky note behind the second one
await third.sendBehindOf(second);

Parameters

NameType
targetBaseMixin

Returns

Promise<void>


getLayerIndex

getLayerIndex(): Promise<number>

The getLayerIndex() method returns the position of an item in the item stack.

Items in a stack are layered on top of each other based on their layer index value. An item with a higher layer index appears above items with lower layer index values.

Each item on the board has a layer index position in the stack. The higher the layer index value, the "closer" to the user the item appears.

For example, with three items on the board - first, second, and third - their initial layer index values might be:
first[0], second[1], third[2].

The item with layerIndex === 2 (third) will be fully visible at the top of the stack. The item with layerIndex === 1 (second) may be partially hidden by the item above it. And the item with layerIndex === 0 (first) may be fully hidden by the items above it.

Returns:

  • Promise<number> - calling getLayerIndex() allows you get the position of a specific item in the stack.

ℹ️ Note:

  • The item stack is zero indexed.
  • Frame items don't support the getLayerIndex() method.
    As a frame item acts as a parent that can contain other items, a frame item is always at the back, relative to any other items on the board.
    The only object behind a frame is the board itself.

Example:

// Create three sticky notes.
// Sticky notes are created on top of each other in the creation order, with the layer index equal to the creation index.
const first = await miro.board.createStickyNote({
  content: 'first',
});

const second = await miro.board.createStickyNote({
  content: 'second',
});

const third = await miro.board.createStickyNote({
  content: 'third',
});

await third.getLayerIndex(); // returns 2

Returns

Promise<number>


getConnectors

getConnectors(): Promise<Connector[]>

The getConnectors() method returns an array of connector items attached to the current item. The connectors returned correspond to the ids in the connectorIds property of the item.

Example:

// Create two sticky notes linked by a connector.
const startItem = await miro.board.createStickyNote({
  content: 'start',
});

const endItem = await miro.board.createStickyNote({
  content: 'end',
  x: 500,
});

const connector = await miro.board.createConnector({
  start: {
    item: startItem.id,
  },
  end: {
    item: endItem.id,
  },
});

// sync() updates the connectorIds property in startItem
await startItem.sync();

const connectors = await startItem.getConnectors(); // returns [connector]

Returns

Promise<Connector[]>