Skip to main content

Web SDK Reference Guide

Miro Web SDK Reference Guide v1 -> v2

If your app currently uses the Miro Web SDK v1, it’s time to plan your migration to v2. The Miro Developer Platform 2.0 has reworked and improved the Web SDK, focusing on performance and reliability, as well as the developer experience. This document will outline the changes in certain data objects, and in how those objects relate to others. For a higher-level explanation of these changes, be sure to check out the comparison guide.

window.miro

The window.miro object continues to be the root object of the Web SDK, serving as the main entry point to the SDK methods. All methods in this reference guide are referred to by their hierarchy following window.miro.**___**.

Boards

At first glance, much of the v1 board object has changed. Despite this, working with a board object in the Miro Web SDK v2 should feel familiar. The structure of the board object is fundamentally the same between v1 and v2. While many methods were renamed for improved clarity, they behave in the same manner as in v1.

Creating a widget / item

The most significant change for board objects in the v2 Web SDK is the replacement of the board.widgets.create method with individual constructors for each widget type.

In the Miro Web SDK v1, the widget methods were polymorphic – meaning that one method was used to interact with all potential widget types. The structure of the call would differ depending on what type of widget you were creating or updating. In the v2 SDK, we have replaced this with an independent constructor for each widget type. Widgets are now referred to as "items" and each item exists as its own object, rather than as a property of the board.

The new item constructors should feel familiar to you, as they were designed to mostly follow the structure of the type-specific payloads of the previous board.widgets.create() call. The following table provides a map of the v1 board.widgets.create call for each supported widget type and its equivalent v2 item constructor.

Widget creation in v1Item creation in v2
Not available in v1

AppCard

board.createAppCard({
    title: "Hello, app card",
    description: "This is a description"
})

Card

board.widgets.create({
    type: "card", 
    title: "Hello, card"
})

Card

board.createCard({
    title: "Hello, card"
})

Embed

board.widgets.create({
    type: "embed", 
    html: "miro.com/blog"
})

Embed

board.createEmbed({
    url: "https://www.miro.com/blog"
})

Emoji
ℹ️ Note:

  • Emoji widgets were only partially supported in v1. The default smiley-face can be created, but the code property was read-only, and so no other emoji could be specified.
board.widgets.create({
    type: "emoji"
})
Not currently available in v2

Frame

board.widgets.create({
    type: "frame", 
    title: "Hello, frame"
})

Frame

board.createFrame({
    title: "Hello, frame"
})

Image

board.widgets.create({
    type: "image", 
    title: "Hello, image", 
    url: "miro.com/logo"}
)

Image

board.createImage({
    title: "Hello, image", 
    url: "miro.com/logo"
})

Line

board.widgets.create({
    type: "line", 
    startWidgetId: "[[id]]", 
    endWidgetid: "[[id]]"
})

Connector

board.createConnector({
  shape: 'elbowed',
  style: {
    startStrokeCap: 'diamond',
    endStrokeCap: 'stealth',
    strokeStyle: 'dashed',
    strokeColor: '#ff00ff', // Magenta
    strokeWidth: 2,
  },
  start: {
    item: start.id,
    position: {
      x: 1.0,
      y: 0.5,
    },
  },
  end: {
    item: end.id,
    snapTo: 'right',
  },
});

Preview creation was not supported in v1.

Preview

board.createPreview({
    url: "https://miro.com"
})

Shape

board.widgets.create({
    type: "shape", 
    text: "Hello, shape",
    style: {
        shapeType: "star"
    }
})

Shape

board.createShape({
    content: "Hello, shape",
    shape: "star"
})



Sticker

board.widgets.create({
    type: "sticker", 
    text: "Hello, world"
})

Sticky Note

board.createStickyNote({
    content: "Hello, world"
})

Text

board.widgets.create({
    type: "text", 
    text: "Hello, words"
})

Text

board.createText({
    content: "Hello, words"
})

Board properties

The table below provides a side-by-side comparison of each board property in the v1 and v2 Web SDKs. The majority of the properties supported in v1 have been removed, and so we have tried to provide the reasoning behind those removals.

board properties in v1

board properties in v2

board.ui served as the namespace for the methods that interact with the Miro board’s user interface.

