Experimental

experimental.Experimental

Experimental

experimental is the namespace that groups and exposes experimental features.
Through miro.board.experimental, apps can access functionality, properties, and methods that are in active development, and therefore subject to change without notice.

⚠️ Warning:

• The features exposed through miro.board.experimental are suitable for testing purposes.
  Don't deploy these features to a production environment.

Table of contents

Constructors

• constructor

Properties

• action
• events

Methods

• createMindmapNode
• createShape
• get
• select
• deselect
• getSelection
• getVotingResults
• sync
• remove
• findEmptySpace

Constructors

constructor

• new Experimental()

Properties

action

• action: CustomActionManagement

Experimental

The action namespace groups a set of methods that enable apps to use custom actions.
The action namespace is currently under the experimental namespace, and it exposes a single method: register():
miro.board.experimental.action.register

You use this method to register a custom action with an app.
The method takes a single argument: an object that defines the custom action.

events

• events: RealtimeEvents

Methods

createMindmapNode

▸ createMindmapNode(props?): Promise<MindmapNode>

Experimental

Creates a mind map item on a board.

There are no required properties to pass while creating a mind map item.
When you create a mind map item without passing any property, the content of the root item is an empty string of type text. You can update the values later.

Example:

const mindmap = await miro.board.experimental.createMindmap({
  rootView: {
    content: '<p>This is the root node of the mind map item.</p>',
  },
  x: 0, // Default value: horizontal center of the board
  y: 0, // Default value: vertical center of the board
});

console.log(mindmap);

Mind map item:

Figure 1. Mind map item.

You can also create a mind map tree by passing the children property:

const mindmap = await miro.board.experimental.createMindmap({
  nodeView: {
    content: 'Root',
  },
  children: [
    {
      direction: 'start',
      nodeView: {content: 'Child 1'},
    },
    {
      nodeView: {content: 'Child 2'},
      // You can nest as many children as you want
      children: [
        {
          nodeView: {content: 'Child 2 - 1'},
        },
        {
          nodeView: {content: 'Child 2 - 2'},
          children: [
            {
              nodeView: {content: 'Child 2 - 2 - 1'},
            },
          ],
        },
      ],
    },
  ],
});

console.log(mindmap);

Note on default values during creation:

• By default, the root node always has node view type of shape
• By default, the child nodes always have node view types of text

Parameters

Returns

Promise<MindmapNode>

createShape

▸ createShape(props?): Promise<ShapeExperimental>

Experimental

Creates a geometric shape on a board.

The only required property to pass upon creation is a valid shape. In the experimental namespace, this method supports creating regular shapes and flowchart shapes.

Example:

const shape = await miro.board.experimental.createShape({
  content: '<p>This is a star shape.</p>',
  shape: 'star',
  style: {
    color: '#ff0000', // Default text color: '#1a1a1a' (black)
    fillColor: '#ffff00', // Default shape fill color: transparent (no fill)
    fontFamily: 'arial', // Default font type for the text
    fontSize: 14, // Default font size for the text, in dp
    textAlign: 'center', // Default horizontal alignment for the text
    textAlignVertical: 'middle', // Default vertical alignment for the text
    borderStyle: 'normal', // Default border line style
    borderOpacity: 1.0, // Default border color opacity: no opacity
    borderColor: '#ff7400', // Default border color: '#ffffff` (white)
    borderWidth: 2, // Default border width
    fillOpacity: 1.0, // Default fill color opacity: no opacity
  },
  x: 0, // Default value: center of the board
  y: 0, // Default value: center of the board
  width: 200,
  height: 200,
});

console.log(shape);

Shape item (star shape):

Figure 1. Shape item example: a star shape.

Parameters

Returns

Promise<ShapeExperimental>

get

▸ get(filter): Promise<MindmapNode[]>

Fetches one or more items or tags from the board.
If you don't pass any arguments, the method returns an array with all the items and tags on the board.

Optionally, you can filter items by id, type, and tags:

• Filter by id: pass an item or a tag id to fetch the corresponding item or tag.
  If the ID doesn't exist on the board, the method throws an error.
  Pass an array of IDs to fetch an array with all the items or tags matching one of the specified IDs.
