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
Properties
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
Name | Type |
---|---|
props? | MindmapCreateNodeProps |
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
Name | Type |
---|---|
props? | ShapeExperimentalProps |
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 tagid
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 itemtype
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
Name | Type |
---|---|
filter | { id : string | string [] } & { type : "mindmap_node" } & { type? : string | string [] ; tags? : string | string [] } & { type : "mindmap_node" } |
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 itemid
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 itemtype
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
Name | Type |
---|---|
filter | { id : string | string [] } & { type : "mindmap_node" } & { type? : string | string [] ; tags? : string | string [] } & { type : "mindmap_node" } |
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 itemid
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 itemtype
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
Name | Type |
---|---|
filter | { id : string | string [] } & { type : "mindmap_node" } & { type? : string | string [] ; tags? : string | string [] } & { type : "mindmap_node" } |
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
Name | Type |
---|---|
item | BaseMixin |
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 theboards: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, useremove()
at the parent item level.
For example:frame.remove()
.
remove
is common to all board items, except unsupported items.
Parameters
Name | Type |
---|---|
item | Item |
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
andy
: define the starting central point to begin the search for an empty space.width
andheight
: 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
Name | Type |
---|---|
dimensions | Rect & { offset : number } |
Returns
Promise
<Rect
>
Updated 9 days ago