board.ui continues to serve this same function in v2.

board.viewport served as the namespace for the methods that interact with the current viewport.

board.viewport continues to serve this same function in v2.

board.widgets served as the namespace for all CRUD operations on board items.

This has been removed as a property in v2, as explained above. Board items now exist as their own objects, separate from the board object.

board.tags served as the namespace for the methods for interacting with tags on a board.

This has been removed as a property in v2, as explained below. Tags now exist as their own objects, separate from the board object.

board.info served as the namespace for methods related to getting board information.

However, there was only one supported method in this namespace: board.info.get().

This has been removed in v2, as there is not a need for a dedicated namespace for board information.

Board information can now be retrieved using the board.getInfo() method.

board.selection served as the namespace for methods that interacted with the selection of certain widgets on the board.


In v2, this function is served by getSelection(). See getSelection().

board.utils served as the namespace for utility methods for a board.

However, there was only one supported method in this namespace: board.utils.unionWidgetBounds().

This has been removed in v2, as there is not a need for a dedicated namespace for board utility functions.

Specifically, a bounds object is no longer a property of board items, rendering the v1 utility method obsolete.

Board metadata / storage

In the v1 Web SDK, board.metadata supported two experimental methods. Metadata was also sometimes referred to as "storage" and provided developers with a way to write a key-value data object into local storage.

Both of these endpoints have been upgraded and are now fully-supported in v2, and have been renamed for clarity.

The table below provides a side-by-side comparison of the usage of each method.

v1 methodv2 method
board.metadata.update("key", "value")

board.setAppData("key", value)

board.metadata.get("key")

board.getAppData("key")

V2 also introduces support for item-level metadata. You can now set and get metadata that is associated with a particular item on the board:
setMetadata

board.setMetadata("key", value)

getMetadata

board.getMetadata("key")

Storage collection

In addition to app and item-level metadata, the V2 Web SDK introduces new support for Storage collection. This provide the ability to store, retrieve, and remove data from a specified collection using key value pairs.

Storage collection provides more storage capability than app and item-level metadata offers and enables you to build logic for when certain keys change (onValue listener).

For a full comparison of all supported metadata and storage options in the V2 Web SDK, see the Storage guide.

BoardUI

When building the v2 SDK, we decided to rethink the way we expose extension points. As a result of this design choice, we have removed several extension points that were available in v1.

Currently, developers building applications with the Miro v2 Web SDK have two options available: the app panel ("Panel") and the pop-up modal ("Modal"). The bottom bar and the left sidebar are no longer available.

The table below shows the board.ui endpoints from v1 and their v2 counterparts, if available.

board.ui in v1

board.ui in v2

board.ui.openLibrary(
    "show-this-page-in-the-library.html", 
    { title: "The library!" }
)

board.ui.openPanel({
    url: 'show-this-page-in-the-panel.html'
})

board.ui.closeLibrary()

board.ui.closePanel()

board.ui.openModal(
    "show-this-page-in-the-modal.html", 
    { 
        width: 400, 
        height: 400 
    }
)

board.ui.openModal({
    url: 'show-this-page-in-the-modal.html',
    width: 600,
    height: 400,
    fullscreen: false,
})

board.ui.closeModal()

board.ui.closeModal()

board.ui.openLeftSidebar(
    "show-this-page-in-the-sidebar.html"
)
Not currently available in v2.
board.ui.closeLeftSidebar()
Not currently available in v2.
board.ui.openBottomPanel(
    "show-this-page-in-the-bottom-bar.html", 
    {
        width: 200,
        height: 200,
    }
)
Not currently available in v2.
board.ui.closeBottomPanel()
Not currently available in v2.

board.ui.resizeTo() provided a way to resize the current iframe inside of the bottom bar.

This method has been removed in v2, as the bottom bar is not currently available.

V2 also introduces additional helper methods for understanding if modals or panels already open on a board. You can now check modal and panel statuses:
canOpenModal

board.ui.canOpenModal()

canOpenPanel

board.ui.canOpenPanel()

V2 also introduces new methods in board.ui for manager the Z-index of an item. See getLayerIndex and its associated methods for more details on managing layers (Z-index) for items.