• Filter by type: pass an item type to fetch an array with the items matching the requested type.
  Pass an array of types to fetch an array with the items matching one of the specified types.
• Filter by tags: pass one or more tags to fetch all the items with the specified tags.
  If the tags don't exist on the board, the method returns an empty array.
  Pass an array of tags to fetch an array with the items matching one of the specified tags.

ℹ️ Note:

• The method cannot return child items inside unsupported parent items, such as User Story Mapping (USM) and Kanban.
• If you filter by passing an array of item IDs, item types, or tags, the logical operator between the array members is OR.
• The method doesn't have an upper limit as to the maximum amount of items that it can return.
  To avoid performance degradation on the board UI, we recommend to not exceed 10000 items per board.

Example:

// Create a tag
const todo = await miro.board.createTag({
  title: 'todo',
  color: 'yellow',
});

// Create another tag
const urgent = await miro.board.createTag({
  title: 'urgent',
  color: 'magenta',
});

// Create a card and attach the tags to it
const card = await miro.board.createCard({
  title: 'card with tags: "todo", "urgent"',
  tagIds: [todo.id, urgent.id],
});

// Create a sticky note and attach the tags to it
const stickyNote = await miro.board.createStickyNote({
  content: 'sticky note with tags: "todo", "urgent"',
  tagIds: [todo.id, urgent.id],
});

// Get the sticky note by passing its ID
await miro.board.get({
  id: stickyNote.id,
});

// Get all items with type: 'card' OR 'sticky_note'
await miro.board.get({
  type: ['card', 'sticky_note'],
});

// Get all 'card' OR 'sticky_note' items with tags: 'todo' OR 'urgent'
await miro.board.get({
  type: ['sticky_note', 'card'],
  tags: ['todo', 'urgent'],
});

Parameters

Returns

Promise<MindmapNode[]>

select

▸ select(filter): Promise<MindmapNode[]>

Selects one or more items from the board and returns the list of selected items.
If you don't pass any arguments, the method selects all items and returns them.

Optionally, you can select items by id, type, and tags:

• Select by id: pass an item id to select the corresponding item. If the ID doesn't exist on the board, the method throws an error.
  Pass an array of IDs to select items with one of the specified IDs.
• Select by type: pass an item type to select items matching the requested type.
  Pass an array of types to select items matching one of the specified types.
• Select by tags: pass one or more tags to select items with the specified tags.
  If the tags don't exist on the board, the method returns an empty array.
  Pass an array of tags to select items matching one of the specified tags.

ℹ️ Note:

• The method cannot return child items inside unsupported parent items, such as User Story Mapping (USM) and Kanban.
• If you filter by passing an array of item IDs, item types, or tags, the logical operator between the array members is OR.
• The method doesn't have an upper limit as to the maximum amount of items that it can return.
  To avoid performance degradation on the board UI, we recommend to not exceed 10000 items per board.

Example:

// Create a tag
const todo = await miro.board.createTag({
  title: 'todo',
  color: 'yellow',
});

// Create another tag
const urgent = await miro.board.createTag({
  title: 'urgent',
  color: 'magenta',
});

// Create a card and attach the tags to it
const card = await miro.board.createCard({
  title: 'card with tags: "todo", "urgent"',
  tagIds: [todo.id, urgent.id],
});

// Create a sticky note and attach the tags to it
const stickyNote = await miro.board.createStickyNote({
  content: 'sticky note with tags: "todo", "urgent"',
  tagIds: [todo.id, urgent.id],
});

// Select the sticky note by passing its ID
await miro.board.select({
  id: stickyNote.id,
});

// Select all items with 'card' OR 'sticky_note' type
await miro.board.select({
  type: ['card', 'sticky_note'],
});

// Select all 'card' OR 'sticky_note' items with 'todo' OR 'urgent' tags
await miro.board.select({
  type: ['sticky_note', 'card'],
  tags: ['todo', 'urgent'],
});

Parameters

Returns

Promise<MindmapNode[]>

deselect

▸ deselect(filter): Promise<MindmapNode[]>

