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.
Properties
action
readonly 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.
Methods
get(...)
(filter?: GetFilter) => Promise<Array<Unsupported | Connector | AppCard | Card | Embed | '...'>>
🔒 Requires scope: boards:read
🚦 Rate limit: Level 3
Fetches one or more items, tags or groups from the board.
If you don't pass any arguments, the method returns an array with all the items, groups 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'],
});
select(...)
(filter?: GetFilter) => Promise<Array<Unsupported | Connector | AppCard | Card | Embed | '...'>>
🔒 Requires scope: boards:write
🚦 Rate limit: Level 1
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. If you pass typegroup
, all the elements within the groups will be deselected. - 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'],
});
// Select all grouped items in the board
await miro.board.select({
type: 'group',
});
deselect(...)
(filter?: GetFilter) => Promise<Array<Unsupported | Connector | AppCard | Card | Embed | '...'>>
🔒 Requires scope: boards:write
🚦 Rate limit: Level 1
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. If you pass typegroup
, all the elements within the groups will be deselected. - 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'],
});
// Deselect all grouped items in the board
await miro.board.deselect({
type: 'group',
});
getSelection(...)
() => Promise<Array<Unsupported | Connector | AppCard | Card | Embed | '...'>>
🔒 Requires scope: boards:read
🚦 Rate limit: Level 3
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.
If the grouped items are selected, the group entity for those items will also be returned.
When individual items within a group are selected with a double-click, the group entity will not be returned as part of this method.
Example:
// Get an array with the selected item(s) and their properties
const selection = await miro.board.getSelection();
console.log(selection);
getVotingResults(...)
() => Promise<Array<VotingResult>>
🔒 Requires scope: boards:read
🚦 Rate limit: Level 1
This method retrieves the results of voting sessions conducted on a specific board. The method does not accept any arguments.
The results of a voting session include:
createdBy
: The username and user ID of the user who initiated the voting session.createdAt
: The start date and time of the voting session in UTC, formatted according to ISO 8601 with a trailingZ
offset. For example,2021-05-18T07:59:01Z
.title
: The title of the voting session.results
: An array of objects containing:itemId
: The ID of the item that was voted on.count
: The total number of votes the item received.
Note
- All timestamps are in UTC, regardless of the app's local machine or execution environment settings.
- This method is available only on paid plans with access to the voting feature. If the app is installed on a team without access to voting, the method will return an error.
- Ensure the app is installed for a team on a paid plan.
- Verify that the voting plugin is installed for the team.
Example:
// Retrieve voting session results.
const votingResults = await miro.board.experimental.getVotingResults();
console.log(votingResults);
// Example output:
//
// [
// {
// "createdBy": {
// "userId": "3458764112826546974",
// "userName": "Ellen Ripley"
// },
// "createdAt": "2023-05-23T10:16:10.464Z",
// "title": "Which option? Save the LV-426 site or nuke it from orbit?",
// "results": [
// {
// "itemId": "3458764513811016840",
// "count": 2
// }
// ]
// }
// ]
sync(...)
(item: BaseItem) => 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
🚦 Rate limit: 50 * (1 + number_of_children), where number_of_children
is the number of mindmap children given as input.
number_of_children
is the number of mindmap children given as input.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:
// Create mind map root node
const root = await miro.board.experimental.createMindmapNode({
nodeView: {
content: '<p>Mind map root node.</p>',
}
});
console.log(root)
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.createMindmapNode({
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
Updated 26 days ago