Events

The V2 Web SDK introduces new support for events which can be used trigger certain logic in an app. Events capture user actions, board changes, and more—enabling your app to respond to actions in Miro.

The V2 Web SDK supports events for:

For more details on supported events, see the Events guide for a comparison between each type of supported event.

Viewport

In both the v1 and v2 Web SDKs, board.viewport serves as the namespace for the collection of methods that interact with the current viewport. The viewport endpoints are largely unchanged, with one major exception: the three methods for controlling the zoom level of a viewport in v1 are no longer supported in v2.

See the table below for a full side-by-side comparison of each board.viewport method and its usage across both v1 and v2.

board.viewport in v1

board.viewport in v2

board.viewport.get()




board.viewport.get()

This method and its response are both unchanged between the v1 and v2 SDKs.

board.viewport.getViewport()

ℹ️ Note:

  • This method is functionally equivalent to board.viewport.get() and was already deprecated in v1.
board.viewport.get()





board.viewport.set({
    x: x-coordinate,
    y: y-coordinate,
    height: height-of-viewport,
    width: width-of-viewport
})




board.viewport.set({
    x: x-coordinate,
    y: y-coordinate,
    height: height-of-viewport,
    width: width-of-viewport
})

This method is unchanged between the v1 and v2 SDKs.

board.viewport.zoomToObject(myShape.id)








board.viewport.zoomTo(myShape)

In the v2 Web SDK, zoomToObject has been renamed to zoomTo.

In addition, where the v1 zoomToObject required the object’s ID as a String parameter, zoomTo requires one or more item objects as a parameter.

board.viewport.setViewportWithAnimation(
    viewport: {
        x: x-coordinate,
        y: y-coordinate,
        height: height-of-viewport,
        width: width-of-viewport
    },
    animationTimeInMs: 1000
)





board.viewport.set(
    viewport: {
        x: x-coordinate,
        y: y-coordinate,
        height: height-of-viewport,
        width: width-of-viewport
    },
    animationDurationInMs: 1000
)

To set the viewport with an animation in v2, include the option animationDurationInMs parameter when calling board.viewport.set().

board.viewport.setZoom(percentage)

board.viewport.setZoom(integer)

board.viewport.getZoom()

board.viewport.getZoom()

board.viewport.getScale()
Not available in v2

Widgets / Items

In the Miro Web SDK v1, the widget methods were polymorphic – meaning that one method was used to interact with all potential widget types. The structure of the call would differ depending on what type of widget you were creating or updating. In the v2 SDK, we have replaced this with independent endpoints for each item type. Widgets are now referred to as "items" and each item exists as its own object, rather than as a property of the board object.

widgets.update() and the new sync() method

Every item type has a sync() method. All item updates are now handled through [item].sync() rather than board.widgets.update(). For more information on the sync() method and an explanation of its usage, please refer to this guide.

The following table shows an example of updating the title of a card item in both v1 and v2.

Updating widgets in v1Updating items in v2
board.widgets.update({
    id: myCard.id,
    title: "New Card Title"
})

myCard.title = "New Card Title"
myCard.sync()

board.widgets endpoints

With the removal of the board.widgets property in the v2 Web SDK, the methods contained in the boards.widget namespace have moved to the board object in v2. The board.widgets.create() and board.widgets.update() methods are discussed separately in this guide, but the remaining methods can be found in the table below, side-by-side with their v2 counterparts.

v1 widget methodsv2 equivalents
board.widgets.get()












board.get()

or

board.getById()

The v2 SDK offers the same support as the v1 SDK for fetching items. The response can be all of the items on the board, one item specifically, or a subset of items matching a particular set of filters. Filters include item type, associated tags, etc. For more examples and a full reference of possible filters, please see the Web SDK reference documentation.

board.widgets.bringForward(myWidget.id)




board.bringToFront(myItem)

ℹ️ Note:

  • Where v1 required the object’s ID as a parameter, v2 requires one or more item objects as a parameter.
board.widgets.sendBackward(myWidget.id)




board.sendToBack(myItem)

ℹ️ Note:

  • Where v1 required the object’s ID as a parameter, v2 requires one or more item objects as a parameter.