Deselects one or more items from the board and returns the list of deselected items.
If you don't pass any arguments, the method deselects all items and returns them.

Optionally, you can deselect items by id, type, and tags:

• Deselect by id: pass an item id to deselect the corresponding item. If the ID doesn't exist on the board, the method throws an error.
  Pass an array of IDs to deselect items with one of the specified IDs.
• Deselect by type: pass an item type to deselect items matching the requested type.
  Pass an array of types to deselect items matching one of the specified types.
• Deselect by tags: pass one or more tags to deselect items with the specified tags.
  If the tags don't exist on the board, the method returns an empty array.
  Pass an array of tags to deselect items matching one of the specified tags.

ℹ️ Note:

• The method cannot return child items inside unsupported parent items, such as User Story Mapping (USM) and Kanban.
• If you filter by passing an array of item IDs, item types, or tags, the logical operator between the array members is OR.
• The method doesn't have an upper limit as to the maximum amount of items that it can return.
  To avoid performance degradation on the board UI, we recommend to not exceed 10000 items per board.

Example:

// Create a tag
const todo = await miro.board.createTag({
  title: 'todo',
  color: 'yellow',
});

// Create another tag
const urgent = await miro.board.createTag({
  title: 'urgent',
  color: 'magenta',
});

// Create a card and attach the tags to it
const card = await miro.board.createCard({
  title: 'card with tags: "todo", "urgent"',
  tagIds: [todo.id, urgent.id],
});

// Create a sticky note and attach the tags to it
const stickyNote = await miro.board.createStickyNote({
  content: 'sticky note with tags: "todo", "urgent"',
  tagIds: [todo.id, urgent.id],
});

// Select all
await miro.board.select();

// Deselect the sticky note by passing its ID
await miro.board.deselect({
  id: stickyNote.id,
});

// Deselect all items with 'card' OR 'sticky_note' type
await miro.board.deselect({
  type: ['card', 'sticky_note'],
});

// Deselect all 'card' OR 'sticky_note' items with 'todo' OR 'urgent' tags
await miro.board.deselect({
  type: ['sticky_note', 'card'],
  tags: ['todo', 'urgent'],
});

Parameters

Returns

Promise<MindmapNode[]>

getSelection

▸ getSelection(): Promise<Item[]>

Fetches the selected items from the board, and it returns them in an array.
If no items are selected on the board, the method returns an empty array.

Example:

// Get an array with the selected item(s) and their properties
const selection = await miro.board.getSelection();

console.log(selection);

Returns

Promise<Item[]>

getVotingResults

▸ getVotingResults(): Promise<VotingResult[]>

Returns

Promise<VotingResult[]>

sync

▸ sync(item): Promise<void>

Parameters

Returns

Promise<void>

remove

▸ remove(item): Promise<void>

Experimental

Removes a board item or a tag from the board.
When removing board items or tags, any associated metadata is removed as well.

ℹ️ Note:

• To use the remove() method, apps need the boards:write permission.
• board.remove() removes board items and tags from the board.
  It doesn't remove parent-child relationships between items.
  To remove a parent-child relationship between items, use remove() at the parent item level.
  For example: frame.remove().

remove is common to all board items, except unsupported items.

Parameters

Returns

Promise<void>

findEmptySpace

▸ findEmptySpace(dimensions): Promise<Rect>

Experimental

Use the findEmptySpace method to identify an area on the board that doesn't overlap with existing board items.

Parameters

• x and y: define the starting central point to begin the search for an empty space.
• width and height: specify the desired size of the empty space.
• offset (optional): sets a distance between the empty space and nearby board items. If not provided, the method finds the closest available space. Default value: 100

Returns An object containing x and y coordinates for the center point of the identified empty space, along with the specified width and height.

Example:

const position = await miro.board.experimental.findEmptySpace({
  x: 0,
  y: 0,
  width: 200,
  height: 200,
});
// If the board is empty then
// position has the following properties:
// {
//   x: 0,
//   y: 0,
//   width: 200,
//   height: 200
// }

await miro.board.createStickyNote({
  content: "I'm not overlaping any existing widgets",
  ...position,
});

Parameters

Returns

Promise<Rect>