Experimental

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

Properties

action

readonly CustomActionManagement

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

Methods

get(...)

(filter?: GetFilter) => Promise<Array<BoardNode>>
🔒 Requires scope: boards:read

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'],
});

select(...)

(filter?: GetFilter) => Promise<Array<BoardNode>>
🔒 Requires scope: boards:write

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'],
});

deselect(...)

(filter?: GetFilter) => Promise<Array<BoardNode>>
🔒 Requires scope: boards:write

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'],
});

getSelection(...)

() => Promise<Array<Item>>
🔒 Requires scope: boards:read

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);

sync(...)

(item: BaseMixin) => Promise<void>
🔒 Requires scope: boards:write

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.


createMindmapNode(...)

(props?: MindmapCreateNodeProps) => Promise<MindmapNode>
🔒 Requires scope: boards:write

Experimental feature 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:

Mindmap 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

findEmptySpace(...)

(dimensions: Rect & { offset?: number }) => Promise<Rect>
🔒 Requires scope: boards:read

Experimental feature 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,
});