board.widgets.deleteById(myWidget.id)




board.remove(myItem)

ℹ️ Note:

  • Where v1 required the object’s ID as a parameter, v2 requires the item object as a parameter.
board.widgets.images.get()


board.get({
    type: image
})

board.widgets.areAllWidgetsLoaded()
Not available in v2
board.widgets.transformDelta()
Not available in v2

Widget / Item properties

In the v2 Web SDK, each item type has its own defined set of properties, directly applicable to that item. These properties would include data unique to the item, such as the type of shape, or style options like color choices. Other properties are universal to all item types, such as geometry or positioning information.

The table below enumerates the various item properties as they exist in both v1 and v2, beginning with the universal properties, and then moving into type-specific properties.

Widget properties in v1Item properties in v2
Basic information
  • id

  • id
  • parentId
  • createdUserId
  • lastModifiedUserId


  • createdBy
  • modifiedBy
  • createdAt
  • modifiedAt
  • groupId
  • capabilities
  • clientVisible
  • metadata
  • scale
  • metadata
Geometry / Position information
  • bounds
    • x- and y- coordinates
    • height and width
    • bottom and top
    • left and right
  • rotation


  • x- and y- coordinates
  • origin
  • height and width
  • rotation

ℹ️ Note:

  • The bounds object is no longer available in v2.
  • origin is new in v2 and denotes both the origin point for positioning and the pivot point for rotation.
Type-specific information

Card

  • type: card
  • title
  • description
  • date
  • assignee
  • tags
  • style
    • backgroundColor
  • card
    • customFields
    • logo

Card

  • type: card
  • title
  • description
  • dueDate
  • assignee
    • userId
  • tagIds
  • taskStatus
  • style
    • cardTheme
    • fillBackground
  • fields
    • value
    • iconUrl
    • iconShape
    • fillColor
    • textColor
    • tooltip

ℹ️ Note:

  • You can also create custom cards with AppCard.

Embed

  • type: embed
  • html


Embed

  • type: embed
  • url
  • previewUrl
  • mode

Frame

  • type: frame
  • title
  • childrenIds
  • style
    • backgroundColor
  • frameIndex


Frame

  • type: frame
  • title
  • childrenIds
  • style
    • fillColor

ℹ️ Note:

  • frameIndex is not available in the v2 SDK.
  • style.backgroundColor has been renamed to style.fillColor.

Image

  • type: image
  • title
  • url

Image

  • type: image
  • title
  • url

Line

  • type: line
  • captions
  • endPosition
  • endWidgetId
  • startPosition
  • startWidgetId
  • style
    • lineColor
    • lineEndStyle
    • lineStartStyle
    • lineStyle
    • lineThickness
    • lineType

Connector

  • type: connector
  • shape
  • style
    • startStrokeCap
    • endStrokeCap
    • strokeStyle
    • strokeColor
    • strokeWidth
    • color
    • fontSize
    • textOrientation
  • start
    • item
    • position
  • end
    • item
    • position
  • captions

Preview

  • type: preview
  • url

Preview

  • type: preview
  • url

Shape

  • type: shape
  • text - supports basic HTML
  • plainText - content without HTML tags
  • style
    • shapeType
    • backgroundColor
    • fontFamily
    • fontSize
    • textAlign
    • textAlignVertical
    • textColor
    • backgroundOpacity
    • borderColor
    • borderOpacity
    • borderStyle
    • borderWidth
    • bold
    • highlighting
    • italic
    • strike
    • underline

Shape

  • type: shape
  • content
  • shape
  • style
    • color
    • fillColor
    • fontFamily
    • fontSize
    • textAlign
    • textAlignVertical
    • borderStyle
    • borderOpacity
    • borderColor
    • borderWidth
    • fillOpacity

ℹ️ Note:
  • style.shapeType in v1 is now shape in v2.
    The property has been renamed, and moved out of the style object.
  • text has been renamed to content
  • plainText has been removed from v2.
  • style.backgroundColor has been renamed to style.fillColor.

Sticker

  • type: sticker
  • text - supports basic HTML
  • plainText - content without HTML tags
  • tags
  • style
    • stickerType: square or rectangle
    • stickerBackgroundColor
    • textAlign
    • textAlignVertical
    • fontFamily
    • fontSize






Sticky Note

  • type: sticky_note
  • content
  • tagIds
  • shape: square or rectangle
  • style
    • fillColor
    • textAlign
    • textAlignVertical

ℹ️ Note:

  • text has been renamed to content
  • plainText has been removed from v2.
  • style.stickerType in v1 is now shape in v2.
    The property has been renamed, and moved out of the style object.
  • style.fontFamily and style.fontSize for sticky notes are no longer supported in v2.
  • style.stickerBackgroundColor has been renamed to style.fillColor

Text

  • type: text
  • text
  • style
    • backgroundColor
    • backgroundOpacity
    • fontFamily
    • textAlign
    • textColor
    • padding
    • borderColor
    • borderOpacity
    • borderStyle
    • borderWidth
    • bold
    • highlighting
    • italic
    • strike
    • underline

Text

  • type: text
  • content
  • style
    • color
    • fillColor
    • fillOpacity
    • fontFamily
    • fontSize
    • textAlign

ℹ️ Note:
  • text has been renamed to content.
  • style.backgroundColor and style.backgroundOpacity have been renamed to style.fillColor and style.fillOpacity
  • Padding, borders and emphasis are not yet supported in v2.





"Unsupported" item types

For board items that are not yet supported in the Miro v2 Web SDK, there is an unsupported item type, which serves as a catch-all object. It does not offer any item-specific properties, but it does have a sync() method. This allows applications to interact with unsupported board objects, including moving or relocating these objects.

Currently, the following item types are not yet supported in the v2 SDK.

We will be adding new item types over time, and we will continue to share updates as we make progress. There are several feature requests already noted on our roadmap, and we encourage you to add your votes and subscribe to future updates. You’re also welcome to raise any questions or concerns in our developer Discord or on our community forum.

Tags

As with the v1 board.widgets property, board.tags is no longer a supported property in the v2 SDK. Tags now exist as their own object, rather than as a property of the board object.

Creating a tag

Although tags are not considered to be items on a Miro board, the new item constructor approach has also been used to create a tag constructor. A side-by-side comparison of the v1 and v2 constructions can be found in the table below.

Tag creation in v1Tag creation in v2
board.tags.create({
    title: "Hello, tag", 
    color: "yellow"
})

board.createTag({
    title: "Hello, tag", 
    color: "yellow"
})

Updating a tag

Similar to items, tag objects each have a sync() method. All tag updates are now handled through [tag].sync() rather than board.tags.update(). For more information on the sync() method and an explanation of its usage, please refer to this guide.

The following table shows an example of updating a tag in both v1 and v2.

Updating tags in v1Updating tags in v2
board.tags.update({
    id: myTag.id,
    title: "New Tag Title"
})

myTag.title = "New Tag Title"
myTag.sync()

Working with tags

Aside from the new create and update implementations, tags are similar across the v1 and v2 SDKs. The most significant change lies in how tags and items are associated. In the v1 Web SDK, a tag was assigned to a widget by adding the widget’s ID to the tag object. In the v2 Web SDK, this has been reversed to the more intuitive approach, where a tag’s ID is added to an item object.

For this, and other side-by-side comparisons of tags across v1 and v2, see the table below.

Tag properties

  • id
  • title
  • color
  • widgetIds





Tag properties

  • type: tag
  • id
  • title
  • color

ℹ️ Note:

  • SDK v2 introduces the type: tag property, but removes the widgetIds property. Instead, tag and item associations can be found in the tagIds property of the item.
board.tags.get()








board.get({type: "tag"})

ℹ️ Note:

  • Because tag objects in v2 no longer include the widgetIds property, this is not a full equivalent of the v1 board.tags.get() method.
    This approach will still return an array of all of the tags on the board.
    However, there is not currently a way to get all of the items that have been tagged.
    This is a known issue.
board.tags.delete(myTag.id)

board.remove(myTag)

Info

In the Miro v1 Web SDK, board.info served as the namespace for methods related to getting board information. However, there was only one supported method in this namespace: board.info.get().
This has been removed in v2, as there is not a need for a dedicated namespace for board information.

Board information can now be retrieved using the board.getInfo() method, as shown in the table below. Unfortunately, the v2 board info object is pretty bare compared to its v1 counterpart. This is a known issue, and the board info objects have been included in the table below for clarity.

Board Info in v1Board Info in v2
board.info.get()

board.getInfo()

Board Info object properties

  • id
  • title
  • description
  • owner
  • picture
  • currentUserPermissions
  • lastModifyingUser
  • lastViewedByMeDate
  • modifiedByMeDate
  • createdAt
  • updatedAt

Board Info object properties

  • id
  • createdAt
  • updatedAt










Selection

In the v1 Web SDK, board.selection served as the namespace for methods that interacted with the selection of certain widgets on the board. In v2, the equivalent methods are board.getSelection, board.select, and board.deselect.

The table below provides a side-by-side comparison of the v1 board.selection property and its v2 counterpart (if available).

Selections in v1Selections in v2
board.selection.get()

board.getSelection()

board.enterSelectWidgetsMode()
Not available in the v2 Web SDK
board.selection.selectWidgets(myWidget.id)

board.select(myWidget.id)

board.selection.clear()

board.deselect(myWidget.id)

Utils

In the v1 Miro Web SDK, board.utils served as the namespace for utility methods for a board. This property has been removed in v2, as there is not a need for a dedicated namespace for board utility functions.

Specifically, in the v1 SDK, there was only one supported method in this namespace: board.utils.unionWidgetBounds(). With v2, the bounds object is no longer a property of board items, rendering the sole utility method obsolete.

v1v2
board.utils.unionWidgetBounds()
Not available in the v2 Web SDK

The V2 Web SDK has, however, started to introduce some similar utility-type methods, such as findEmptySpace. This method can be accessed from the experimental namespace, and allows you to programmatically find empty space on a Miro board when positioning items. See findEmptySpace.

Users and Accounts

The v1 Web SDK offered several endpoints for working with users and accounts, including the UserInfo object, Account Info object, and several methods, including:

  • .account.get()
  • .currentUser.getScopes()
  • .currentUser.isSignedIn()
  • .currentUser.getCurrentBoardPermissions()
  • .currentUser.getCurrentAccountPermissions()
  • .currentUser.isMemberOfCurrentAccount()

None of these are available in the Miro v2 Web SDK. When building the v2 platform, all enterprise methods have been moved to the REST API. The Web SDK will no longer offer any endpoints that require a Team or Organization authorization scope.

However, applications can still retrieve the context and information of the current authenticated user by using board.getUserInfo(). An example of this method, and its v1 counterpart, is provided in the table below.

v1v2
.currentUser.getId()





board.getUserInfo()

ℹ️Note:

  • While the v1 method returns the user ID of the current user, the v2 board.getUserInfo() method returns a user object containing the user ID.

The V2 SDK also introduces a new method to retrieve users who are currently active on a board. See getOnlineUsers.

Additional capabilities in V2

There are several additional capabilities that are now supported in the V2 Web SDK, including:

We will continue to expand support for new capabilities in our V2 Web SDK. Stay up to date with our changelog for the latest developments.

New namespaces in V2

The V2 Web SDK introduces a couple of new namespaces.

Experimental

The experimental namespace, miro.board.experimental, is where certain experimental features or methods will be exposed as an early preview. These methods should not be relied on in a production environment.

Features or methods that are experimental in v2 will be reflected with an experimental tag in the reference documentation.

Collaboration

The collaboration namespace, miro.board.collaboration, is where new features or methods related to collaborative experiences will be exposed. See Collaboration.

V1 experimental methods

Some of the experimental methods from the v1 Web SDK are now fully supported in v2. For those that were not upgraded to become permanent parts of the v2 platform, we have removed the methods from our SDK. This is an attempt to clean up erroneous code, and to ensure a consistent developer experience.

The removed methods are listed below.

  • board.__getParamsFromURL()
  • board.widgets.__blinkWidget()
  • board.widgets.__getIntersectedObjects()
  • board.comments.get()

If any of these methods were critical to your v1 application, or if you have any other questions or concerns, please reach out. You can post in our community forum, start a discussion in our developer Discord, or suggest and vote on new features in our public roadmap.